From 5a4ba0b35ff80a8de44adda4f7c7235b93b852d4 Mon Sep 17 00:00:00 2001 From: lePerdu Date: Wed, 30 Jan 2019 15:46:40 -0500 Subject: [PATCH 1/6] Update and clarify expansion/quoting docs --- doc/pages/expansions.asciidoc | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc index a14877a5..56bda28a 100644 --- a/doc/pages/expansions.asciidoc +++ b/doc/pages/expansions.asciidoc @@ -6,11 +6,33 @@ associated value before executing the command. These patterns are called expansions. Every expansion consists of a `%`, followed by the expansion _type_ (one -or more alphabetic characters), a nestable punctuation character (`(`, `[`, -`{`, or `<`), and then all the text up to and including its matching opposite -(`)`, `]`, `}`, or `>`). It doesn't matter which character is used, but -`{}` are most common. For example, the command `echo %val{session}` will -echo the ID of the current Kakoune session. +or more alphabetic characters), a quoting character, and then all the text +up to and including its matching character. + +If an openning brace (`(`, `[`, `{`, or `<`) is used as the openning quoting +character, the expansion will end at the character's matching brace (`)`, `]`, +`}`, or `>`). Nested pairs of the braces used in the expansion are allowed, but +they must be balanced. Braces other than the ones used in the expansion need +not be balanced, however. For example, `%{nest{ed} non[nested}` is valid and +expands to `nest{ed} non[nested`. + +If any other character is used, the expansion will end at the next occurance of +that character. The quoting character can be escpaed inside the expansion if it +is doubled-up. For example, `%|abc||def|` expands to the text `abc|def`. + +It doesn't matter which character is used, but `{}` are most common. + +There are 2 types of quoting which can be used to group together words separated +by whitespace into a single argument or prevent expansions from expanding: + +"double quoted strings":: + Double quoted strings are mainly for grouping multiple `%` expansions or + `%` expansions and regular text as a single argument. `%` and `"` can be + escaped by doubling the characters (i.e. `%%` and `""`). + +'single quoted strings':: + Expansions are not processed inside single quoted strings. Single quotes can + be escaped by doubling up (i.e. `''`). Expansions are processed when unquoted and anywhere inside double-quoted strings, but not inside unquoted words, inside single-quoted strings, or From a7320a01aace280117d81a52dab2fa4162ef2d24 Mon Sep 17 00:00:00 2001 From: lePerdu Date: Wed, 30 Jan 2019 16:17:45 -0500 Subject: [PATCH 2/6] Specify only lists can expand to multiple args --- doc/pages/expansions.asciidoc | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc index 56bda28a..5907911d 100644 --- a/doc/pages/expansions.asciidoc +++ b/doc/pages/expansions.asciidoc @@ -54,9 +54,10 @@ Like "variable expansion" and "command substitution" in shell programming, Kakoune expansions can expand to multiple "words" - that is, separate arguments on the resulting command-line. However, unlike shell programming, Kakoune expansions cannot _accidentally_ expand to multiple words, even if -the expansion contains whitespace or other special characters. While in -shell-programming it's good practice to always wrap expansions in -double-quotes, in Kakoune it's perfectly safe to leave expansions unquoted. +the expansion contains whitespace or other special characters: only list types +can expand to multiple arguments. While in shell-programming it's good practice +to always wrap expansions in double-quotes, in Kakoune it's perfectly safe to +leave expansions unquoted. == Argument expansions From db4bb6788d1aaea5d5a08f890e59b2bd3892f9ae Mon Sep 17 00:00:00 2001 From: lePerdu Date: Wed, 30 Jan 2019 20:55:37 -0500 Subject: [PATCH 3/6] Make word splitting description more precise --- doc/pages/expansions.asciidoc | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc index 5907911d..833e8de8 100644 --- a/doc/pages/expansions.asciidoc +++ b/doc/pages/expansions.asciidoc @@ -53,11 +53,12 @@ inside %-strings or other expansions. So: Like "variable expansion" and "command substitution" in shell programming, Kakoune expansions can expand to multiple "words" - that is, separate arguments on the resulting command-line. However, unlike shell programming, -Kakoune expansions cannot _accidentally_ expand to multiple words, even if -the expansion contains whitespace or other special characters: only list types -can expand to multiple arguments. While in shell-programming it's good practice -to always wrap expansions in double-quotes, in Kakoune it's perfectly safe to -leave expansions unquoted. +Kakoune expansions cannot _accidentally_ expand to multiple words because they +contain whitespace or other special characters. Only expansions which +semantically contain a list of values (list-type options, registers, selections, +etc.) expand to multiple arguments. While in shell-programming it's good +practice to always wrap expansions in double-quotes, in Kakoune it's perfectly +safe to leave expansions unquoted. == Argument expansions From deda1595366e87c25362ea2da33eb7bdefa42c18 Mon Sep 17 00:00:00 2001 From: lePerdu Date: Wed, 30 Jan 2019 21:02:19 -0500 Subject: [PATCH 4/6] Change "brace" back to "nestable punctuation" --- doc/pages/expansions.asciidoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc index 833e8de8..b1a22931 100644 --- a/doc/pages/expansions.asciidoc +++ b/doc/pages/expansions.asciidoc @@ -9,15 +9,15 @@ Every expansion consists of a `%`, followed by the expansion _type_ (one or more alphabetic characters), a quoting character, and then all the text up to and including its matching character. -If an openning brace (`(`, `[`, `{`, or `<`) is used as the openning quoting -character, the expansion will end at the character's matching brace (`)`, `]`, -`}`, or `>`). Nested pairs of the braces used in the expansion are allowed, but -they must be balanced. Braces other than the ones used in the expansion need -not be balanced, however. For example, `%{nest{ed} non[nested}` is valid and -expands to `nest{ed} non[nested`. +If a nestable punctuation character (`(`, `[`, `{`, or `<`) is used as the +opening quoting character, the expansion will end at its matching opposite +(`)`, `]`, `}`, or `>`). Nested pairs of the braces used in the expansion are +allowed, but they must be balanced. Braces other than the ones used in the +expansion need not be balanced, however. For example, `%{nest{ed} non[nested}` +is valid and expands to `nest{ed} non[nested`. -If any other character is used, the expansion will end at the next occurance of -that character. The quoting character can be escpaed inside the expansion if it +If any other character is used, the expansion will end at the next occurrence of +that character. The quoting character can be escaped inside the expansion if it is doubled-up. For example, `%|abc||def|` expands to the text `abc|def`. It doesn't matter which character is used, but `{}` are most common. From a5f865a5668a21748d153b5bf4848ddca3d25d43 Mon Sep 17 00:00:00 2001 From: lePerdu Date: Thu, 31 Jan 2019 08:31:48 -0500 Subject: [PATCH 5/6] Add/fix cross-references for expansions --- doc/pages/command-parsing.asciidoc | 5 ++--- doc/pages/expansions.asciidoc | 4 +++- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/pages/command-parsing.asciidoc b/doc/pages/command-parsing.asciidoc index aebe9eba..02b02b86 100644 --- a/doc/pages/command-parsing.asciidoc +++ b/doc/pages/command-parsing.asciidoc @@ -63,7 +63,7 @@ is treated as a literal `\\`. == Typed Expansions -Quoted and Balanced strings startings with `%` might have an optional +Quoted and Balanced strings starting with `%` might have an optional alphabetic *expansion type* between the `%` and their delimiter (which is always a punctuation character). This *expansion type* defines how the string content is going to be expanded. @@ -71,7 +71,6 @@ string content is going to be expanded. - If the *expansion type* is empty, the string content is used verbatim. - If the *expansion type* is one of `sh`, `reg`, `opt`, `val` or `arg`, - The string is expanded according as described in - <> + The string is expanded as described in <> - For any other *expansion type* a parsing error is raised. diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc index b1a22931..36e5d020 100644 --- a/doc/pages/expansions.asciidoc +++ b/doc/pages/expansions.asciidoc @@ -36,7 +36,9 @@ by whitespace into a single argument or prevent expansions from expanding: Expansions are processed when unquoted and anywhere inside double-quoted strings, but not inside unquoted words, inside single-quoted strings, or -inside %-strings or other expansions. So: +inside %-strings or other expansions (see +<> +for full details). For example: * `echo %val{session}` echoes the current session ID From 665d90b9bbcdcd789ff81e23daa3579291623424 Mon Sep 17 00:00:00 2001 From: lePerdu Date: Thu, 31 Jan 2019 08:41:58 -0500 Subject: [PATCH 6/6] Document escaping %-strings and add more examples --- doc/pages/command-parsing.asciidoc | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/doc/pages/command-parsing.asciidoc b/doc/pages/command-parsing.asciidoc index 02b02b86..dcf3724f 100644 --- a/doc/pages/command-parsing.asciidoc +++ b/doc/pages/command-parsing.asciidoc @@ -15,20 +15,31 @@ If a word starts with `'`, `"` or `%X` with `X` a non nestable punctuation character it is parsed as a quoted string whose delimiter is, respectively, `'`, `"` or `X`. -A quoted string contains every characters (including whitespaces) until +A quoted string contains every character (including whitespaces) until its closing delimiter. If its closing delimiter is doubled, then it is considered to be part of the string content as a single delimiter. +Inside double quotes, `%`-strings are processed unless the `%` is escaped by +doubling it. Double quotes inside these nested strings must still be escaped. + No other escaping takes place in quoted strings. === Quoted Strings Examples -- `'foo'` contents is *foo* +- `'foo'` contains *foo* + +- `foo'bar'` is read verbatim, so it contains *foo'bar'* + +- `foo%|bar|` is read verbatim, so it contains *foo%|bar|*. - `'foo''bar'` is a single word whose content is *foo'bar* - `"baz"""` is a single word whose content is *baz"*. +- `%|foo||bar|` is a single word whose content is *foo|bar*. + +- `"foo %|""bar| %%,baz,"` is a single word whose content is *foo "bar %,baz,*. + == Balanced Strings If a word starts with `%X` with `X` a nestable punctuation character (one @@ -45,9 +56,13 @@ No other escaping takes place in balanced strings. === Balanced Strings Examples -- `%{foo}` contents is *foo* +- `%{foo}` contains *foo* -- `%{foo\{bar}}` contents is *foo\{bar}* +- `%{foo\{bar}}` contains *foo\{bar}* + +- `foo%{bar}` contains *foo%{bar}* + +- `"foo %{bar}"` is a single word whose content is *foo bar* == Non Quoted words @@ -57,7 +72,7 @@ or a `;`. If they start with `\\` followed by `%`, `'` or `"`, then that leading `\\` is discarded. -If a whitespace or `;` is preceeded by `\\`, then the `\\` is discarded +If a whitespace or `;` is preceded by `\\`, then the `\\` is discarded and the whitespace or `;` becomes part of the word. Any other `\\` is treated as a literal `\\`. @@ -66,7 +81,8 @@ is treated as a literal `\\`. Quoted and Balanced strings starting with `%` might have an optional alphabetic *expansion type* between the `%` and their delimiter (which is always a punctuation character). This *expansion type* defines how the -string content is going to be expanded. +string content is going to be expanded. Rules for expanding and escaping typed +expansions are the same as for `%`-strings. - If the *expansion type* is empty, the string content is used verbatim.