lib/path.x

Filesystem locations and the operations on them.

Primary API

Path

Path.absolute

Self Path.absolute(Self path)

Returns an absolute form of path with symbolic links resolved. Missing trailing components are appended to their resolved parent with . and .. normalized, so a path that does not exist yet still has a stable identity.

Raises: <io-fail> when a relative path needs the current directory and it cannot be read.

Source: lib/path.x:102

Path.basename

Self Path.basename(Self path)

Returns the last component of path, ignoring trailing slashes.

Source: lib/path.x:65

Path.copy_file

void Path.copy_file(Path source, Path target)

Copies the regular file source to target, replacing target and giving it source’s permission bits. A target that is already the same file as source is left as it is.

Raises: <not-found> or <io-fail>, including for a directory source.

Source: lib/path.x:450

Path.copy_tree

void Path.copy_tree(Path source, Path target)

Copies source to target: a directory recursively, a symbolic link as a link, and a regular file with Path.copy_file.

Raises: <not-found> or <io-fail>, with EINVAL when source is a directory and target is that directory or inside it.

Source: lib/path.x:490

Path.dirname

Self Path.dirname(Self path)

Returns the directory part of path: . when it has no slash and / for a path directly under the root.

Source: lib/path.x:56

Path.exists

int Path.exists(Path p)

Reports whether p names an existing file, following links.

Source: lib/path.x:129

Path.extension

String Path.extension(Path path)

Returns the extension of path’s last component, including its dot, or NULL when there is none. A leading or trailing dot does not start an extension, so .. and notes. have none.

Source: lib/path.x:82

Path.glob

List Path.glob(Path pattern)

Returns the existing paths that match the glob pattern, sorted. The walk starts at the longest leading directory without a wildcard, spelled as the pattern spells it, and descends only as deep as the pattern can match. As in a shell, a name that begins with a dot matches only where the pattern spells the dot, and a pattern that ends with a slash matches only directories, each returned with a trailing slash. No match returns an empty List.

Source: lib/path.x:350

Path.glob_match

int Path.glob_match(Path pattern, Path path)

Reports whether all of path matches the glob pattern. A path component that begins with a dot matches only a pattern component that begins with one, and a run of slashes matches a run of slashes.

Source: lib/path.x:339

Path.is_dir

int Path.is_dir(Path p)

Reports whether p names a directory, following links.

Source: lib/path.x:132

Path.is_executable

int Path.is_executable(Path path)

Reports whether this process may execute path, as the shell’s -x.

Source: lib/path.x:138

Path.is_file

int Path.is_file(Path p)

Reports whether p names a regular file, following links.

Source: lib/path.x:135

Path.join

Self Path.join(Self base, Path name)

Returns name joined to base with one separating slash. An absolute name, or an empty base, is returned unchanged.

Source: lib/path.x:47

Path.list_dir

List Path.list_dir(Path path)

Returns the names in the directory path, sorted, without . and ...

Raises: <not-found> or <io-fail>.

Source: lib/path.x:180

Path.make_dirs

void Path.make_dirs(Path p)

Creates the directory p and any missing parents. An existing directory is left as it is.

Raises: <io-fail> when a component cannot be created or names an existing non-directory, or <not-found>.

Source: lib/path.x:381

Path.modified_time

double Path.modified_time(Path path)

Returns the modification time of path in seconds since the epoch, with the fraction the filesystem records.

Raises: <not-found> or <io-fail>.

Source: lib/path.x:168

Path.move_to

void Path.move_to(Path source, Path target)

Moves source to target, copying and removing when they are on different filesystems.

Raises: <not-found> or <io-fail>.

Source: lib/path.x:502

Path.new

Path Path.new(const char *)

Provides the class default for Path.new.

See Classes and system macros for the default behavior.

Source: lib/path.x:25

Path.read_text

String Path.read_text(Path path)

Returns the contents of the file at path, or NULL when it is empty.

Raises: <not-found>, <io-fail>, or <bad-arg> when the file contains a NUL byte.

Source: lib/path.x:520

Path.remove_file

void Path.remove_file(Path path)

Removes the file or symbolic link path when it exists.

Raises: <io-fail> when it exists and cannot be removed.

Source: lib/path.x:394

Path.remove_tree

void Path.remove_tree(Path path)

Removes path and everything below it when it exists. Symbolic links are removed, not followed. Removal continues past an entry that cannot be removed.

Raises: <io-fail> naming the first path that could not be removed.

Source: lib/path.x:437

Path.size

long Path.size(Path path)

Returns the size of the file at path in bytes.

Raises: <not-found> or <io-fail>.

Source: lib/path.x:162

Path.stem

String Path.stem(Path path)

Returns path’s last component without its extension.

Source: lib/path.x:89

Path.symlink_to

void Path.symlink_to(Path link, Path target)

Creates the symbolic link link pointing at target.

Raises: <io-fail> when the link cannot be created.

Source: lib/path.x:512

Path.temp_dir

Path Path.temp_dir(void)

Creates a new private directory under TMPDIR, or /tmp, and returns its path. The caller removes it, usually with Path.remove_tree.

Raises: <io-fail> when the directory cannot be created.

Source: lib/path.x:536

Path.walk

Iter Path.walk(Path root, Iter dest)

Returns a lazy iterator over every path below the directory root, parents before their contents and siblings sorted. Symbolic links to directories are listed but not followed, and a directory that cannot be read is listed without its contents. Only the paths not yet visited are held; the yielded paths live in the active pool.

#include "path.x"
int main(void) {
Path source = "src";
foreach (Path path, source.walk()) printf("%s\n", path);
long units = source.walk().filter(%!(p) => p.str().endswith(".x")).count();
  return units >= 0 ? 0 : 1;
}

Raises: <not-found> or <io-fail> when root cannot be listed, and <io-fail> from a pull when a directory vanishes during the walk.

Source: lib/path.x:232

Path.write_text

void Path.write_text(Path path, String text)

Replaces the contents of the file at path with text.

Raises: <not-found> when the directory does not exist, or <io-fail>.

Source: lib/path.x:526

Public types

Path

class Path String

A String that names a filesystem location. A literal or a String converts to a Path wherever one is expected, and a Path passes wherever a String is expected. Slicing and + are String operations.

Source: lib/path.x:25

Design notes

A Path is a String that names a filesystem location; its methods read and change the files it names. A failure raises <not-found> when a named path does not exist and <io-fail> for any other host failure, both with operation, path, and errno details. Removing a path that is already absent succeeds.

The path-part methods only examine text. dirname and basename follow POSIX, ignoring trailing slashes. Glob patterns use * and ? within one path component, [...] character classes, ** for any number of components, and backslash to quote the next character. As in a shell, a wildcard does not match a leading dot; spell the dot to match it.

Tests and examples

make verify (unittest/test-path.x) and make examples (scripts/line-counts).