diff --git a/doc/pages/command-parsing.asciidoc b/doc/pages/command-parsing.asciidoc index aebe9eba..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,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 - <> + 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 a14877a5..36e5d020 100644 --- a/doc/pages/expansions.asciidoc +++ b/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 +<> +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