From 61b108d52789f20fb03c4f8a74719c1d53021c91 Mon Sep 17 00:00:00 2001 From: Albert Krewinkel Date: Wed, 27 Jan 2021 15:17:39 +0100 Subject: [PATCH] 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 | 172 ++++++++++++++++++++++++++++++++ pandoc.cabal | 1 + src/Text/Pandoc/Lua/Packages.hs | 2 + stack.yaml | 4 +- test/Tests/Lua/Module.hs | 2 + test/lua/module/pandoc-path.lua | 17 ++++ 6 files changed, 197 insertions(+), 1 deletion(-) create mode 100644 test/lua/module/pandoc-path.lua diff --git a/doc/lua-filters.md b/doc/lua-filters.md index 7873652125e6..33c0d27bdc5f 100644 --- a/doc/lua-filters.md +++ b/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. diff --git a/pandoc.cabal b/pandoc.cabal index 2f8c255a882e..4b808af849ae 100644 --- a/pandoc.cabal +++ b/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, diff --git a/src/Text/Pandoc/Lua/Packages.hs b/src/Text/Pandoc/Lua/Packages.hs index 5949a1a7d26e..2f1c139db36d 100644 --- a/src/Text/Pandoc/Lua/Packages.hs +++ b/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 diff --git a/stack.yaml b/stack.yaml index dc6fa65177df..da7acd8db4b4 100644 --- a/stack.yaml +++ b/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 diff --git a/test/Tests/Lua/Module.hs b/test/Tests/Lua/Module.hs index d88633cf8223..8be445f656f2 100644 --- a/test/Tests/Lua/Module.hs +++ b/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" diff --git a/test/lua/module/pandoc-path.lua b/test/lua/module/pandoc-path.lua new file mode 100644 index 000000000000..9a5a3f6c8142 --- /dev/null +++ b/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), + }, +}