diff options
Diffstat (limited to 'DOCS/man/javascript.rst')
| -rw-r--r-- | DOCS/man/javascript.rst | 88 |
1 files changed, 65 insertions, 23 deletions
diff --git a/DOCS/man/javascript.rst b/DOCS/man/javascript.rst index 184c962a97..99112db40b 100644 --- a/DOCS/man/javascript.rst +++ b/DOCS/man/javascript.rst @@ -58,7 +58,7 @@ Language features - ECMAScript 5 The scripting backend which mpv currently uses is MuJS - a compatible minimal ES5 interpreter. As such, ``String.substring`` is implemented for instance, while the common but non-standard ``String.substr`` is not. Please consult the -MuJS pages on language features and platform support - http://mujs.com . +MuJS pages on language features and platform support - https://mujs.com . Unsupported Lua APIs and their JS alternatives ---------------------------------------------- @@ -73,12 +73,6 @@ Unsupported Lua APIs and their JS alternatives ``utils.to_string(v)`` see ``dump`` below. -``mp.suspend()`` JS: none (deprecated). - -``mp.resume()`` JS: none (deprecated). - -``mp.resume_all()`` JS: none (deprecated). - ``mp.get_next_timeout()`` see event loop below. ``mp.dispatch_events([allow_wait])`` see event loop below. @@ -88,7 +82,7 @@ Scripting APIs - identical to Lua (LE) - Last-Error, indicates that ``mp.last_error()`` can be used after the call to test for success (empty string) or failure (non empty reason string). -Otherwise, where the Lua APIs return ``nil`` on error, JS returns ``undefined``. +Where the Lua APIs use ``nil`` to indicate error, JS APIs use ``undefined``. ``mp.command(string)`` (LE) @@ -96,6 +90,11 @@ Otherwise, where the Lua APIs return ``nil`` on error, JS returns ``undefined``. ``mp.command_native(table [,def])`` (LE) +``id = mp.command_native_async(table [,fn])`` (LE) Notes: ``id`` is true-thy on +success, ``fn`` is called always a-sync, ``error`` is empty string on success. + +``mp.abort_async_command(id)`` + ``mp.get_property(name [,def])`` (LE) ``mp.get_property_osd(name [,def])`` (LE) @@ -134,6 +133,8 @@ Otherwise, where the Lua APIs return ``nil`` on error, JS returns ``undefined``. ``mp.get_script_name()`` +``mp.get_script_directory()`` + ``mp.osd_message(text [,duration])`` ``mp.get_wakeup_pipe()`` @@ -148,6 +149,10 @@ Otherwise, where the Lua APIs return ``nil`` on error, JS returns ``undefined``. ``mp.unregister_script_message(name)`` +``mp.create_osd_overlay(format)`` + +``mp.get_osd_size()`` (returned object has properties: width, height, aspect) + ``mp.msg.log(level, ...)`` ``mp.msg.fatal(...)`` @@ -168,7 +173,8 @@ Otherwise, where the Lua APIs return ``nil`` on error, JS returns ``undefined``. ``mp.utils.readdir(path [, filter])`` (LE) -``mp.utils.file_info(path)`` (LE) +``mp.utils.file_info(path)`` (LE) Note: like lua - this does NOT expand +meta-paths like ``~~/foo`` (other JS file functions do expand meta paths). ``mp.utils.split_path(path)`` @@ -178,11 +184,14 @@ Otherwise, where the Lua APIs return ``nil`` on error, JS returns ``undefined``. ``mp.utils.subprocess_detached(t)`` +``mp.utils.get_env_list()`` + ``mp.utils.getpid()`` (LE) -``mp.add_hook(type, priority, fn)`` +``mp.add_hook(type, priority, fn(hook))`` -``mp.options.read_options(obj [, identifier])`` (types: string/boolean/number) +``mp.options.read_options(obj [, identifier [, on_update]])`` (types: +string/boolean/number) Additional utilities -------------------- @@ -206,8 +215,9 @@ Additional utilities ``undefined`` if the variable is not defined. ``mp.utils.get_user_path(path)`` - Expands (mpv) meta paths like ``~/x``, ``~~/y``, ``~~desktop/z`` etc. - ``read_file``, ``write_file`` and ``require`` already use this internaly. + Trivial wrapper of the ``expand-path`` mpv command, returns a string. + ``read_file``, ``write_file``, ``append_file`` and ``require`` already + expand the path internally and accept mpv meta-paths like ``~~desktop/foo``. ``mp.utils.read_file(fname [,max])`` Returns the content of file ``fname`` as string. If ``max`` is provided and @@ -218,7 +228,12 @@ Additional utilities prefixed with ``file://`` as simple protection against accidental arguments switch, e.g. ``mp.utils.write_file("file://~/abc.txt", "hello world")``. -Note: ``read_file`` and ``write_file`` throw on errors, allow text content only. +``mp.utils.append_file(fname, str)`` + Same as ``mp.utils.write_file`` if the file ``fname`` does not exist. If it + does exist then append instead of overwrite. + +Note: ``read_file``, ``write_file`` and ``append_file`` throw on errors, allow +text content only. ``mp.get_time_ms()`` Same as ``mp.get_time()`` but in ms instead of seconds. @@ -235,6 +250,9 @@ Note: ``read_file`` and ``write_file`` throw on errors, allow text content only. anything from the filesystem), and returns it as a function. Very similar to a ``Function`` constructor, but shows at stack traces as ``fname``. +``mp.module_paths`` + Global modules search paths array for the ``require`` function (see below). + Timers (global) --------------- @@ -273,9 +291,11 @@ CommonJS modules and ``require(id)`` ------------------------------------ CommonJS Modules are a standard system where scripts can export common functions -for use by other scripts. A module is a script which adds properties (functions, -etc) to its invisible ``exports`` object, which another script can access by -loading it with ``require(module-id)`` - which returns that ``exports`` object. +for use by other scripts. Specifically, a module is a script which adds +properties (functions, etc) to its pre-existing ``exports`` object, which +another script can access with ``require(module-id)``. This runs the module and +returns its ``exports`` object. Further calls to ``require`` for the same module +will return its cached ``exports`` object without running the module again. Modules and ``require`` are supported, standard compliant, and generally similar to node.js. However, most node.js modules won't run due to missing modules such @@ -285,13 +305,20 @@ do work. In general, this is for mpv modules and not a node.js replacement. A ``.js`` file extension is always added to ``id``, e.g. ``require("./foo")`` will load the file ``./foo.js`` and return its ``exports`` object. -An id is relative (to the script which ``require``'d it) if it starts with -``./`` or ``../``. Otherwise, it's considered a "top-level id" (CommonJS term). +An id which starts with ``./`` or ``../`` is relative to the script or module +which ``require`` it. Otherwise it's considered a top-level id (CommonJS term). -Top level id is evaluated as absolute filesystem path if possible (e.g. ``/x/y`` -or ``~/x``). Otherwise, it's searched at ``scripts/modules.js/`` in mpv config -dirs - in normal config search order. E.g. ``require("x")`` is searched as file -``x.js`` at those dirs, and id ``foo/x`` is searched as file ``foo/x.js``. +Top-level id is evaluated as absolute filesystem path if possible, e.g. ``/x/y`` +or ``~/x``. Otherwise it's considered a global module id and searched according +to ``mp.module_paths`` in normal array order, e.g. ``require("x")`` tries to +load ``x.js`` at one of the array paths, and id ``foo/x`` tries to load ``x.js`` +inside dir ``foo`` at one of the paths. + +The ``mp.module_paths`` array is empty by default except for scripts which are +loaded as a directory where it contains one item - ``<directory>/modules/`` . +The array may be updated from a script (or using custom init - see below) which +will affect future calls to ``require`` for global module id's which are not +already loaded/cached. No ``global`` variable, but a module's ``this`` at its top lexical scope is the global object - also in strict mode. If you have a module which needs ``global`` @@ -299,6 +326,21 @@ as the global object, you could do ``this.global = this;`` before ``require``. Functions and variables declared at a module don't pollute the global object. +Custom initialization +--------------------- + +After mpv initializes the JavaScript environment for a script but before it +loads the script - it tries to run the file ``init.js`` at the root of the mpv +configuration directory. Code at this file can update the environment further +for all scripts. E.g. if it contains ``mp.module_paths.push("/foo")`` then +``require`` at all scripts will search global module id's also at ``/foo`` +(do NOT do ``mp.module_paths = ["/foo"];`` because this will remove existing +paths - like ``<script-dir>/modules`` for scripts which load from a directory). + +The custom-init file is ignored if mpv is invoked with ``--no-config``. + +Before mpv 0.34, the file name was ``.init.js`` (with dot) at the same dir. + The event loop -------------- |