diff options
Diffstat (limited to 'DOCS/man')
-rw-r--r-- | DOCS/man/input.rst | 26 |
1 files changed, 18 insertions, 8 deletions
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index 394f394552..82b570c228 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -63,7 +63,7 @@ command. ``<command>`` is the command itself. It consists of the command name and multiple (or none) arguments, all separated by whitespace. String arguments -need to be quoted with ``"``. Details see ``Flat command syntax``. +should be quoted, typically with ``"``. See ``Flat command syntax``. You can bind multiple commands to one key. For example: @@ -162,18 +162,28 @@ a number of other places. | | ``<command> ::= [<prefixes>] <command_name> (<argument>)*`` -| ``<argument> ::= (<string> | " <quoted_string> ")`` +| ``<argument> ::= (<unquoted> | " <double_quoted> " | !X <custom_quoted> X!)`` ``command_name`` is an unquoted string with the command name itself. See `List of Input Commands`_ for a list. -Arguments are separated by whitespace. This applies even to string arguments. -For this reason, string arguments should be quoted with ``"``. If a string -argument contains spaces or certain special characters, quoting and possibly -escaping is mandatory, or the command cannot be parsed correctly. +Arguments are separated by whitespaces even if the command expects only one +argument. Arguments with whitespaces or other special characters must be quoted, +or the command cannot be parsed correctly. -Inside quotes, C-style escaping can be used. JSON escapes according to RFC 8259, -minus surrogate pair escapes, should be a safe subset that can be used. +Double quoted arguments start and end with ``"``. Custom quotes start with ``!`` +(exclamation mark) followed by any ASCII character, and end in the same pair in +reverse order, e.g. ``!'foo'!`` or ``!-bar-!``. The final pair sequence is not +allowed inside the string - in these examples ``'!`` and ``-!`` respectively. + +Custom quotes take their content literally, while inside double quotes +JSON/C-style escaping can be used. JSON escapes according to RFC 8259, minus +surrogate pair escapes, should be a safe subset that can be used. + +Note that argument parsing and property expansion happen at different stages. +First, arguments are determined as described above, and then, where applicable, +properties are expanded - regardless of argument quoting. However, expansion +can still be prevented with ``$>``. See `Property Expansion`_. Commands specified as arrays ---------------------------- |