envzn
0.8 · beta · not released

Library / System / Runtime / Path

CLASSIMPLEMENTS Cloneable, Comparable<Path>, Equatable<Path>, Formattable

Path

Instance class wrapping a filesystem path with rich operations.

Fields 1

String value

Constructors 1

INIT(REFERENCE String value)

Methods 20

METHOD clone() RETURNS Cloneable
reads
METHOD exists() RETURNS boolean
reads

EXISTENCE CHECKS — never fail TRUE iff something exists at this path (file, directory, or other).

METHOD isDirectory() RETURNS boolean
reads

TRUE iff this path exists and is a directory.

METHOD isFile() RETURNS boolean
reads

TRUE iff this path exists and is a regular file.

METHOD parent() RETURNS Path
reads

PURE-ENVZN PATH MANIPULATION

The six methods below — parent / basename / stem / extension / withExtension / join — perform byte-level string manipulation around the / separator. The filesystem is never touched, so they are pure Envzn: cross-platform-consistent semantics (forward-slash only), demagic-plan-aligned scrutability, and one fewer dependency for the future LLVM-IR self-host.

Paths are treated as code-point strings: / is 0x2F and . is 0x2E (both ASCII, one code point each). Multi-byte codepoints inside path segments pass through unchanged. Returns the parent directory. For "/a/b/c" returns "/a/b". For "/a/b/c/" returns "/a/b/c" (the trailing slash makes the filename empty). For a relative single-segment path ("a"), returns the empty path. For "/" returns "/" (root's own parent — fixed point).

METHOD basename() RETURNS String
reads

Filename including extension. For "/a/b/file.txt" returns "file.txt". For a path ending in "/" returns the empty String.

METHOD stem() RETURNS String
reads

Filename without extension. For "/a/b/file.txt" returns "file". For "file.tar.gz" returns "file.tar" (only the last extension is stripped). For dotfiles like ".bashrc" returns ".bashrc" (no leading-dot extension stripped).

METHOD extension() RETURNS String
reads

The file's extension including the leading dot. For "file.txt" returns ".txt". For an extensionless filename returns the empty String. For a leading-dot dotfile (".bashrc") returns the empty String — the leading dot is part of the stem, not an extension.

METHOD withExtension(REFERENCE String ext) RETURNS Path
reads

Returns a new Path with the extension replaced. ext may include or omit the leading dot. For withExtension(".cpp") on "file.txt" returns Path "file.cpp". For withExtension("") strips the extension entirely (returning the stem-form path).

METHOD join(REFERENCE String segment) RETURNS Path
reads

Append segment as a child path component. The result is value + "/" + segment, normalised so a trailing slash on value or a leading slash on segment doesn't produce a double "//". If segment is absolute (starts with '/') it replaces value entirely — matches std::filesystem::path's operator/ semantics.

METHOD resolve() RETURNS | Path
reads

Resolve the path: if relative, prepend CWD; resolve any symbolic links; canonicalise '.' and '..' segments. Canonical resolution requires existence, so a missing path is FAILURE. Pipe-XOR: SUCCESS populates the resolved Path; FAILURE the STATUS.

METHOD listFiles() RETURNS | Array[Path]
reads

DIRECTORY OPERATIONS — STATUS multi-return on failure List the immediate children of this directory as Paths. Each child is this joined with the entry's filename (forward-slash semantics via join()). FAILURE if this path is not an existing directory. An empty directory yields an empty Array (SUCCESS).

METHOD makeDir() RETURNS STATUS
reads

Create the directory (and any missing parents). No-op if it already exists. FAILURE when something that is not a directory is in the way, on a permission error, and for the empty path.

The walk over the parents is here; C makes one directory at a time (ev_fs_make_dir). parent() is strictly shorter than its path for every path but "/", which is always a directory, so the recursion ends; a relative path's walk ends at "", whose parent is the current directory and needs no making.

METHOD remove() RETURNS STATUS
reads

Remove the file or directory tree. FAILURE on permission error or unreachable entries during traversal.

METHOD readText() RETURNS String
reads

I/O — delegates to File

Convenience wrappers — for callers that already have a Path, it's natural to read/write directly without constructing a separate File instance. These are equivalent to: File f := CREATE File(.value); f->readText() / writeText

METHOD writeText(REFERENCE String content) RETURNS STATUS
reads
METHOD modifiedAt() RETURNS | int64
reads

Last modification time, in NANOSECONDS since the Unix epoch. FAILURE when the path cannot be stat'd — it does not exist, or a component of it is not searchable.

Nanoseconds rather than whole seconds because the caller is a build tool: a source edited in the same second as the build that consumed it must still read as newer, or the rebuild is silently skipped. An int64 of nanoseconds since the epoch runs to the year 2262.

IF p->modifiedAt() THEN { int64 ns := $= }
METHOD toString() RETURNS String
reads

STRING REPRESENTATION

METHOD equals(REFERENCE Path other) RETURNS boolean
reads
METHOD isLessThan(REFERENCE Path other) RETURNS boolean
reads