command: give named arguments to almost all commands

Before this change, only 1 command or so had named arguments. There is
no reason why other commands can't have them, except that it's a bit of
work to add them.

Commands with variable number of arguments are inherently incompatible
to named arguments, such as the "run" command. They still have dummy
names, but obviously you can't assign multiple values to a single named
argument (unless the argument has an array type, which would be
something different). For now, disallow using named argument APIs with
these commands. This might change later.

2 commands are adjusted to not need a separate default value by changing
flag constants. (The numeric values are C only and can't be set by
users.)

Make the command syntax in the manpage more consistent. Now none of the
allowed choice/flag names are in the command header, and all arguments
are shown with their proper name and quoted with <...>.

Some places in the manpage and the client.h doxygen are updated to
reflect that most commands support named arguments. In addition, try to
improve the documentation of the syntax and need for escaping etc. as
well.

(Or actually most uses of the word "argument" should be "parameter".)

1 files changed, 7 insertions, 0 deletions

diff --git a/input/cmd.c b/input/cmd.c
index c637ec22bd..7e50f0784b 100644
--- a/input/cmd.c
+++ b/input/cmd.c
@@ -239,6 +239,13 @@ static bool cmd_node_map(struct mp_log *log, struct mp_cmd *cmd, mpv_node *node)
     if (!find_cmd(log, cmd, bstr0(name->u.string)))
         return false;
 
+    if (cmd->def->vararg) {
+        mp_err(log, "Command %s: this command uses a variable number of "
+               "arguments, which does not work with named arguments.\n",
+               cmd->name);
+        return false;
+    }
+
     for (int n = 0; n < args->num; n++) {
         const char *key = args->keys[n];
         mpv_node *val = &args->values[n];