From 3abb1729d86edf007c6a9590dfd9f2fd2e141274 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Thu, 14 Nov 2024 14:35:30 +0100 Subject: [PATCH 1/2] use quote in backticks rather than escape --- ...ions-additions-removals-compatibility.adoc | 28 +++++++++---------- modules/ROOT/pages/styleguide.adoc | 2 +- modules/ROOT/pages/syntax/naming.adoc | 10 +++---- modules/ROOT/pages/syntax/reserved.adoc | 2 +- 4 files changed, 21 insertions(+), 21 deletions(-) diff --git a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc index 6250cc475..9decf9b67 100644 --- a/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc +++ b/modules/ROOT/pages/deprecations-additions-removals-compatibility.adoc @@ -49,8 +49,8 @@ MATCH (where {...}) ---- MATCH (...)-[where {...}]->() ---- -a| The unescaped variable named `where` (or any casing variant, like `WHERE`) used in a node or relationship pattern followed directly by a property key-value expression is deprecated. -To continue using variables with this name, use backticks to escape the variable name: +a| The variable named `where` (or any casing variant, like `WHERE`) used in a node or relationship pattern followed directly by a property key-value expression is deprecated. +To continue using variables with this name, use backticks to quote the variable name: * Node patterns: `MATCH (++`where`++ { ... })` * Relationship patterns: `MATCH (...)-[++`where`++ { ... }]->()` @@ -78,8 +78,8 @@ label:deprecated[] ---- CASE x ... WHEN is :: STRING THEN ... END ---- -a| Using an unescaped variable named `is` (or any casing variant, like `IS`) as a `WHEN` operand in a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated. -To continue using variables with this name in simple `CASE` expressions, use backticks to escape the variable name: `CASE x ... WHEN ++`is`++ :: STRING THEN ... END` +a| Using a variable named `is` (or any casing variant, like `IS`) as a `WHEN` operand in a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated. +To continue using variables with this name in simple `CASE` expressions, use backticks to quote the variable name: `CASE x ... WHEN ++`is`++ :: STRING THEN ... END` a| label:functionality[] @@ -91,8 +91,8 @@ CASE x ... WHEN contains + 1 THEN ... END ---- CASE x ... WHEN contains - 1 THEN ... END ---- -a| Using an unescaped variable named `contains` (or any casing variant, like `CONTAINS`) in addition or subtraction operations within a `WHEN` operand of a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated. -To continue using variables with this name, use backticks to escape the variable name: +a| Using a variable named `contains` (or any casing variant, like `CONTAINS`) in addition or subtraction operations within a `WHEN` operand of a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated. +To continue using variables with this name, use backticks to quote the variable name: * Additions: `CASE x ... WHEN ++`contains`++ + 1 THEN ... END` * Subtractions: `CASE x ... WHEN ++`contains`++ - 1 THEN ... END` @@ -107,8 +107,8 @@ CASE x ... WHEN in[1] THEN ... END ---- CASE x ... WHEN in["abc"] THEN ... END ---- -a| Using the `[]` operator on an unescaped variable named `in` (or any casing variant, like `IN`) within a `WHEN` operand of a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated. -To continue using variables with this name, use backticks to escape the variable name: +a| Using the `[]` operator on a variable named `in` (or any casing variant, like `IN`) within a `WHEN` operand of a xref:queries/case.adoc#case-simple[simple `CASE`] expression is deprecated. +To continue using variables with this name, use backticks to quote the variable name: * `CASE x ... WHEN ++`in`++[1] THEN ... END` * `CASE x ... WHEN ++`in`++["abc"] THEN ... END` @@ -1000,9 +1000,9 @@ label:deprecated[] RETURN 1 as my\u0085identifier ---- a| -The Unicode character \`\u0085` is deprecated for unescaped identifiers and will be considered as a whitespace character in the future. -To continue using it, escape the identifier by adding backticks around the identifier. -This applies to all unescaped identifiers in Cypher, such as label expressions, properties, variable names or parameters. +The Unicode character \`\u0085` is deprecated for identifiers not quoted in backticks and will be considered as a whitespace character in the future. +To continue using it, quote the identifier with backticks. +This applies to all identifiers in Cypher, such as label expressions, properties, variable names or parameters. In the given example, the quoted identifier would be \`my�identifier`. a| @@ -1013,8 +1013,8 @@ label:deprecated[] RETURN 1 as my$Identifier ---- a| -The character with the Unicode representation \`\u0024` is deprecated for unescaped identifiers and will not be supported in the future. To continue using it, escape the identifier by adding backticks around the identifier. -This applies to all unescaped identifiers in Cypher, such as label expressions, properties, variable names or parameters. In the given example, the quoted identifier would be \`my$identifier`. +The character with the Unicode representation \`\u0024` is deprecated for identifiers not quoted in backticks and will not be supported in the future. To continue using it, quote the identifier with backticks. +This applies to all identifiers in Cypher, such as label expressions, properties, variable names or parameters. In the given example, the quoted identifier would be \`my$identifier`. The following Unicode Characters are deprecated in identifiers: '\u0000', '\u0001', '\u0002', '\u0003', '\u0004', '\u0005', '\u0006', '\u0007', @@ -2682,7 +2682,7 @@ label:deprecated[] CREATE DATABASE databaseName.withDot ... ---- a| -Creating a database with unescaped dots in the name has been deprecated, instead escape the database name: +Creating a database with dots in the name has been deprecated, instead quote the database name using backticks: [source, cypher, role="noheader"] ---- diff --git a/modules/ROOT/pages/styleguide.adoc b/modules/ROOT/pages/styleguide.adoc index 0874703f7..a6d0d48f0 100644 --- a/modules/ROOT/pages/styleguide.adoc +++ b/modules/ROOT/pages/styleguide.adoc @@ -472,7 +472,7 @@ RETURN 'Cypher\'s a nice language', "Mats' quote: \"statement\"" RETURN "Cypher's a nice language", 'Mats\' quote: "statement"' ---- -* Avoid having to use back-ticks to escape characters and keywords. +* Avoid having to use backticks to quote characters and keywords. .Bad [source, cypher] diff --git a/modules/ROOT/pages/syntax/naming.adoc b/modules/ROOT/pages/syntax/naming.adoc index 4f70b12f7..2d25bcc7f 100644 --- a/modules/ROOT/pages/syntax/naming.adoc +++ b/modules/ROOT/pages/syntax/naming.adoc @@ -25,23 +25,23 @@ For example, `MATCH ( a ) RETURN a` is equivalent to `MATCH (a) RETURN a`. [[symbolic-names-escaping-rules]] === Using special characters in names -Non-alphabetic characters, including numbers, symbols and whitespace characters, *can* be used in names, but *must* be escaped using backticks. +Non-alphabetic characters, including numbers, symbols and whitespace characters, *can* be used in names, but *must* be quoted using backticks. For example: `++`^n`++`, `++`1first`++`, `++`$$n`++`, and `++`my variable has spaces`++`. -Database names are an exception and may include dots without the need for escaping, although this behavior is deprecated as it may introduce ambiguity when addressing composite databases. +Database names are an exception and may include dots without the need for quoting using backticks, although this behavior is deprecated as it may introduce ambiguity when addressing composite databases. For example: naming a database `foo.bar.baz` is valid, but deprecated. `++`foo.bar.baz`++` is valid. -Within an escaped name, the following escaping sequences are allowed: +Within a name quoted by backticks, the following character representations are allowed: [options="header", cols=">1,<2"] |=== -|Escape sequence|Character +|Q sequence|Character |````| Backtick |`\uxxxx`| Unicode UTF-16 code point (4 hex digits must follow the `\u`) |=== [NOTE] ==== -Using escaped names with unsanitized user input makes you vulnerable to Cypher injection. +Using names quoted in backticks with unsanitized user input makes you vulnerable to Cypher injection. Some techniques to mitigate this are: * sanitizing (and validating) the user input. diff --git a/modules/ROOT/pages/syntax/reserved.adoc b/modules/ROOT/pages/syntax/reserved.adoc index e38ba0ed2..5e4a73d2f 100644 --- a/modules/ROOT/pages/syntax/reserved.adoc +++ b/modules/ROOT/pages/syntax/reserved.adoc @@ -16,7 +16,7 @@ The reserved keywords are not permitted to be used as identifiers in the followi * Function names * Parameters -If any reserved keyword is escaped -- i.e. is encapsulated by backticks ```, such as `++`AND`++` -- it would become a valid identifier in the above contexts. +If any reserved keyword is quoted in backticks (```), such as `++`AND`++`, it would become a valid identifier in the above contexts. == Clauses From 9406fafad7a20aff0df51a68addb8e5af1ef95b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?= <112686610+JPryce-Aklundh@users.noreply.github.com> Date: Thu, 14 Nov 2024 15:50:32 +0100 Subject: [PATCH 2/2] update --- modules/ROOT/pages/styleguide.adoc | 2 +- modules/ROOT/pages/syntax/naming.adoc | 2 +- modules/ROOT/pages/syntax/reserved.adoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/styleguide.adoc b/modules/ROOT/pages/styleguide.adoc index a6d0d48f0..bff296f2e 100644 --- a/modules/ROOT/pages/styleguide.adoc +++ b/modules/ROOT/pages/styleguide.adoc @@ -472,7 +472,7 @@ RETURN 'Cypher\'s a nice language', "Mats' quote: \"statement\"" RETURN "Cypher's a nice language", 'Mats\' quote: "statement"' ---- -* Avoid having to use backticks to quote characters and keywords. +* Avoid using characters and keywords that require the input to be quoted with backticks. .Bad [source, cypher] diff --git a/modules/ROOT/pages/syntax/naming.adoc b/modules/ROOT/pages/syntax/naming.adoc index 2d25bcc7f..a483e62f7 100644 --- a/modules/ROOT/pages/syntax/naming.adoc +++ b/modules/ROOT/pages/syntax/naming.adoc @@ -34,7 +34,7 @@ Within a name quoted by backticks, the following character representations are a [options="header", cols=">1,<2"] |=== -|Q sequence|Character +| Character representation | Description |````| Backtick |`\uxxxx`| Unicode UTF-16 code point (4 hex digits must follow the `\u`) |=== diff --git a/modules/ROOT/pages/syntax/reserved.adoc b/modules/ROOT/pages/syntax/reserved.adoc index 5e4a73d2f..fe298c19b 100644 --- a/modules/ROOT/pages/syntax/reserved.adoc +++ b/modules/ROOT/pages/syntax/reserved.adoc @@ -16,7 +16,7 @@ The reserved keywords are not permitted to be used as identifiers in the followi * Function names * Parameters -If any reserved keyword is quoted in backticks (```), such as `++`AND`++`, it would become a valid identifier in the above contexts. +If any reserved keyword is quoted in backticks (```), such as `++`AND`++`, it would become a valid identifier in the above contexts; however, this approach is not recommended. == Clauses