diff --git a/doc/pages/command-parsing.asciidoc b/doc/pages/command-parsing.asciidoc index e4b62123..bd585292 100644 --- a/doc/pages/command-parsing.asciidoc +++ b/doc/pages/command-parsing.asciidoc @@ -1,38 +1,40 @@ = Command Parsing -Kakoune commands, either loaded from a script, or written in the command -prompt are parsed according to the following rules: +Kakoune commands, either loaded from a script or written in the command +prompt, are parsed according to the following rules: == Basic parsing -- Commands are separated by `;` or end of lines +- Commands are terminated by a `;` or an end of line. -- Words (command names and parameters) are separated by whitespaces +- Words (command names and parameters) are delimited by whitespaces. == Quoted Strings -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`. +If a word starts with `'`, `"`, or `%X` with `X` a _non-nestable_ punctuation +character (see below for nestable characters), it is parsed as a quoted +string whose delimiter is, respectively, `'`, `"`, or `X`. -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. +A quoted string contains every character (including whitespaces). Doubling +a closing delimiter escapes it. Thus, for example, entering two closing +delimiters at the end of a quoted string will render one of the characters +literally; that is, it will be considered as part of the quoted string's +content. Inside double quotes, `%`-strings are processed unless the `%` is escaped by -doubling it. Double quotes inside these nested strings must still be escaped. +doubling it. Double quotes inside these nested strings must also be escaped. No other escaping takes place in quoted strings. === Quoted Strings Examples -- `'foo'` contains *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 read verbatim, so it contains *foo%|bar|*. -- `'foo''bar'` is a single word whose content is *foo'bar* +- `'foo''bar'` is a single word whose content is *foo'bar*. - `"baz"""` is a single word whose content is *baz"*. @@ -42,51 +44,46 @@ No other escaping takes place in quoted strings. == Balanced Strings -If a word starts with `%X` with `X` a nestable punctuation character (one +If a word starts with `%X` with `X` a _nestable_ punctuation character (one of `(`, `[`, `{` and `<`), it is parsed as a balanced string whose closing -delimiter is the matching character of its opening delimiter (respectively -`)`, `]`, `}` and `>`). +delimiter matches that of its opening delimiter (respectively, `)`, `]`, +`}`, and `>`). -A balanced string contains every character (including whitespaces) until -a closing delimiter is found, and opening and closing delimiters are -balanced inside the string (each opening delimiter appearing inside the -string have been closed by a matching closing delimiter). - -No other escaping takes place in balanced strings. +Characters may be escaped in the same manner as those for quoted strings. === Balanced Strings Examples -- `%{foo}` contains *foo* +- `%{foo}` contains *foo*. -- `%{foo\{bar}}` contains *foo\{bar}* +- `%{foo\{bar}}` contains *foo\{bar}*. -- `foo%{bar}` contains *foo%{bar}* +- `foo%{bar}` contains *foo%{bar}*. -- `"foo %{bar}"` is a single word whose content is *foo bar* +- `"foo %{bar}"` is a single word whose content is *foo bar*. -== Non Quoted words +== Non-Quoted words -Other words are non-quoted. Non-quoted words end either on a whitespaces -or a `;`. +Other words are non-quoted. Non-quoted words are terminated by either a +whitespace or a `;`. -If they start with `\` followed by `%`, `'` or `"`, then that leading -`\` is discarded. +If they start with a `\` followed by a `%`, `'`, or `"`, then that leading +`\` escapes those characters and 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 `\`. +If a whitespace or `;` is preceded by a `\`, 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 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. Rules for expanding and escaping typed -expansions are the same as for `%`-strings. +alphabetic *expansion type* between the `%` and their delimiter (which is +always a punctuation character). This *expansion type* defines how the +string's content is going to be expanded. Rules for expanding and escaping +expansion types 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 as described in <> + the string is expanded as described in <>. -- For any other *expansion type* a parsing error is raised. +- For any other *expansion type*, a parsing error is raised.