1) Modified some wording to be more precise
2) Reformatted paragraphs to wrap at column 80 3) Added periods are the end of several lines for overall consistency
This commit is contained in:
parent
56287daac0
commit
a3c0665acc
|
@ -1,36 +1,40 @@
|
||||||
= Command Parsing
|
= Command Parsing
|
||||||
|
|
||||||
Kakoune commands, either loaded from a script or written in the command prompt, are parsed according to the following rules:
|
Kakoune commands, either loaded from a script or written in the command
|
||||||
|
prompt, are parsed according to the following rules:
|
||||||
|
|
||||||
== Basic parsing
|
== Basic parsing
|
||||||
|
|
||||||
- Commands are delimited by a `;` or an end of line
|
- Commands are terminated by a `;` or an end of line.
|
||||||
|
|
||||||
- Words (command names and parameters) are delimited by whitespaces
|
- Words (command names and parameters) are delimited by whitespaces.
|
||||||
|
|
||||||
== Quoted Strings
|
== Quoted Strings
|
||||||
|
|
||||||
If a word starts with `'`, `"`, or `%X` with `X` a non-nestable punctuation character (see below for nestable characters),
|
If a word starts with `'`, `"`, or `%X` with `X` a _non-nestable_ punctuation
|
||||||
it is parsed as a quoted string whose delimiter is, respectively, `'`, `"`, or `X`.
|
character (see 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.
|
A quoted string contains every character (including whitespaces). Doubling
|
||||||
Thus, for example, entering two closing delimiting characters at the end of a quoted string will render one of the characters literally;
|
a closing delimiter escapes it. Thus, for example, entering two closing
|
||||||
that is, it will be considered as part of the quoted string's content.
|
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.
|
Inside double quotes, `%`-strings are processed unless the `%` is escaped by
|
||||||
Double quotes inside these nested strings must still be escaped.
|
doubling it. Double quotes inside these nested strings must also 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'` contains *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 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"*.
|
||||||
|
|
||||||
|
@ -40,44 +44,46 @@ No other escaping takes place in quoted strings.
|
||||||
|
|
||||||
== Balanced Strings
|
== Balanced Strings
|
||||||
|
|
||||||
If a word starts with `%X` with `X` a nestable punctuation character (one of `(`, `[`, `{` and `<`),
|
If a word starts with `%X` with `X` a _nestable_ punctuation character (one
|
||||||
it is parsed as a balanced string
|
of `(`, `[`, `{` and `<`), it is parsed as a balanced string whose closing
|
||||||
whose closing delimiter matches that of its opening delimiter (respectively `)`, `]`, `}` and `>`).
|
delimiter matches that of its opening delimiter (respectively, `)`, `]`,
|
||||||
|
`}`, and `>`).
|
||||||
|
|
||||||
Characters may be escaped in the same manner as those for quoted strings.
|
Characters may be escaped in the same manner as those for quoted strings.
|
||||||
|
|
||||||
=== Balanced Strings Examples
|
=== Balanced Strings Examples
|
||||||
|
|
||||||
- `%{foo}` contains *foo*
|
- `%{foo}` contains *foo*.
|
||||||
|
|
||||||
- `%{foo\{bar}}` contains *foo\{bar}*
|
- `%{foo\{bar}}` contains *foo\{bar}*.
|
||||||
|
|
||||||
- `foo%{bar}` contains *foo%{bar}*
|
- `foo%{bar}` 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*.
|
||||||
|
|
||||||
== Non Quoted words
|
== Non-Quoted words
|
||||||
|
|
||||||
Other words are non-quoted.
|
Other words are non-quoted. Non-quoted words are terminated by either a
|
||||||
Non-quoted words end either at a whitespace or a `;`.
|
whitespace or a `;`.
|
||||||
|
|
||||||
If they start with a `\` followed by a `%`, `'`, or `"`,
|
If they start with a `\` followed by a `%`, `'`, or `"`, then that leading
|
||||||
then that leading `\` escapes those characters and is discarded.
|
`\` escapes those characters and is discarded.
|
||||||
|
|
||||||
If a whitespace or `;` is preceded by a `\`,
|
If a whitespace or `;` is preceded by a `\`, then the `\` is discarded, and
|
||||||
then the `\` is discarded, and the whitespace or `;` becomes part of the word.
|
the whitespace or `;` becomes part of the word. Any other `\` is treated
|
||||||
Any other `\` is treated as a literal `\`.
|
as a literal `\`.
|
||||||
|
|
||||||
== Typed Expansions
|
== Typed Expansions
|
||||||
|
|
||||||
Quoted and Balanced strings starting with `%` might have an optional alphabetic *expansion type* between the `%` and their delimiter
|
Quoted and Balanced strings starting with `%` might have an optional
|
||||||
(which is always a punctuation character).
|
alphabetic *expansion type* between the `%` and their delimiter (which is
|
||||||
This *expansion type* defines how the string's content is going to be expanded.
|
always a punctuation character). This *expansion type* defines how the
|
||||||
Rules for expanding and escaping expansion types are the same as for `%`-strings.
|
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 empty, the string content is used verbatim.
|
||||||
|
|
||||||
- If the *expansion type* is one of `sh`, `reg`, `opt`, `val` or `arg`,
|
- If the *expansion type* is one of `sh`, `reg`, `opt`, `val` or `arg`,
|
||||||
The string is expanded as described in <<expansions#,`:doc expansions`>>
|
the string is expanded as described in <<expansions#,`:doc expansions`>>.
|
||||||
|
|
||||||
- For any other *expansion type* a parsing error is raised.
|
- For any other *expansion type*, a parsing error is raised.
|
||||||
|
|
Loading…
Reference in New Issue
Block a user