lua+js: implement utils.file_info()

This commit introduces mp.utils.file_info() for querying information
on file paths, implemented for both Lua and Javascript.

The function takes a file path as an argument and returns a Lua table /
JS object upon success. The table/object will contain the values:
mode, size, atime, mtime, ctime and the convenience booleans is_file, is_dir.

On error, the Lua side will return `nil, error` and the Javascript side
will return `undefined` (and mark the last error).

This feature utilizes the already existing cross-platform `mp_stat()`
function.

2 files changed, 30 insertions, 0 deletions

diff --git a/DOCS/man/javascript.rst b/DOCS/man/javascript.rst
index 995899d07b..419f473e2c 100644
--- a/DOCS/man/javascript.rst
+++ b/DOCS/man/javascript.rst
@@ -168,6 +168,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.split_path(path)``
 
 ``mp.utils.join_path(p1, p2)``
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index 831981db06..5fe7507049 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -591,6 +591,34 @@ strictly part of the guaranteed API.
 
     On error, ``nil, error`` is returned.
 
+``utils.file_info(path)``
+    Stats the given path for information and returns a table with the
+    following entries:
+
+        ``mode``
+            protection bits (on Windows, always 755 (octal) for directories
+            and 644 (octal) for files)
+        ``size``
+            size in bytes
+        ``atime``
+            time of last access
+        ``mtime``
+            time of last modification
+        ``ctime``
+            time of last metadata change (Linux) / time of creation (Windows)
+        ``is_file``
+            Whether ``path`` is a regular file (boolean)
+        ``is_dir``
+            Whether ``path`` is a directory (boolean)
+
+    ``mode`` and ``size`` are integers.
+    Timestamps (``atime``, ``mtime`` and ``ctime``) are integer seconds since
+    the Unix epoch (Unix time).
+    The booleans ``is_file`` and ``is_dir`` are provided as a convenience;
+    they can be and are derived from ``mode``.
+
+    On error (eg. path does not exist), ``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