From 4f129a3eca7f8e1d6e3407c0689cbe313debf301 Mon Sep 17 00:00:00 2001 From: "Avi Halachmi (:avih)" Date: Mon, 28 Dec 2020 15:58:38 +0200 Subject: 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). --- DOCS/man/input.rst | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) (limited to 'DOCS/man') 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. ```` 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. | | `` ::= [] ()*`` -| `` ::= ( | " ")`` +| `` ::= ( | " " | !X 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 ---------------------------- -- cgit v1.2.3