command-parsing.asciidoc (3298B)
1 = Command Parsing 2 3 Kakoune commands, either loaded from a script or written in the command 4 prompt, are parsed according to the following rules: 5 6 == Basic parsing 7 8 - Commands are terminated by a `;` or an end of line. 9 10 - Words (command names and parameters) are delimited by whitespaces. 11 12 == Quoted Strings 13 14 If a word starts with `'`, `"`, or `%X` with `X` a _non-nestable_ punctuation 15 character (see <<command-parsing#balanced-strings,Balanced Strings>> below for 16 nestable characters), it is parsed as a quoted string whose delimiter is, 17 respectively, `'`, `"`, or `X`. 18 19 A quoted string contains every character (including whitespaces). Doubling 20 a closing delimiter escapes it. Thus, for example, entering two closing 21 delimiters at the end of a quoted string will render one of the characters 22 literally; that is, it will be considered as part of the quoted string's 23 content. 24 25 Inside double quotes, `%`-strings are processed unless the `%` is escaped by 26 doubling it. Double quotes inside these nested strings must also be escaped. 27 28 No other escaping takes place in quoted strings. 29 30 === Quoted Strings Examples 31 32 - `'foo'` contains *foo*. 33 34 - `foo'bar'` is read verbatim, so it contains *foo'bar'*. 35 36 - `foo%|bar|` is read verbatim, so it contains *foo%|bar|*. 37 38 - `'foo''bar'` is a single word whose content is *foo'bar*. 39 40 - `"baz"""` is a single word whose content is *baz"*. 41 42 - `%|foo||bar|` is a single word whose content is *foo|bar*. 43 44 - `"foo %|""bar| %%,baz,"` is a single word whose content is *foo "bar %,baz,*. 45 46 == Balanced Strings 47 48 If a word starts with `%X` with `X` a _nestable_ punctuation character (one 49 of `(`, `[`, `{` and `<`), it is parsed as a balanced string whose closing 50 delimiter matches that of its opening delimiter (respectively, `)`, `]`, 51 `}`, and `>`). 52 53 There is no way to escape the opening and closing characters, even if they 54 are nested inside some other kind of string. 55 56 === Balanced Strings Examples 57 58 - `%{foo}` contains *foo*. 59 60 - `%{foo\{bar}}` contains *foo\{bar}*. 61 62 - `foo%{bar}` contains *foo%{bar}*. 63 64 - `"foo %{bar}"` is a single word whose content is *foo bar*. 65 66 - `%{foo\{}` is a parse error, since the `{}` delimiters are not balanced. 67 68 - `%[foo\{]` contains *foo\{*, since it uses different delimiters. 69 70 == Non-Quoted words 71 72 Other words are non-quoted. Non-quoted words are terminated by either a 73 whitespace or a `;`. 74 75 If they start with a `\` followed by a `%`, `'`, or `"`, then that leading 76 `\` escapes those characters and is discarded. 77 78 If a whitespace or `;` is preceded by a `\`, then the `\` is discarded, and 79 the whitespace or `;` becomes part of the word. Any other `\` is treated 80 as a literal `\`. 81 82 == Typed Expansions 83 84 Quoted and Balanced strings starting with `%` might have an optional 85 alphabetic *expansion type* between the `%` and their delimiter (which is 86 always a punctuation character). This *expansion type* defines how the 87 string's content is going to be expanded. Rules for expanding and escaping 88 expansion types are the same as for `%`-strings. 89 90 - If the *expansion type* is empty, the string content is used verbatim. 91 92 - If the *expansion type* is one of `sh`, `reg`, `opt`, `val` or `arg`, 93 the string is expanded as described in <<expansions#,`:doc expansions`>>. 94 95 - For any other *expansion type*, a parsing error is raised.