Pathlib

Submodules

Pathlib: An object-oriented filesystem path library for Chapel.

Provides a path record that serves as a wrapper around many common filesystem path operations. This library has the advantage over plain string manipulation using Path and FileSystem in a few ways.

Provides more intuitive path operations like myPath / "subdir vs Path.joinPath(myPath, "subdir").
Helps developers write code that is more clear and semantically meaningful by using a dedicated path type instead of overloading string operations.

Usage:

class PathError : Error

proc init(msg: string)

record path : writeSerializable

A filesystem path. Supports path joining, component access, existence checks, and basic filesystem mutations.

A path can be constructed from a string and freely converted back.

proc init(pathStr: string): Initialize a path from a string representing a filesystem path.

proc init=(other: path): Copy-initialize a path from another path.

operator =(ref x: path, other: path)

proc init=(other: string): Implicitly initialize a path from a string.

operator =(ref x: path, other: string)

operator :(other: string, type t) where t == path: Allow casting from string to path.

proc toStr(): Return the string representation of this path.

operator :(other: path, type t) where t == string: Get the string representation of this path.

proc type join(args ...?n) : path: Join one or more path segments, inserting the platform separator between components. Accepts path or string arguments.

proc type cwd(loc = here) : path throws: Return a new path representing the current working directory.

proc chdir(loc = here) throws: Change the current working directory to this path.

proc pushChdir(loc = here) : chdirManager throws

Returns a contextManager that will enter the given directory and return to the original directory when the context is exited. For example:

var p = new path("/some/dir");
manage p.pushChdir(p) {
  // CWD is now "/some/dir"
  ...
}
// CWD is restored to its original value

proc exists() : bool: Return true if this path refers to an existing file or directory.

proc isFile() : bool: Return true if this path points to a regular file.

proc isDir() : bool: Return true if this path points to a directory.

proc isSymlink() : bool: Return true if this path points to a symbolic link.

proc touch() throws

Create the file at this path if it does not exist, or update its modification time if it does. Analogous to the UNIX touch command.

Throws:: If the file cannot be opened or created.

proc mkdir(parents = false, existOk = false) throws

Create the directory at this path.

Arguments:

parents – If true, create missing parent directories as needed (like mkdir -p).
existOk – If true, do not raise an error when the directory already exists.

Throws:

PathError – If the directory already exists and existOk is false.

proc remove() throws

Remove the file or directory at this path. If this path is a directory, it and all its contents are removed.

Throws:: PathError – If the path does not exist.

proc copy(dest: path, copySymbolically: bool = false, metadata: bool = false, permissions: bool = true) throws

Copy the file or directory at this path to the destination path.

See https://chapel-lang.org/docs/modules/standard/FileSystem.html#FileSystem.copy and https://chapel-lang.org/docs/modules/standard/FileSystem.html#FileSystem.copyTree for more details on the available options for copying files and directories.

proc move(dest: path) throws

Move the file or directory at this path to the destination path.

See https://chapel-lang.org/docs/modules/standard/FileSystem.html#FileSystem.moveDir for more details on moving directories.

iter parts() : string: Yield the individual components of the path as strings.

proc parent : path: The logical parent of this path.

proc name : string: The final component of this path (file or directory name).

proc stem : string: The final component without its suffix (file extension).

proc suffix : string: The file extension of the final component, including the leading dot. Returns an empty string if there is no extension.

proc withName(newName: string) : path

Return a new path with the name changed to newName. The parent directory is preserved.

Arguments:: newName – The new filename (including any extension).

proc withStem(newStem: string) : path

Return a new path with the stem changed to newStem. The parent directory and suffix are preserved.

Arguments:: newStem – The new stem (filename without extension).

proc withSuffix(newSuffix: string) : path

Return a new path with the suffix changed to newSuffix. If newSuffix is empty, the current suffix is removed entirely.

Arguments:: newSuffix – The new extension, including the leading dot (e.g. ".txt"). Pass "" to remove the suffix.

proc isAbsolute() : bool: Return true if this path is absolute (begins with /).

proc resolve() throws: Make the path absolute, resolving any symlinks and expanding environment variables. Returns a new path.

iter findFiles(recursive: bool = false, hidden: bool = false) : path throws: See https://chapel-lang.org/docs/modules/standard/FileSystem.html#FileSystem.findFiles

iter listDir(hidden: bool = false, dirs: bool = true, files: bool = true, listlinks: bool = true) : path throws: See https://chapel-lang.org/docs/modules/standard/FileSystem.html#FileSystem.listDir

iter walkDirs(topdown: bool = true, depth: int = max(int), hidden: bool = false, followlinks: bool = false, sort: bool = false) : path throws: See https://chapel-lang.org/docs/modules/standard/FileSystem.html#FileSystem.walkDirs

operator /(lhs: path, rhs: path) : path: Join two path values.

operator /(lhs: string, rhs: path) : path: Join a string and a path.

operator /(lhs: path, rhs: string) : path: Join a path and a string.

operator /=(ref lhs: path, rhs: path): Append a path segment in place.

operator /=(ref lhs: path, rhs: string): Append a string segment in place.