diff options
author | Avi Halachmi (:avih) <avihpit@yahoo.com> | 2020-12-28 15:58:38 +0200 |
---|---|---|
committer | Avi Halachmi (:avih) <avihpit@yahoo.com> | 2020-12-31 12:54:33 +0200 |
commit | 4f129a3eca7f8e1d6e3407c0689cbe313debf301 (patch) | |
tree | 84208ce103e7108e450f445373913986f85e0186 /DOCS | |
parent | bb439efe0df3e90be25613745a544c75a97127dd (diff) | |
download | mpv-4f129a3eca7f8e1d6e3407c0689cbe313debf301.tar.bz2 mpv-4f129a3eca7f8e1d6e3407c0689cbe313debf301.tar.xz |
input.conf syntax: support custom quotes !XstringX!
Where X is any ASCII char chosen by the user. An argument is only
interpreted as custom-quoted if it starts with '!' and the line doesn't
end right after it. Custom quotes don't interpret backslash-escape.
This change only affects command arguments which mpv parses (not array
commands), and not tokens before the arguments (where applicable - key
name, input section, command prefixes, command name).
Diffstat (limited to 'DOCS')
-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 ---------------------------- |