From 65cd9efa850faaedb9f866632feb9fee2ef71462 Mon Sep 17 00:00:00 2001
From: wm4 <wm4@nowhere>
Date: Tue, 4 Feb 2020 20:40:16 +0100
Subject: lua: add mp.get_script_directory() function

And add some clarifications/suggestions to the manpage.
---
 DOCS/man/lua.rst | 21 ++++++++++++++++-----
 player/lua.c     | 11 +++++++++++
 2 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index b7b423a22b..829bcafd0c 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -55,12 +55,18 @@ that uses the ``.foo`` file extension.
 
 mpv also appends the top level directory of the script to the start of Lua's
 package path so you can import scripts from there too. Be aware that this will
-shadow Lua libraries that use the same package path.
+shadow Lua libraries that use the same package path. (Single file scripts do not
+include mpv specific directory the Lua package path. This was silently changed
+in mpv 0.32.0.)
 
-On the other hand, if the script is a single file (directly located in
-``~/.config/mpv/scripts/`` and not as sub-directory), the Lua package path
-does not include any mpv specific directories. (This was silently changed in
-mpv 0.32.0.)
+Using a script directory is the recommended way to package a script that
+consists of multiple source files, or requires other files (you can use
+``mp.get_script_directory()`` to get the location and e.g. load data files).
+
+Making a script a git repository, basically a repository which contains a
+``main.lua``` file in the root directory, makes scripts easily updateable
+(without the dangers of auto-updates). Another suggestion is to use git
+submodules to share common files or libraries.
 
 Details on the script initialization and lifecycle
 --------------------------------------------------
@@ -492,6 +498,11 @@ The ``mp`` module is preloaded, although it can be loaded manually with
 
         The script ``/path/to/fooscript.lua`` becomes ``fooscript``.
 
+``mp.get_script_directory()``
+    Return the directory if this is a script packaged as directory (see
+    `Script location`_ for a description). Return nothing if this is a single
+    file script.
+
 ``mp.osd_message(text [,duration])``
     Show an OSD message on the screen. ``duration`` is in seconds, and is
     optional (uses ``--osd-duration`` by default).
diff --git a/player/lua.c b/player/lua.c
index 5934492bdf..521a76b4f9 100644
--- a/player/lua.c
+++ b/player/lua.c
@@ -455,6 +455,16 @@ static int script_find_config_file(lua_State *L)
     return 1;
 }
 
+static int script_get_script_directory(lua_State *L)
+{
+    struct script_ctx *ctx = get_ctx(L);
+    if (ctx->path) {
+        lua_pushstring(L, ctx->path);
+        return 1;
+    }
+    return 0;
+}
+
 static int script_suspend(lua_State *L)
 {
     struct script_ctx *ctx = get_ctx(L);
@@ -1228,6 +1238,7 @@ static const struct fn_entry main_fns[] = {
     FN_ENTRY(wait_event),
     FN_ENTRY(request_event),
     FN_ENTRY(find_config_file),
+    FN_ENTRY(get_script_directory),
     FN_ENTRY(command),
     FN_ENTRY(commandv),
     FN_ENTRY(command_native),
-- 
cgit v1.2.3