From 665d90b9bbcdcd789ff81e23daa3579291623424 Mon Sep 17 00:00:00 2001 From: lePerdu Date: Thu, 31 Jan 2019 08:41:58 -0500 Subject: [PATCH] Document escaping %-strings and add more examples --- doc/pages/command-parsing.asciidoc | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/doc/pages/command-parsing.asciidoc b/doc/pages/command-parsing.asciidoc index 02b02b86..dcf3724f 100644 --- a/doc/pages/command-parsing.asciidoc +++ b/doc/pages/command-parsing.asciidoc @@ -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, 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 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'` 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* - `"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 @@ -45,9 +56,13 @@ No other escaping takes place in balanced strings. === 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 @@ -57,7 +72,7 @@ or a `;`. If they start with `\\` followed by `%`, `'` or `"`, then that leading `\\` 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 `\\` is treated as a literal `\\`. @@ -66,7 +81,8 @@ is treated as a literal `\\`. 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. +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.