summaryrefslogtreecommitdiffstats
path: root/DOCS/man/en
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2014-05-25 19:51:11 +0200
committerwm4 <wm4@nowhere>2014-05-25 19:51:11 +0200
commite2e450f96177c17bea5f15abee87b1671ecdc75d (patch)
treea235911e1fbe620532b41f32a647ff45f7ced378 /DOCS/man/en
parente648f7e783e9b063bbef4dcbb5f2c9e7a8c8e4e4 (diff)
downloadmpv-e2e450f96177c17bea5f15abee87b1671ecdc75d.tar.bz2
mpv-e2e450f96177c17bea5f15abee87b1671ecdc75d.tar.xz
lua: add some filesystem utility functions
We need this only because Lua's stdlib is so scarce. Lua doesn't intend to include a complete stdlib - they confine themselves to standard C, both for portability reasons and to keep the code minimal. But standard C does not provide much either. It would be possible to use Lua POSIX wrapper libraries, but that would be a messy (and unobvious) dependency. It's better to implement the missing functions ourselves, as long as they're small in number.
Diffstat (limited to 'DOCS/man/en')
-rw-r--r--DOCS/man/en/lua.rst42
1 files changed, 42 insertions, 0 deletions
diff --git a/DOCS/man/en/lua.rst b/DOCS/man/en/lua.rst
index f500443203..fca158cad7 100644
--- a/DOCS/man/en/lua.rst
+++ b/DOCS/man/en/lua.rst
@@ -461,6 +461,48 @@ Example command-line::
--lua-opts=myscript-optionA=TEST:myscript-optionB=0:myscript-optionC=yes
+mp.utils options
+----------------
+
+This built-in module provides generic helper functions for Lua, and have
+strictly speaking nothing to do with mpv or video/audio playback. They are
+provided for convenience. Most compensate for Lua's scarce standard library.
+
+``utils.readdir(path [, filter])``
+ Enumerate all entries at the given path on the filesystem, and return them
+ as array. Each entry is a directory entry (without the path).
+ The list is unsorted (in whatever order the operating system returns it).
+
+ If the ``filter`` argument is given, it must be one of the following
+ strings:
+
+ ``files``
+ List regular files only. This excludes directories, special files
+ (like UNIX device files or FIFOs), and dead symlinks. It includes
+ UNIX symlinks to regular files.
+
+ ``dirs``
+ List directories only, or symlinks to directories. ``.`` and ``..``
+ are not included.
+
+ ``normal``
+ Include the results of both ``files`` and ``dirs``. (This is the
+ default.)
+
+ ``all``
+ List all entries, even device files, dead symlinks, FIFOs, and the
+ ``.`` and ``..`` entries.
+
+ On error, ``nil, error`` is returned.
+
+``utils.split_path(path)``
+ Split a path into directory component and filename component, and return
+ them. The first return value is always the directory. The second return
+ value is the trailing part of the path, the directory entry.
+
+``utils.join_path(p1, p2)``
+ Return the concatenation of the 2 paths. Tries to be clever. For example,
+ if ```p2`` is an absolute path, p2 is returned without change.
Events
------