Lua: add more UTF-8-aware file operations to `pandoc.system`.

Functions that expect UTF-8-encoded filenames should make it easier to
write platform-independent scripts, as the encoding of the actual
filename depends on the system.

Additionally, this also adds a generalized method to run commands, and
functions to retrieve XDG directory names.

The new functions are `command`, `copy`, `read_file`, `remove`,
`rename`, `times`, `write_file`, `xdg`.

4 files changed, 188 insertions, 3 deletions

diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index f728e5bdb..7bbef63fd 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -5534,6 +5534,53 @@ Returns:
 
 *Since: 3.1.1*
 
+### command {#pandoc.system.command}
+
+`command (command, args[, input[, opts]])`
+
+Executes a system command with the given arguments and `input` on
+*stdin*.
+
+Parameters:
+
+`command`
+:   command to execute (string)
+
+`args`
+:   command arguments ({string,\...})
+
+`input`
+:   input on stdin (string)
+
+`opts`
+:   process options (table)
+
+Returns:
+
+- exit code -- `false` on success, an integer otherwise
+  ([integer]{unknown-type="integer"}\|boolean)
+- stdout (string)
+- stderr (string)
+
+*Since: 3.7.1*
+
+### copy {#pandoc.system.copy}
+
+`copy (source, target)`
+
+Copy a file with its permissions. If the destination file already
+exists, it is overwritten.
+
+Parameters:
+
+`source`
+:   source file (string)
+
+`target`
+:   target destination (string)
+
+*Since: 3.7.1*
+
 ### environment {#pandoc.system.environment}
 
 `environment ()`
@@ -5602,6 +5649,61 @@ Parameters:
 
 *Since: 2.19*
 
+### read_file {#pandoc.system.read_file}
+
+`read_file (filepath)`
+
+Parameters:
+
+`filepath`
+:   File to read (string)
+
+Returns:
+
+- file contents (string)
+
+*Since: 3.7.1*
+
+### rename {#pandoc.system.rename}
+
+`rename (old, new)`
+
+Change the name of an existing path from `old` to `new`.
+
+If `old` is a directory and `new` is a directory that already
+exists, then `new` is atomically replaced by the `old` directory.
+On Win32 platforms, this function fails if `new` is an existing
+directory.
+
+If `old` does not refer to a directory, then neither may `new`.
+
+Renaming may not work across file system boundaries or due to
+other system-specific reasons. It's generally more robust to copy
+the source path to its destination before deleting the source.
+
+Parameters:
+
+`old`
+:   original path (string)
+
+`new`
+:   new path (string)
+
+*Since: 3.7.1*
+
+### remove {#pandoc.system.remove}
+
+`remove (filename)`
+
+Removes the directory entry for an existing file.
+
+Parameters:
+
+`filename`
+:   file to remove (string)
+
+*Since: 3.7.1*
+
 ### remove_directory {#pandoc.system.remove_directory}
 
 `remove_directory (dirname[, recursive])`
@@ -5619,6 +5721,25 @@ Parameters:
 
 *Since: 2.19*
 
+### times {#pandoc.system.times}
+
+`times (filepath)`
+
+Obtain the modification and access time of a file or directory.
+The times are returned as strings using the ISO 8601 format.
+
+Parameters:
+
+`filepath`
+:   file or directory path (string)
+
+Returns:
+
+- time at which the file or directory was last modified (table)
+- time at which the file or directory was last accessed (table)
+
+*Since: 3.7.1*
+
 ### with_environment {#pandoc.system.with_environment}
 
 `with_environment (environment, callback)`
@@ -5695,6 +5816,58 @@ The results of the call to `callback`.
 
 *Since: 2.7.3*
 
+### write_file {#pandoc.system.write_file}
+
+`write_file (filepath, contents)`
+
+Writes a string to a file.
+
+Parameters:
+
+`filepath`
+:   path to target file (string)
+
+`contents`
+:   file contents (string)
+
+*Since: 3.7.1*
+
+### xdg {#pandoc.system.xdg}
+
+`xdg (xdg_directory_type[, filepath])`
+
+Access special directories and directory search paths.
+
+Special directories for storing user-specific application data,
+configuration, and cache files, as specified by the [XDG Base
+Directory Specification].
+
+Parameters:
+
+`xdg_directory_type`
+
+:   The type of the XDG directory or search path. Must be one of
+    `config`, `data`, `cache`, `state`, `datadirs`, or
+    `configdirs`.
+
+    Matching is case-insensitive, and underscores and `XDG`
+    prefixes are ignored, so a value like `XDG_DATA_DIRS` is also
+    acceptable.
+
+    The `state` directory might not be available, depending on the
+    version of the underlying Haskell library. (string)
+
+`filepath`
+:   relative path that is appended to the path; ignored if the
+    result is a list of search paths. (string)
+
+Returns:
+
+- Either a single file path, or a list of search paths.
+  (string\|{string,\...})
+
+*Since: 3.7.1*
+
 <!-- END: AUTOGENERATED CONTENT -->
 
 
