Skip to content

ddn.os.path

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

Module Declaration

module ddn.os.path;

Structs

Path

struct Path

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

Constructor

this(string path);

Constructs a Path from a string.

Parameter Description
path The path string

Example:

auto p1 = Path("foo/bar/baz.txt");
auto p2 = Path("/tmp/example.txt");

Methods

str
string str() const @safe nothrow @nogc pure;

Returns the underlying path string.

Returns: The path as a string.

Attributes: @safe nothrow @nogc pure

name
string name() const;

Returns the final component of the path (file name with extension).

Returns: The file name.

Example:

auto p = Path("/home/user/report.txt");
assert(p.name() == "report.txt");
stem
string stem() const;

Returns the file name without the extension.

Returns: The stem of the file name.

Example:

auto p = Path("/home/user/report.txt");
assert(p.stem() == "report");
suffix
string suffix() const;

Returns the file extension (including the dot).

Returns: The file extension.

Example:

auto p = Path("/home/user/report.txt");
assert(p.suffix() == ".txt");
parent
Path parent() const;

Returns the parent directory of this path.

Returns: A Path representing the parent directory.

Example:

auto p = Path("/home/user/documents/report.txt");
assert(p.parent().str() == "/home/user/documents");
parents
auto parents() const;

Returns a range of all parent directories.

Returns: A range of Path objects representing all ancestors.

Example:

auto p = Path("/home/user/documents/report.txt");
foreach (par; p.parents()) {
    writeln(par.str());
}
// Output:
// /home/user/documents
// /home/user
// /home
join
Path join(string other) const;

Joins this path with another path component.

Parameter Description
other The path component to join

Returns: A new Path with the joined components.

opBinary!"/"
Path opBinary(string op : "/")(string rhs) const;
Path opBinary(string op : "/")(Path rhs) const;

Joins paths using the / operator.

Returns: A new Path with the joined components.

Example:

auto p = Path("/home") / "user" / "file.txt";
// Result: /home/user/file.txt
absolute
Path absolute() const;

Returns the absolute path.

Returns: A Path representing the absolute path.

resolve
Path resolve() const;

Resolves the path to an absolute path with normalization (removes . and .. components).

Returns: A normalized absolute Path.

normalize
Path normalize() const;

Normalizes the path (removes redundant separators and . / .. components).

Returns: A normalized Path.

Example:

auto p = Path("foo//bar/./baz/../file.txt").normalize();
// Result: foo/bar/file.txt
relativeTo
Path relativeTo(Path base) const;

Returns this path relative to the given base path.

Parameter Description
base The base path

Returns: A relative Path.

exists
bool exists() const;

Checks if the path exists in the filesystem.

Returns: true if the path exists.

isFile
bool isFile() const;

Checks if the path is a regular file.

Returns: true if the path is a file.

isDir
bool isDir() const;

Checks if the path is a directory.

Returns: true if the path is a directory.

bool isSymlink() const;

Checks if the path is a symbolic link.

Returns: true if the path is a symlink.

isAbsolute
bool isAbsolute() const;

Checks if the path is absolute.

Returns: true if the path is absolute.

isBlockDevice
bool isBlockDevice() const;

Returns true if the path is a block device.

On POSIX, this checks if the file type is a block device. On Windows, always returns false.

Returns: true if the path is a block device.

isCharDevice
bool isCharDevice() const;

Returns true if the path is a character device.

Returns: true if the path is a character device.

isFIFO
bool isFIFO() const;

Returns true if the path is a FIFO (named pipe).

Returns: true if the path is a FIFO.

isSocket
bool isSocket() const;

Returns true if the path is a socket.

Returns: true if the path is a socket.

readText
string readText() const;

Reads the entire contents of the file as text.

Returns: The file contents as a string.

writeText
void writeText(string content);

Writes text content to the file.

Parameter Description
content The text to write
touch
void touch();

Creates the file if it doesn't exist, or updates its modification timestamp.

remove
void remove();

Removes the file or directory (recursive for directories).

mkdir
void mkdir();

Creates the directory, including any necessary parent directories.

rmdir
void rmdir();

Removes an empty directory.

glob
auto glob(string pattern);

Finds files matching a glob pattern in this directory.

Parameter Description
pattern The glob pattern (e.g., "*.txt", "**/*.d")

Returns: A range of matching Path objects.

Example:

auto dir = Path("/var/log");
auto txtFiles = dir.glob("*.txt");
auto nestedTxt = dir.glob("**/*.txt");
rglob
auto rglob(string pattern);

Recursively finds files matching a glob pattern.

Parameter Description
pattern The glob pattern

Returns: A range of matching Path objects.

iterdir
auto iterdir();

Iterates over the contents of this directory.

Returns: A range of Path objects for directory entries.

Example:

auto items = Path("/tmp").iterdir().map!(p => baseName(p.str())).array;
walk
auto walk(bool topDown = true, bool followSymlinks = false);

Recursively walks the directory tree.

Parameter Description
topDown If true, yield directories before their contents
followSymlinks If true, follow symbolic links

Returns: A range of walk entries containing root, dirs, and files.

Example:

foreach (entry; Path("/project").walk()) {
    writeln("Directory: ", entry.root.str());
    foreach (d; entry.dirs) {
        writeln("  Subdir: ", d.str());
    }
    foreach (f; entry.files) {
        writeln("  File: ", f.str());
    }
}
symlinkTo
void symlinkTo(string target);

Creates a symbolic link at this path pointing to the target.

Parameter Description
target The target path
hardlinkTo
void hardlinkTo(string target);

Creates a hard link at this path pointing to the target.

Parameter Description
target The target path 
string readlink();

Reads the target of a symbolic link.

Returns: The symlink target as a string.

samefile
bool samefile(Path other) const;

Checks if two paths refer to the same file.

Parameter Description
other The other path to compare

Returns: true if both paths refer to the same file.

owner
string owner() const;

Returns the owner username of the file (POSIX only).

Returns: The owner's username.

group
string group() const;

Returns the group name of the file (POSIX only).

Returns: The group name.

toUri
string toUri() const;

Converts the path to a file URI.

Returns: A file:// URI string.

withName
Path withName(string newName) const;

Returns a new path with the file name replaced.

Parameter Description
newName The new file name

Returns: A new Path with the replaced name.

Example:

auto p = Path("foo/bar.txt").withName("baz.py");
// Result: foo/baz.py
withSuffix
Path withSuffix(string newSuffix) const;

Returns a new path with the file extension replaced.

Parameter Description
newSuffix The new extension (including dot)

Returns: A new Path with the replaced extension.

Example:

auto p = Path("foo/bar.txt").withSuffix(".md");
// Result: foo/bar.md
expandTilde
Path expandTilde() const;

Expands ~ to the user's home directory.

Returns: A Path with tilde expanded.

expandVars
Path expandVars() const;

Expands environment variables in the path.

Returns: A Path with variables expanded.

Example:

auto p = Path("$HOME/documents").expandVars();

Static Methods

home
static Path home();

Returns the current user's home directory.

Returns: A Path representing the home directory.

cwd
static Path cwd();

Returns the current working directory.

Returns: A Path representing the current directory.

See Also

  • Python's pathlib — Inspiration for this module