DOCS: clarify how client/script names work

This isn't really clearly stated anywhere and could understandably lead
to some confusion.
This commit is contained in:
Dudemanguy 2021-04-29 15:56:11 -05:00
parent 029cd8a813
commit 7df9ebda6c
2 changed files with 12 additions and 4 deletions

View File

@ -1174,7 +1174,8 @@ Input Commands that are Possibly Subject to Change
``script-message-to <target> [<arg1> [<arg2> [...]]]``
Same as ``script-message``, but send it only to the client named
``<target>``. Each client (scripts etc.) has a unique name. For example,
Lua scripts can get their name via ``mp.get_script_name()``.
Lua scripts can get their name via ``mp.get_script_name()``. Note that
client names only consist of alphanumeric characters and ``_``.
This command has a variable number of arguments, and cannot be used with
named arguments.
@ -1186,7 +1187,8 @@ Input Commands that are Possibly Subject to Change
The argument is the name of the binding.
It can optionally be prefixed with the name of the script, using ``/`` as
separator, e.g. ``script-binding scriptname/bindingname``.
separator, e.g. ``script-binding scriptname/bindingname``. Note that script
names only consist of alphanumeric characters and ``_``.
For completeness, here is how this command works internally. The details
could change any time. On any matching key event, ``script-message-to``

View File

@ -37,6 +37,12 @@ scripting backend to use for it. For Lua, it is ``.lua``. If the extension is
not recognized, an error is printed. (If an error happens, the extension is
either mistyped, or the backend was not compiled into your mpv binary.)
mpv internally loads the script's name by stripping the ``.lua`` extension and
replacing all nonalphanumeric characters with ``_``. E.g., ``my-tools.lua``
becomes ``my_tools``. If there are several scripts with the same name, it is
made unique by appending a number. This is the name returned by
``mp.get_script_name()``.
Entries with ``.disable`` extension are always ignored.
If a script is a directory (either if a directory is passed to ``--script``,
@ -500,11 +506,11 @@ The ``mp`` module is preloaded, although it can be loaded manually with
Return the name of the current script. The name is usually made of the
filename of the script, with directory and file extension removed. If
there are several scripts which would have the same name, it's made unique
by appending a number.
by appending a number. Any nonalphanumeric characters are replaced with ``_``.
.. admonition:: Example
The script ``/path/to/fooscript.lua`` becomes ``fooscript``.
The script ``/path/to/foo-script.lua`` becomes ``foo_script``.
``mp.get_script_directory()``
Return the directory if this is a script packaged as directory (see