path

local path = require 'path'

The path module contains functions for analyzing and altering file path strings.

It is essentially an interface to Rust’s std::path.

Functions

path.ancestors(path)

Return a list of path and its ancestors.

Return type:

sequence

Example

local path = require 'path'

-- a is:
--  '../some/path/foo/bar'
--  '../some/path/foo'
--  '../some/path'
--  '../some'
--  '..'
--  ''
for i,a in ipairs(path.ancestors('../some/path/foo/bar')) do

end

See also

Rust’s std::path::Path.ancestors.

Version History

Version	Notes
0.3.0	Added

path.canonicalize(path)

Return the canonical, absolute form of path with all intermediate components and symbolic links resolved.

If path is invalid, nil is returned instead.

Return type:

string

See also

Rust’s std::path::Path.canonicalize.

Version History

Version	Notes
0.3.0	Added

path.components(path)

Return a list of components that make up path.

When parsing the path, there is a small amount of normalization:

Repeated separators are ignored, so a/b and a//b both have a and b as components.

Occurrences of . are normalized away, except if they are at the beginning of the path. For example, a/./b, a/b/, a/b/. and a/b all have a and b as components, but ./a/b starts with an additional cur-dir component.

A trailing slash is normalized away, /a/b and /a/b/ are equivalent.

Note that no other normalization takes place; in particular, a/c and a/b/../c are distinct, to account for the possibility that b is a symbolic link (so its parent isn’t a).

Components are returned as a sequence of strings. The first string is the type of component, and any following strings are the path fragment(s) of the component.

The component type will be one of the following values:

Value	Description
prefix-verbatim	A verbatim prefix, e.g. \\?\\foo.
prefix-verbatim-unc	A verbatim prefix using Windows’ Uniform Naming Convention, e.g. \\?\\UNC\server\share.
prefix-verbatim-disk	A verbatim disk prefix, e.g. \\?\C:.
prefix-device-ns	A device namespace prefix, e.g. \\.\COM1.
prefix-unc	A Windows’ Uniform Naming Convention prefix, e.g. \\server\share.
prefix-disk	A prefix for a given disk drive, e.g. C:.
root-dir	The root directory component, appears after any prefix an before anything else.
cur-dir	A reference to the current directory, i.e. ..
parent-dir	A reference to the parent directory, i.e. ...
normal	A normal path component, e.g. a and b in a/b.

Return type:

sequence

Example

local path = require 'path'

-- c is:
--  {'parent-dir'}
--  {'normal', 'foo'}
--  {'normal', 'bar'}
for i,c in ipairs(path.components('../foo/bar')) do

end

See also

Rust’s std::path::Path.components.

Version History

Version	Notes
0.3.0	Added

path.endswith(path, child)

Returns true if child is a suffix of path.

Only considers whole path components to match.

Return type:

boolean

See also

Rust’s std::path::Path.ends_with.

Version History

Version	Notes
0.3.0	Added

path.exists(path)

Returns true if path points at an existing entity.

If an error occurs, information is logged and nil is returned instead.

Return type:

boolean

See also

Rust’s std::path::Path.try_exists.

Version History

Version	Notes
0.3.0	Added

path.extension(path)

Return the extension (without the leadin dot) of path, if possible.

The extension is:

• nil if there is no file name

• nil if there is no embedded .

• nil if the file name begins with . and no other . within

• Otherwise, the portion of the file name after the final .

Return type:

string

See also

Rust’s std::path::Path.extension.

Version History

Version	Notes
0.3.0	Added

path.filename(path)

Return the final component of path, if there is one.

If the path is a normal file, this is the file name. If it’s the path of a directory, this is the directory name.

Returns nil if the path terminates in ...

Return type:

string

See also

Rust’s std::path::Path.file_name.

Version History

Version	Notes
0.3.0	Added

path.filestem(path)

Return the stem (non-extension) portion of the file name in path.

The stem is:

• nil if there is no file name

• The entire file name if there is no embedded .

• The entire file name if the file name begins with . and has no other . within

• Otherwise, the portion of the file name before the final .

Return type:

string

See also

Rust’s std::path::Path.file_stem.

Version History

Version	Notes
0.3.0	Added

path.hasroot(path)

Return true if path has a root component.

Return type:

boolean

See also

Rust’s std::path::Path.has_root.

Version History

Version	Notes
0.3.0	Added

path.isabsolute(path)

Return true if path is absolute, i.e., it is independent of the current directory.

Return type:

boolean

See also

Rust’s std::path::Path.is_absolute.

Version History

Version	Notes
0.3.0	Added

path.isdir(path)

Return true if path exists and is pointing at a directory.

Return type:

boolean

See also

Rust’s std::path::Path.is_dir.

Version History

Version	Notes
0.3.0	Added

path.isfile(path)

Return true if path exists and is pointing at a regular file.

Return type:

boolean

See also

Rust’s std::path::Path.is_file.

Version History

Version	Notes
0.3.0	Added

path.isrelative(path)

Return true if path is relative.

Rtype::

boolean

See also

Rust’s std::path::Path.is_relative.

Version History

Version	Notes
0.3.0	Added

path.issymlink(path)

Return true if path exists and is pointing at a symbolic link.

Return type:

boolean

See also

Rust’s std::path::Path.is_symlink.

Version History

Version	Notes
0.3.0	Added

path.join(path1, path2)

Return a new path from path2 adjoined to path1.

If path2 is absolute, it will be returned instead.

Return type:

string

See also

Rust’s std::path::Path.join.

Version History

Version	Notes
0.3.0	Added

path.parent(path)

Return path without its final component, if there is one.

Returns '' for relative paths with one component, or nil if the path terminates in a root or prefix, or if it’s an empty string.

Return type:

string

See also

Rust’s std::path::Path.parent.

Version History

Version	Notes
0.3.0	Added

path.startswith(path, base)

Returns true if base if a prefix of path.

Only considers whole path components to match.

Return type:

boolean

See also

Rust’s std::path::Path.starts_with.

Version History

Version	Notes
0.3.0	Added

path.stripprefix(path, base)

Returns a path that when joined onto base yields path.

Return type:

string

See also

Rust’s std::path::Path.strip_prefix.

Version History

Version	Notes
0.3.0	Added

path.withextension(path, extension)

Return path but with the given extension.

Return type:

string

See also

Rust’s std::path::Path.with_extension.

Version History

Version	Notes
0.3.0	Added

path.withfilename(path, filename)

Return path but with the given filename.

If path already ends in a filename, it will be replaced.

Return type:

string

See also

Rust’s std::path::Path.with_file_name.

Version History

Version	Notes
0.3.0	Added