nupp.io.path

nupp.io.path answers an immutable path value whose joining, normalizing and splitting follow the platform's own rules. Reach for it when a program builds a filesystem name or takes one apart, rather than when it reads the bytes behind one.

const path = nupp.io.path

local source = path.newPath("src", "app", "..", "main.nupp"):normalize()
assert(source:toString() == "src" .. path.separator() .. "main.nupp")
assert(source:fileName() == "main.nupp")

Every operation answers a new path, and two paths are equal when their native text is. tostring(path) and path:toString() return that same text.

Building a path#

path.newPath(first, parts...) joins its components using the current platform's rules. join appends more to a path already built, and both accept a string or another path. Path has no public constructor; creation goes through newPath, which interns recent paths in a bounded LRU cache.

const path = nupp.io.path

local native = path.newPath("out"):join("lib", "native")
assert(native:fileName() == "native")

currentDirectory and separator are functions on the module beside the record, because neither builds a path out of components:

const path = nupp.io.path

local current, reason = path.currentDirectory()
assert(current, reason)
local log = current:join("var", "app.log"):withExtension("jsonl")
assert(log:extension() == "jsonl")

Normalizing and resolving#

normalize removes lexical . and .. components without touching the filesystem, so it answers even for a path that does not exist:

const path = nupp.io.path

assert(path.newPath("src", "app", "..", "main.nupp"):normalize():stem() == "main")

The operations that consult the process or filesystem can fail, as can a relative path whose base uses a different coordinate system. Each answers nil with a reason when it does.

• absolute() resolves the path against the process's working directory.
• resolve(parts...) makes it absolute, appends the parts, and normalizes.
• canonicalize() asks the filesystem for the real path, following every symbolic link, which requires the path to exist.
• relativeTo(base) expresses the path against another one, when both share a coordinate system. A path expressed against itself answers ., the path that stays where the base already is.

const path = nupp.io.path

local real, reason = path.newPath("src"):canonicalize()
assert(real, reason)
assert(real:isAbsolute())

Path components#

parent answers another path or nil. fileName, stem and extension answer the final component, that component without its extension, and the extension without its dot:

const path = nupp.io.path

local source = path.newPath("src", "main.nupp")
assert(source:fileName() == "main.nupp")
assert(source:stem() == "main")
assert(source:extension() == "nupp")
assert(assert(source:parent()):toString() == "src")

withFileName and withExtension replace one component. Each takes one path component and raises when handed text that is not one, so a separator smuggled into a file name is reported where it was written rather than carried into the path it would have produced:

const path = nupp.io.path

local report = path.newPath("out", "report.tmp"):withExtension("json")
assert(report:fileName() == "report.json")

isAbsolute and isRelative classify a path without accessing the filesystem.

function newPath(first: string | Path, ...: string | Path): Path

const path = nupp.io.path
local source = path.newPath("src", "main.nupp")

record Path
    function toString(self): string end

    function join(self, ...: string | Path): Path end

    function normalize(self): Path end

    function absolute(self): (Path?, string?) end

    function resolve(self, ...: string | Path): (Path?, string?) end

    function canonicalize(self): (Path?, string?) end

    function relativeTo(self, base: string | Path): (Path?, string?) end

    function parent(self): Path? end

    function fileName(self): string? end

    function stem(self): string? end

    function extension(self): string? end

    function withFileName(self, name: string): Path end

    function withExtension(self, extension: string): Path end

    function isAbsolute(self): boolean end

    function isRelative(self): boolean end

    metamethod __tostring: function(self): string
    metamethod __eq: function(self, any): boolean
end

toString: function toString(self): string

join: function join(self, ...: string | Path): Path

normalize: function normalize(self): Path

absolute: function absolute(self): Path?, string?

resolve: function resolve(self, ...: string | Path): Path?, string?

canonicalize: function canonicalize(self): Path?, string?

relativeTo: function relativeTo(self, base: string | Path): Path?, string?

parent: function parent(self): Path?

fileName: function fileName(self): string?

stem: function stem(self): string?

extension: function extension(self): string?

withFileName: function withFileName(self, name: string): Path

withExtension: function withExtension(self, extension: string): Path

isAbsolute: function isAbsolute(self): boolean

isRelative: function isRelative(self): boolean

__tostring: function(self): string

__eq: function(self, any): boolean

function currentDirectory(): Path?, string?

function separator(): string