summaryrefslogtreecommitdiffstats
path: root/libmpv
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2018-05-12 14:50:07 +0200
committerwm4 <wm4@nowhere>2018-05-24 19:56:34 +0200
commit1aae88b4879f40c68cebbdcd47895787ecdcdf68 (patch)
tree72de973fbbed447ee6cd7bf61ce506601fe8438f /libmpv
parent1157f07c5b8b97112f9a6bde695aff8072a88fb2 (diff)
downloadmpv-1aae88b4879f40c68cebbdcd47895787ecdcdf68.tar.bz2
mpv-1aae88b4879f40c68cebbdcd47895787ecdcdf68.tar.xz
input: add glue code for named arguments
Named arguments should make it easier to have long time compatibility, even if command arguments get added or removed. They're also much nicer for commands with a large number of arguments, especially if many arguments are optional. As of this commit, this can not be used, because there is no command yet which supports them. See the following commit.
Diffstat (limited to 'libmpv')
-rw-r--r--libmpv/client.h23
1 files changed, 19 insertions, 4 deletions
diff --git a/libmpv/client.h b/libmpv/client.h
index f9c9f3686b..f7f7fada58 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -941,10 +941,25 @@ int mpv_command(mpv_handle *ctx, const char **args);
*
* Does not use OSD and string expansion by default.
*
- * @param[in] args mpv_node with format set to MPV_FORMAT_NODE_ARRAY; each entry
- * is an argument using an arbitrary format (the format must be
- * compatible to the used command). Usually, the first item is
- * the command name (as MPV_FORMAT_STRING).
+ * The args argument can have one of the following formats:
+ *
+ * MPV_FORMAT_NODE_ARRAY:
+ * Positional arguments. Each entry is an argument using an arbitrary
+ * format (the format must be compatible to the used command). Usually,
+ * the first item is the command name (as MPV_FORMAT_STRING). The order
+ * of arguments is as documented in each command description.
+ *
+ * MPV_FORMAT_NODE_MAP:
+ * Named arguments. This requires at least an entry with the key "name"
+ * to be present, which must be a string, and contains the command name.
+ * The special entry "_flags" is optional, and if present, must be an
+ * array of strings, each being a command prefix to apply. All other
+ * entries are interpreted as arguments. They must use the argument names
+ * as documented in each command description. Currently, most commands do
+ * not support named arguments at all.
+ *
+ * @param[in] args mpv_node with format set to one of the values documented
+ * above (see there for details)
* @param[out] result Optional, pass NULL if unused. If not NULL, and if the
* function succeeds, this is set to command-specific return
* data. You must call mpv_free_node_contents() to free it