84 lines
3.0 KiB
Plaintext
84 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 delimited by a `;` or an end of line
|
|
|
|
- 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 (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). Doubling a closing delimiter escapes it.
|
|
Thus, for example, entering two closing delimiting characters 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.
|
|
|
|
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 matches that of its opening delimiter (respectively `)`, `]`, `}` and `>`).
|
|
|
|
Characters may be escaped in the same manner as those for quoted 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 at a whitespace or a `;`.
|
|
|
|
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 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'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 <<expansions#,`:doc expansions`>>
|
|
|
|
- For any other *expansion type* a parsing error is raised.
|