xenia/kakoune
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document escaping %-strings and add more examples

Browse Source
This commit is contained in:
lePerdu 2019-01-31 08:41:58 -05:00
parent a5f865a566
commit 665d90b9bb
1 changed files with 22 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
doc/pages/command-parsing.asciidoc
View File

@ -15,20 +15,31 @@ If a word starts with `'`, `"` or `%X` with `X` a non nestable
punctuation character it is parsed as a quoted string whose delimiter is, punctuation character it is parsed as a quoted string whose delimiter is,
respectively, `'`, `"` or `X`. respectively, `'`, `"` or `X`.
A quoted string contains every characters (including whitespaces) until A quoted string contains every character (including whitespaces) until
its closing delimiter. If its closing delimiter is doubled, then it is its closing delimiter. If its closing delimiter is doubled, then it is
considered to be part of the string content as a single delimiter. 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. No other escaping takes place in quoted strings.
=== Quoted Strings Examples === Quoted Strings Examples
- `'foo'` contents is *foo* - `'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* - `'foo''bar'` is a single word whose content is *foo'bar*
- `"baz"""` is a single word whose content is *baz"*. - `"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 == Balanced Strings
If a word starts with `%X` with `X` a nestable punctuation character (one If a word starts with `%X` with `X` a nestable punctuation character (one
@ -45,9 +56,13 @@ No other escaping takes place in balanced strings.
=== Balanced Strings Examples === Balanced Strings Examples
- `%{foo}` contents is *foo* - `%{foo}` contains *foo*
- `%{foo\{bar}}` contents is *foo\{bar}* - `%{foo\{bar}}` contains *foo\{bar}*
- `foo%{bar}` contains *foo%{bar}*
- `"foo %{bar}"` is a single word whose content is *foo bar*
== Non Quoted words == Non Quoted words
@ -57,7 +72,7 @@ or a `;`.
If they start with `\\` followed by `%`, `'` or `"`, then that leading If they start with `\\` followed by `%`, `'` or `"`, then that leading
`\\` is discarded. `\\` is discarded.
If a whitespace or `;` is preceeded by `\\`, then the `\\` is discarded If a whitespace or `;` is preceded by `\\`, then the `\\` is discarded
and the whitespace or `;` becomes part of the word. Any other `\\` and the whitespace or `;` becomes part of the word. Any other `\\`
is treated as a literal `\\`. is treated as a literal `\\`.
@ -66,7 +81,8 @@ is treated as a literal `\\`.
Quoted and Balanced strings starting with `%` might have an optional Quoted and Balanced strings starting with `%` might have an optional
alphabetic *expansion type* between the `%` and their delimiter (which alphabetic *expansion type* between the `%` and their delimiter (which
is always a punctuation character). This *expansion type* defines how the is always a punctuation character). This *expansion type* defines how the
string content is going to be expanded. 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 empty, the string content is used verbatim.