96 lines
3.2 KiB
Plaintext
96 lines
3.2 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 terminated 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 <<command-parsing#balanced-strings,Balanced Strings>> 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
|
|
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 also 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 `>`).
|
|
|
|
There is no way to escape the opening and closing characters, even if they
|
|
are nested inside some other kind of string.
|
|
|
|
=== 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*.
|
|
|
|
- `%{foo\{}` is a parse error, since the `{}` delimiters are not balanced.
|
|
|
|
- `%[foo\{]` contains *foo\{*, since it uses different delimiters.
|
|
|
|
== Non-Quoted words
|
|
|
|
Other words are non-quoted. Non-quoted words are terminated by either 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.
|