@@ -6982,6 +7155,7 @@ Returns:
   [null]: #pandoc.json.null
   [this blog post]: http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html
   [ChunkedDoc]: #type-chunkeddoc
+  [XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/latest/
   [Doc]: #type-doc
   [Template]: #type-template
   [zip.Entry]: #type-pandoc.zip.Entry
diff --git a/pandoc-lua-engine/pandoc-lua-engine.cabal b/pandoc-lua-engine/pandoc-lua-engine.cabal
index 1ebfba37b..5cd6c570b 100644
--- a/pandoc-lua-engine/pandoc-lua-engine.cabal
+++ b/pandoc-lua-engine/pandoc-lua-engine.cabal
@@ -119,7 +119,7 @@ library
                      , hslua                 >= 2.3     && < 2.5
                      , hslua-module-doclayout>= 1.2     && < 1.3
                      , hslua-module-path     >= 1.1     && < 1.2
-                     , hslua-module-system   >= 1.1     && < 1.2
+                     , hslua-module-system   >= 1.2     && < 1.3
                      , hslua-module-text     >= 1.1     && < 1.2
                      , hslua-module-version  >= 1.1     && < 1.2
                      , hslua-module-zip      >= 1.1.3   && < 1.2
diff --git a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/System.hs b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/System.hs
index ef5c63d6a..c6a124166 100644
--- a/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/System.hs
+++ b/pandoc-lua-engine/src/Text/Pandoc/Lua/Module/System.hs
@@ -18,8 +18,10 @@ module Text.Pandoc.Lua.Module.System
 import Data.Version (makeVersion)
 import HsLua
 import HsLua.Module.System
-  ( arch, cputime, env, getwd, ls, mkdir, os, rmdir
-  , with_env, with_tmpdir, with_wd)
+  ( arch, cmd, cp, cputime, env, getwd, ls, mkdir, os, read_file
+  , rename, rm, rmdir, times, with_env, with_tmpdir, with_wd
+  , write_file, xdg
+  )
 import qualified HsLua.Module.System as MSys
 
 -- | Push the pandoc.system module on the Lua stack.
@@ -33,14 +35,22 @@ documentedModule = Module
       ]
   , moduleFunctions =
       [ cputime                                        `since` v[3,1,1]
+      , setName "command" cmd                          `since` v[3,7,1]
+      , setName "copy" cp                              `since` v[3,7,1]
       , setName "environment" env                      `since` v[2,7,3]
       , setName "get_working_directory" getwd          `since` v[2,8]
       , setName "list_directory" ls                    `since` v[2,19]
       , setName "make_directory" mkdir                 `since` v[2,19]
+      , read_file                                      `since` v[3,7,1]
+      , rename                                         `since` v[3,7,1]
+      , setName "remove" rm                            `since` v[3,7,1]
       , setName "remove_directory" rmdir               `since` v[2,19]
+      , times                                          `since` v[3,7,1]
       , setName "with_environment" with_env            `since` v[2,7,3]
       , setName "with_temporary_directory" with_tmpdir `since` v[2,8]
       , setName "with_working_directory" with_wd       `since` v[2,7,3]
+      , write_file                                     `since` v[3,7,1]
+      , xdg                                            `since` v[3,7,1]
       ]
   , moduleOperations = []
   , moduleTypeInitializers = []
diff --git a/stack.yaml b/stack.yaml
index 547f20758..2f8df84a0 100644
--- a/stack.yaml
+++ b/stack.yaml
@@ -11,6 +11,7 @@ packages:
 extra-deps:
 - hslua-2.4.0
 - hslua-module-doclayout-1.2.0.1
+- hslua-module-system-1.2.0
 - hslua-objectorientation-2.4.0
 - hslua-packaging-2.3.2
 - pandoc-lua-marshal-0.3.1