diff options
author | Albert Krewinkel <albert@zeitkraut.de> | 2021-01-27 15:17:39 +0100 |
---|---|---|
committer | John MacFarlane <jgm@berkeley.edu> | 2021-02-02 21:04:30 -0800 |
commit | 61b108d52789f20fb03c4f8a74719c1d53021c91 (patch) | |
tree | 9c798380274ade60da91ec98adbbcb2e91e90efc /doc/lua-filters.md | |
parent | 2415b2680a522e89b63abb370c02bfff54b824a2 (diff) | |
download | pandoc-61b108d52789f20fb03c4f8a74719c1d53021c91.tar.gz |
Lua: add module "pandoc.path"
The module allows to work with file paths in a convenient and
platform-independent manner.
Closes: #6001
Closes: #6565
Diffstat (limited to 'doc/lua-filters.md')
-rw-r--r-- | doc/lua-filters.md | 172 |
1 files changed, 172 insertions, 0 deletions
diff --git a/doc/lua-filters.md b/doc/lua-filters.md index 787365212..33c0d27bd 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. |