Command Parsing

Kakoune commands, either loaded from a script or written in the command prompt, are parsed according to the following rules:

1. Basic parsing

Commands are terminated by a ; or an end of line.
Words (command names and parameters) are delimited by whitespaces.

If a word starts with ', ", or %X with X a non-nestable punctuation character (see 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.

2.1. 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,.

3. 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.

3.1. 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.

4. 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 \.

5. 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 :doc expansions.
For any other expansion type, a parsing error is raised.