From 159379980ec8c79608b1adada4b66b1d8c016e4a Mon Sep 17 00:00:00 2001 From: wm4 Date: Thu, 10 May 2018 15:26:27 +0200 Subject: lua: expose async commands Might be useful for some. --- DOCS/man/lua.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'DOCS/man/lua.rst') diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index c0c4f9b00a..0dbd7d3c0a 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -115,6 +115,15 @@ The ``mp`` module is preloaded, although it can be loaded manually with error. ``def`` is the second parameter provided to the function, and is nil if it's missing. +``mp.command_native_async(table [,fn])`` + Like ``mp.command_native()``, but the command is ran asynchronously (as far + as possible), and upon completion, fn is called. fn has two arguments: + ``fn(success, result, error)``. ``success`` is always a Boolean and is true + if the command was successful, otherwise false. The second parameter is + the result value (can be nil) in case of success, nil otherwise (as returned + by ``mp.command_native()``). The third parameter is the error string in case + of an error, nil otherwise. + ``mp.get_property(name [,def])`` Return the value of the given property as string. These are the same properties as used in input.conf. See `Properties`_ for a list of -- cgit v1.2.3 From 1aae88b4879f40c68cebbdcd47895787ecdcdf68 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 12 May 2018 14:50:07 +0200 Subject: 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. --- DOCS/man/lua.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'DOCS/man/lua.rst') diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 0dbd7d3c0a..dab185a284 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -109,7 +109,17 @@ The ``mp`` module is preloaded, although it can be loaded manually with ``mp.command_native(table [,def])`` Similar to ``mp.commandv``, but pass the argument list as table. This has the advantage that in at least some cases, arguments can be passed as - native types. + native types. It also allows you to use named argument. + + If the table is an array, each array item is like an argument in + ``mp.commandv()`` (but can be a native type instead of a string). + + If the table contains string keys, it's interpreted as command with 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 + `Input Command Prefixes`_ to apply. All other entries are interpreted as + arguments. Returns a result table on success (usually empty), or ``def, error`` on error. ``def`` is the second parameter provided to the function, and is -- cgit v1.2.3 From 548ef07864f3e1a40f731b2643f037435ceae46d Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 12 May 2018 15:36:43 +0200 Subject: lua: reimplement mp.subprocess() by invoking the new subprocess command We keep mp.subprocess() with roughly the same semantics for compatibility with scripts (including the internal ytdl script). Seems to work with rhe ytdl wrapper. Not tested further. --- DOCS/man/lua.rst | 56 +++++++++++++++++--------------------------------------- 1 file changed, 17 insertions(+), 39 deletions(-) (limited to 'DOCS/man/lua.rst') diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index dab185a284..ba09164d3b 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -653,45 +653,23 @@ strictly part of the guaranteed API. ``utils.subprocess(t)`` Runs an external process and waits until it exits. Returns process status - and the captured output. - - The parameter ``t`` is a table. The function reads the following entries: - - ``args`` - Array of strings. The first array entry is the executable. This - can be either an absolute path, or a filename with no path - components, in which case the ``PATH`` environment variable is - used to resolve the executable. The other array elements are - passed as command line arguments. - - ``cancellable`` - Optional. If set to ``true`` (default), then if the user stops - playback or goes to the next file while the process is running, - the process will be killed. - - ``max_size`` - Optional. The maximum size in bytes of the data that can be captured - from stdout. (Default: 16 MB.) - - The function returns a table as result with the following entries: - - ``status`` - The raw exit status of the process. It will be negative on error. - - ``stdout`` - Captured output stream as string, limited to ``max_size``. - - ``error`` - ``nil`` on success. The string ``killed`` if the process was - terminated in an unusual way. The string ``init`` if the process - could not be started. - - On Windows, ``killed`` is only returned when the process has been - killed by mpv as a result of ``cancellable`` being set to ``true``. - - ``killed_by_us`` - Set to ``true`` if the process has been killed by mpv as a result - of ``cancellable`` being set to ``true``. + and the captured output. This is a legacy wrapper around calling the + ``subprocess`` command with ``mp.command_native``. It does the following + things: + + - copy the table ``t`` + - rename ``cancellable`` field to ``playback_only`` + - rename ``max_size`` to ``capture_size`` + - set ``capture_stdout`` field to ``true`` if unset + - set ``name`` field to ``subprocess`` + - call ``mp.command_native(copied_t)`` + - if the command failed, create a dummy result table + - copy ``error_string`` to ``error`` field if the string is non-empty + - return the result table + + It is recommended to use ``mp.command_native`` or ``mp.command_native_async`` + directly, instead of calling this legacy wrapper. It is for compatibility + only. ``utils.subprocess_detached(t)`` Runs an external process and detaches it from mpv's control. -- cgit v1.2.3 From 7f91e2684e8600c45512e36f03aadff0b825a1b0 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 12 May 2018 16:03:04 +0200 Subject: lua: reimplement mp.subprocess_detached() by invoking the "run" command The "run" command is old. I'm not sure why the separate Lua implementation was added. But maybe it as because the "run" command used to be limited to a small number of arguments. This limit has been removed a while ago. In any case, the old implementation is not needed anymore. --- DOCS/man/lua.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'DOCS/man/lua.rst') diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index ba09164d3b..b2e244b6b5 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -682,6 +682,9 @@ strictly part of the guaranteed API. The function returns ``nil``. + This is a legacy wrapper around calling the ``run`` command with + ``mp.commandv`` and other functions. + ``utils.getpid()`` Returns the process ID of the running mpv process. This can be used to identify the calling mpv when launching (detached) subprocesses. -- cgit v1.2.3 From dbe831bd025d34930b97c493d9ef61278408cf46 Mon Sep 17 00:00:00 2001 From: wm4 Date: Sat, 12 May 2018 18:48:35 +0200 Subject: lua: expose mpv_abort_async_command() Also somewhat cleans up mp.command_native_async() error handling. --- DOCS/man/lua.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'DOCS/man/lua.rst') diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index b2e244b6b5..10da40016c 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -134,6 +134,18 @@ The ``mp`` module is preloaded, although it can be loaded manually with by ``mp.command_native()``). The third parameter is the error string in case of an error, nil otherwise. + Returns a table with undefined contents, which can be used as argument for + ``mp.abort_async_command``. + + If starting the command failed for some reason, ``nil, error`` is returned, + and ``fn`` is called indicating failure, using the same error value. + +``mp.abort_async_command(t)`` + Abort a ``mp.command_native_async`` call. The argument is the return value + of that command (which starts asynchronous execution of the command). + Whether this works and how long it takes depends on the command and the + situation. The abort call itself is asynchronous. Does not return anything. + ``mp.get_property(name [,def])`` Return the value of the given property as string. These are the same properties as used in input.conf. See `Properties`_ for a list of -- cgit v1.2.3