Skip to content

Latest commit

 

History

History
95 lines (59 loc) · 3.22 KB

command-parsing.asciidoc

File metadata and controls

95 lines (59 loc) · 3.22 KB

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 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 :doc expansions.

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