kakoune/doc/pages/command-parsing.asciidoc

93 lines
3.0 KiB
Plaintext

= Command Parsing
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
- Words (command names and parameters) are separated 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`.
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'` 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
of `(`, `[`, `{` and `<`), it is parsed as a balanced string whose closing
delimiter is the matching character 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.
=== Balanced Strings Examples
- `%{foo}` contains *foo*
- `%{foo\{bar}}` contains *foo\{bar}*
- `foo%{bar}` contains *foo%{bar}*
- `"foo %{bar}"` is a single word whose content is *foo bar*
== Non Quoted words
Other words are non-quoted. Non-quoted words end either on a whitespaces
or a `;`.
If they start with `\\` followed by `%`, `'` or `"`, then that leading
`\\` 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 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.
- 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 <<expansions#,`:doc expansions`>>
- For any other *expansion type* a parsing error is raised.