Add filesystem module to Lua API.rst

Lua API.rst

@@ -1765,6 +1765,66 @@ Supported callbacks and fields are:
   ``dfhack.gui.getSelected...`` function.
 
 
+Filesystem module
+-----------------
+
+Most of these functions return ``true`` on success and ``false`` on failure,
+unless otherwise noted.
+
+* ``dfhack.filesystem.exists(path)``
+
+  Returns ``true`` if ``path`` exists.
+
+* ``dfhack.filesystem.isfile(path)``
+
+  Returns ``true`` if ``path`` exists and is a file.
+
+* ``dfhack.filesystem.isdir(path)``
+
+  Returns ``true`` if ``path`` exists and is a directory.
+
+* ``dfhack.filesystem.getcwd()``
+
+  Returns the current working directory. To retrieve the DF path, use ``dfhack.getDFPath()`` instead.
+
+* ``dfhack.filesystem.chdir(path)``
+
+  Changes the current directory to ``path``. Use with caution.
+
+* ``dfhack.filesystem.mkdir(path)``
+
+  Creates a new directory. Returns ``false`` if unsuccessful, including if ``path`` already exists.
+
+* ``dfhack.filesystem.rmdir(path)``
+
+  Removes a directory. Only works if the directory is already empty.
+
+* ``dfhack.filesystem.mtime(path)``
+
+  Returns the modification time (in seconds) of the file or directory specified by ``path``,
+  or -1 if ``path`` does not exist. This depends on the system clock and should only be used locally.
+
+* ``dfhack.filesystem.atime(path)``
+* ``dfhack.filesystem.ctime(path)``
+
+  Return values vary across operating systems - return the ``st_atime`` and ``st_ctime``
+  fields of a C++ stat struct, respectively.
+
+* ``dfhack.filesystem.listdir(path)``
+
+  Lists files/directories in a directory.  Returns ``{}`` if ``path`` does not exist.
+
+* ``dfhack.filesystem.listdir_recursive(path [, depth = 10])``
+
+  Lists all files/directories in a directory and its subdirectories. All directories
+  are listed before their contents. Returns a table with subtables of the format::
+
+    {path: 'path to file', isdir: true|false}
+
+  Note that ``listdir()`` returns only the base name of each directory entry, while
+  ``listdir_recursive()`` returns the initial path and all components following it
+  for each entry.
+
 Internal API
 ------------
 
@@ -1846,8 +1906,8 @@ and are only documented here for completeness:
 
 * ``dfhack.internal.getDir(path)``
 
-  List files in a directory.
+  Lists files/directories in a directory.
-  Returns: *file_names* or empty table if not found.
+  Returns: *file_names* or empty table if not found. Identical to ``dfhack.filesystem.listdir(path)``.
 
 Core interpreter context
 ========================