Command Parsing

#1

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}" 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
    :doc expansions

  • For any other expansion type a parsing error is raised.