From 7df9ebda6c9828b75b814facd4267c8da0eca736 Mon Sep 17 00:00:00 2001 From: Dudemanguy Date: Thu, 29 Apr 2021 15:56:11 -0500 Subject: DOCS: clarify how client/script names work This isn't really clearly stated anywhere and could understandably lead to some confusion. --- DOCS/man/input.rst | 6 ++++-- DOCS/man/lua.rst | 10 ++++++++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst index cf4bd4c649..25f52e3c10 100644 --- a/DOCS/man/input.rst +++ b/DOCS/man/input.rst @@ -1174,7 +1174,8 @@ Input Commands that are Possibly Subject to Change ``script-message-to [ [ [...]]]`` Same as ``script-message``, but send it only to the client named ````. 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`` diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst index 3fdb0b2f42..8a8fadc40c 100644 --- a/DOCS/man/lua.rst +++ b/DOCS/man/lua.rst @@ -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 -- cgit v1.2.3