Merge remote-tracking branch 'lePerdu/expansion-docs'

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,21 +72,21 @@ 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 `\\`.
 
 == 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.
+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.
 
 - If the *expansion type* is one of `sh`, `reg`, `opt`, `val` or `arg`,
-  The string is expanded according as described in
-  <<expansions#typed-expansions,`:doc expansion typed-expansions`>>
+  The string is expanded as described in <<expansions#,`:doc expansions`>>
 
 - For any other *expansion type* a parsing error is raised.

doc/pages/expansions.asciidoc

@@ -6,15 +6,39 @@ 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 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 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.
+
+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
-inside %-strings or other expansions. So:
+inside %-strings or other expansions (see
+<<command-parsing#typed-expansions, `:doc command-parsing typed-expansions`>>
+for full details). For example:
 
 * `echo %val{session}` echoes the current session ID
 
@@ -31,10 +55,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. 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