ddn.os.path

Utilities for file and directory path manipulation. Heavily inspired by the Python's pathlib.

This module provides functions for joining, splitting, normalizing, traversing, and querying filesystem paths in a platform-independent manner. It builds upon and extends standard D path and file utilities, offering additional convenience functions for robust path handling.

struct Path
class NotFoundError PathError PermissionError
fn _mapErrnoToPathError _rethrowMapped sameFilesystem windowsDirIdentity

Types 4

structPath

Cross-platform Path object inspired by Python's pathlib. Supports Windows, Linux, and POSIX environments.

Fields
private string _pathThe underlying path string.
Methods
bool isBlockDevice() constReturns `true` if the path is a block device.
bool isFifo() constReturns `true` if the path is a FIFO (named pipe).
bool isCharDevice() constReturns `true` if the path is a character device.
bool isSocket() constReturns `true` if the path is a socket.
string str() const @safe nothrow @nogc pureReturns the string representation of the path.
void symlinkTo(string target) constCreate a symbolic link at this path pointing to the given target.
void hardlinkTo(string target) constCreate a hard link at this path pointing to the given target.
Path[] parents() constReturns all ancestor directories as an array of Path, pathlib-style.
string name() const @safeReturns the name of the file or directory.
string suffix() const @safeReturn the last file suffix (extension) including the leading dot.
Path withName(string newName) const @safeReturns a new Path with the file name replaced.
private bool _hasNameComponent() const @safe
Path withSuffix(string newSuffix) const @safe Return a new Path with the last suffix (extension) replaced. Modeled after pathlib's `with_suffix`: - `newSuffix` must be empty (to remove the last suffix) or start with a dot (e.g., ".md"). -...
Path withStem(string newStem) const @safeReturn a new Path with the stem (base name without its last suffix) replaced, preserving the original suffixes.
string[] suffixes() const @safeReturn all suffixes (extensions) as an array, each including the leading dot.
string stem() const @safeReturns the stem (filename without suffix).
Path parent() const @safeReturns the parent directory as a Path.
string asUri() const @safeReturns a file URI for this path (RFC 8089).
bool exists() const @safeChecks if the path exists in the filesystem.
bool samefile(Path other) constChecks if this path refers to the same file as another path.
bool sameOpenFile(int fd1, int fd2) staticReturns `true` if two open files refer to the same underlying file object.
bool sameOpenFile(File f1, File f2) staticReturns `true` if two `std.stdio.File` handles refer to the same file.
bool isFile() const @safeChecks if the path is a file.
string owner() constGets the owner username of the file (POSIX only).
string group() constGets the group name of the file (POSIX only).
void chmod(uint mode) constChanges file permissions.
void lchmod(uint mode) constChanges file permissions, following symlinks (POSIX only).
void chown(int uid, int gid) constChanges the file's owner user ID and/or group ID.
void lchown(int uid, int gid) constLike `chown` but does not follow symlinks (operates on the link itself).
bool isDir() const @safeChecks if the path is a directory.
bool isSymlink() const @safeChecks if the path is a symbolic link.
string readLink() constCreates a symbolic link at this path pointing to the target.
Path join(string other) const @safeJoins this path with another path or segment.
Path joinpath(T...)(T args) if (args.length > 0) const @safeJoin this path with one or more path segments.
Path expandUser() constExpands a leading tilde in the path to the user's home directory, similar to Python's `os.path.expanduser` / `pathlib.Path.expanduser` semantics.
Path expandVars() constExpands environment variables in the path string.
private string _expandDollarVars(string s) staticExpand `$NAME` and `${NAME}` references using the process environment.
private string _getEnv(string name) staticLook up an environment variable.
Path opBinary(string op : "/")(string other) const @safeOperator overload for joining paths using the ~ operator.
Path opBinary(string op : "/")(Path other) const @safeOperator overload to join with another `Path` using `/`.
bool isRelativeTo(Path other) const @safeReturn whether this path is relative to `other` (pathlib-like).
bool isRelativeTo(string other) const @safeOverload taking a string
Path relativeTo(Path other) const @safeCompute the relative path from `other` to `this` (pathlib-like).
Path relativeTo(string other) const @safeOverload taking a string base
void rename(string target) constRenames or moves the file or directory represented by this `Path` to `target`.
void replace(string target) constOverwrites `target` by moving this path over it. On platforms that support it (POSIX), this is an atomic replacement using `rename(2)`.
Path absolute() const @safeReturns the absolute version of this path.
Path normalize() const @safeReturns a normalized version of this path where redundant separators are collapsed and dot-segments (`.` and `..`) are simplified in a platform-appropriate way.
Path norm() const @safeReturns the normalized version of this path.
Path[] rGlob(string pattern) constHistorical camel-cased alias for `rglob`.
string[] parts() const @safeSplit the path into components similar to Python's pathlib `parts`.
bool isReservedDeviceName() constDetect whether this path's final component is a reserved Windows device name.
string drive() const @safeReturn the drive component of the path (Windows only).
string root() const @safeReturn the root component of the path.
string anchor() const @safeReturn the path anchor (drive + root on Windows; root on POSIX).
Path home() staticReturns the user's home directory as a Path.
Path cwd() staticReturns the current working directory as a Path.
string readText(string encoding = "utf-8", string errors = "strict", string newline = null) constReads the contents of the file as text with configurable decoding and newline handling, inspired by Python's `pathlib.Path.read_text`.
ubyte[] readBytes() constReads the contents of the file as bytes.
void writeText(string content, string encoding = "utf-8", string errors = "strict", string newline = null, bool atomic = false) constWrites text to the file (overwrites) with configurable encoding, newline handling, and optional atomic replace. Modeled after Python's `pathlib.Path.write_text`.
void writeBytes(const(ubyte)[] content, bool atomic = false) constWrites bytes to the file (overwrites). Supports optional atomic replacement.
Path[] iterDir() constReturns the directory contents as an array of Path.
auto iterdir() const Returns a lazy input range of `Path` values for each immediate entry in this directory, similar to Python's `Path.iterdir()`. Notes: - The range yields children in unspecified order (as provid...
auto walk(bool topDown = true, bool followSymlinks = false, bool delegate(const Path) dirFilter = null) constRecursively traverses the directory tree rooted at `this` and yields `WalkEntry` values describing each directory and its immediate children.
void mkdir(bool parents = false) constCreates the directory at this path.
void remove(bool recursive = false) constRemoves the file or directory at this path.
bool isAbsolute() constChecks if the path is absolute.
bool isRelative() constChecks if the path is relative.
DirEntry stat() constReturns the directory entry information for this path.
void utime(SysTime atime, SysTime mtime) constUpdate file timestamps (like POSIX `utime`), following symlinks.
void touch(bool existOk = true, Nullable!uint mode = Nullable!uint.init, Nullable!FileTimes times = Nullable!FileTimes.init) constCreate the file and/or update its timestamps, pathlib-like.
void touch() constConvenience overload matching historical API: create or update with current time.
void copy(string dest, bool recursive = false) constCopies the file or directory to a new location.
Path resolve(bool strict = false) constResolves this path similarly to Python's `Path.resolve(strict=False)`: - Returns an absolute path with symlinks expanded where possible. - Detects symlink loops and throws an exception. - When `str...
Path resolve() constConvenience overload: `resolve()` is equivalent to `resolve(false)`
private string _normKey() const @safeInternal normalization key used for comparisons and hashing.
bool opEquals(const Path rhs) const @safeChecks equality with another `Path` using normalized, platform-aware semantics.
int opCmp(const Path rhs) const @safeCompares this `Path` to another using normalized, platform-aware rules.
size_t toHash() const @safeReturns a hash value for this `Path`, derived from its normalized key.
string toString() const @safe nothrow @nogc pureReturns the string representation of this Path.
bool isMount() constReturns `true` if the path is a mount point.
Path[] glob(string pattern) constGlobs for filesystem entries under this directory that match the given pattern.
Path[] rglob(string pattern) constRecursively globs for entries matching `pattern` under this path.
Constructors
this(string path)Construct a Path from a string.
Nested Templates
WalkEntryA single walk step for `walk()`: the current root directory with its child directories and files.
FileTimesRepresents file timestamps for access and modification time.
classPathError : Exception

Base class for all path-related exceptions thrown by this module.

The error model maps common OS error codes to a small hierarchy of exceptions for consistency across APIs:

  • NotFoundError when a path component is missing (ENOENT/ENOTDIR).
  • PermissionError when access is denied (EACCES/EPERM).
  • PathError for other filesystem-related failures.
Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__, Throwable next = null)Create a `PathError` with a message and optional chained cause.
classNotFoundError : PathError

Raised when the specified path or one of its components does not exist.

Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__, Throwable next = null)
classPermissionError : PathError

Raised when the operation lacks sufficient privileges or access is denied.

Constructors
this(string msg, string file = __FILE__, size_t line = __LINE__, Throwable next = null)

Functions 4

private fnException _mapErrnoToPathError(string op, string p, int err, Throwable next, string file = __FILE__, size_t line = __LINE__)Map an errno value to the PathError hierarchy.
private fnstring windowsDirIdentity(string d)Canonical directory identity on Windows for symlink-loop protection.
private fnvoid _rethrowMapped(string op, string p, Throwable ex, string file = __FILE__, size_t line = __LINE__)Re-throw a filesystem exception mapped into the PathError hierarchy.
fnbool sameFilesystem(string path1, string path2)Check whether two paths live on the same filesystem.