Lua: add module "pandoc.path"

The module allows to work with file paths in a convenient and
platform-independent manner.

Closes: #6001
Closes: #6565

doc/lua-filters.md

@@ -3376,6 +3376,178 @@ methods and convenience functions.
     `comp`:
     :   Comparison function as described above.
 
+# Module pandoc.path
+
+Module for file path manipulations.
+
+## Static Fields {#pandoc.path-fields}
+
+### separator {#pandoc.path.separator}
+
+The character that separates directories.
+
+### search_path_separator {#pandoc.path.search_path_separator}
+
+The character that is used to separate the entries in the `PATH`
+environment variable.
+
+## Functions {#pandoc.path-functions}
+
+### directory (filepath) {#pandoc.path.directory}
+
+Get the directory name; move up one level.
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   The filepath up to the last directory separator. (string)
+
+### filename (filepath) {#pandoc.path.filename}
+
+Get the file name.
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   File name part of the input path. (string)
+
+### is_absolute (filepath) {#pandoc.path.is_absolute}
+
+Checks whether a path is absolute, i.e. not fixed to a root.
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   `true` iff `filepath` is an absolute path, `false` otherwise.
+    (boolean)
+
+### is_relative (filepath) {#pandoc.path.is_relative}
+
+Checks whether a path is relative or fixed to a root.
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   `true` iff `filepath` is a relative path, `false` otherwise.
+    (boolean)
+
+### join (filepaths) {#pandoc.path.join}
+
+Join path elements back together by the directory separator.
+
+Parameters:
+
+filepaths
+:   path components (list of strings)
+
+Returns:
+
+-   The joined path. (string)
+
+### make_relative (path, root[, unsafe]) {#pandoc.path.make_relative}
+
+Contract a filename, based on a relative path. Note that the
+resulting path will usually not introduce `..` paths, as the
+presence of symlinks means `../b` may not reach `a/b` if it starts
+from `a/c`. For a worked example see [this blog
+post](http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html).
+
+Set `unsafe` to a truthy value to a allow `..` in paths.
+
+Parameters:
+
+path
+:   path to be made relative (string)
+
+root
+:   root path (string)
+
+unsafe
+:   whether to allow `..` in the result. (boolean)
+
+Returns:
+
+-   contracted filename (string)
+
+### normalize (filepath) {#pandoc.path.normalize}
+
+Normalizes a path.
+
+-   `//` outside of the drive can be made blank
+-   `/` becomes the `path.separator`
+-   `./` -\> ''
+-   an empty path becomes `.`
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   The normalized path. (string)
+
+### split (filepath) {#pandoc.path.split}
+
+Splits a path by the directory separator.
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   List of all path components. (list of strings)
+
+### split_extension (filepath) {#pandoc.path.split_extension}
+
+Splits the last extension from a file path and returns the parts. The
+extension, if present, includes the leading separator; if the path has
+no extension, then the empty string is returned as the extension.
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   filepath without extension (string)
+
+-   extension or empty string (string)
+
+### split_search_path (search_path) {#pandoc.path.split_search_path}
+
+Takes a string and splits it on the `search_path_separator` character.
+Blank items are ignored on Windows, and converted to `.` on Posix. On
+Windows path elements are stripped of quotes.
+
+Parameters:
+
+search_path
+:   platform-specific search path (string)
+
+Returns:
+
+-   list of directories in search path (list of strings)
+
 # Module pandoc.system
 
 Access to system information and functionality.

pandoc.cabal

@@ -429,6 +429,7 @@ library
                  filepath              >= 1.1      && < 1.5,
                  haddock-library       >= 1.8      && < 1.10,
                  hslua                 >= 1.1      && < 1.4,
+                 hslua-module-path     >= 0.0.1    && < 0.1.0,
                  hslua-module-system   >= 0.2      && < 0.3,
                  hslua-module-text     >= 0.2.1    && < 0.4,
                  http-client           >= 0.4.30   && < 0.8,

src/Text/Pandoc/Lua/Packages.hs

@@ -17,6 +17,7 @@ import Foreign.Lua (NumResults)
 import Text.Pandoc.Lua.PandocLua (PandocLua, liftPandocLua, loadDefaultModule)
 
 import qualified Foreign.Lua as Lua
+import qualified Foreign.Lua.Module.Path as Path
 import qualified Foreign.Lua.Module.Text as Text
 import qualified Text.Pandoc.Lua.Module.Pandoc as Pandoc
 import qualified Text.Pandoc.Lua.Module.MediaBag as MediaBag
@@ -43,6 +44,7 @@ pandocPackageSearcher pkgName =
   case pkgName of
     "pandoc"          -> pushWrappedHsFun Pandoc.pushModule
     "pandoc.mediabag" -> pushWrappedHsFun MediaBag.pushModule
+    "pandoc.path"     -> pushWrappedHsFun Path.pushModule
     "pandoc.system"   -> pushWrappedHsFun System.pushModule
     "pandoc.types"    -> pushWrappedHsFun Types.pushModule
     "pandoc.utils"    -> pushWrappedHsFun Utils.pushModule

stack.yaml

@@ -10,7 +10,9 @@ extra-deps:
 - haddock-library-1.9.0
 - skylighting-0.10.2
 - skylighting-core-0.10.2
-- hslua-1.1.2
+- hslua-1.3.0
+- hslua-module-path-0.0.1
+- hslua-module-text-0.3.0.1
 - jira-wiki-markup-1.3.2
 - HsYAML-aeson-0.2.0.0
 - commonmark-0.1.1.3

test/Tests/Lua/Module.hs

@@ -25,6 +25,8 @@ tests =
                   ("lua" </> "module" </> "pandoc-list.lua")
   , testPandocLua "pandoc.mediabag"
                   ("lua" </> "module" </> "pandoc-mediabag.lua")
+  , testPandocLua "pandoc.path"
+                  ("lua" </> "module" </> "pandoc-path.lua")
   , testPandocLua "pandoc.types"
                   ("lua" </> "module" </> "pandoc-types.lua")
   , testPandocLua "pandoc.util"

test/lua/module/pandoc-path.lua

@@ -0,0 +1,17 @@
+local tasty = require 'tasty'
+local path = require 'pandoc.path'
+
+local assert = tasty.assert
+local test = tasty.test_case
+local group = tasty.test_group
+
+return {
+  group 'path separator' {
+    test('is string', function ()
+      assert.are_same(type(path.separator), 'string')
+    end),
+    test('is slash or backslash', function ()
+      assert.is_truthy(path.separator:match '^[/\\]$')
+    end),
+  },
+}