kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

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.