1b8381461d
Originally the page said:
> No other escaping takes place in balanced strings.
...but in the course of a general readability rewrite (56287da) this was
changed to:
> Characters may be escaped in the same manner as those for quoted strings.
...which is not actually true; probably this change made it in because there
were a lot of good changes in those commits and we didn't read them all closely
enough.
Now the documentation is correct again, and I've added some examples covering
the problems people occasionally ask about (see #2760).
118 lines
3.7 KiB
Plaintext
118 lines
3.7 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. For example, this will **not**
|
|
work, because the `{` in the map command interferes with the delimiters for the
|
|
hook's command block:
|
|
|
|
----
|
|
# DOES NOT WORK
|
|
hook global WinSetOption filetype=latex %{
|
|
map window user b 'o\begin{'
|
|
}
|
|
----
|
|
|
|
You can solve this by using a different outer delimiter:
|
|
|
|
----
|
|
hook global WinSetOption filetype=latex %[
|
|
# Note different delimiter used -----^
|
|
map window user b o\begin{
|
|
]
|
|
----
|
|
|
|
...or just by including matching delimiters inside comments:
|
|
|
|
----
|
|
hook global WinSetOption filetype=latex %{
|
|
map window user b o\begin{ # matched pair to keep Kakoune happy: }
|
|
}
|
|
----
|
|
|
|
=== 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 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.
|