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`.

1 files changed, 174 insertions, 0 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