The lib:path library module provides object-oriented path manipulation and file system utilities, inspired by Python's pathlib.

To use this module, load it using the lib prefix:

var path = use("lib:path");

Path (Class)

The Path class wraps a file system path string and exposes object-oriented properties, methods, and operator overloading for joining subpaths using the division operator (/).

Constructor

Path(raw_path = ".")

Constructs a new Path instance. Automatically normalizes path separators (converting Windows \ to /) and strips trailing slashes.

• Parameters:
  • raw_path (String | Path, optional): The input path string or another Path instance. Defaults to ".".

var path = use("lib:path");

var p = path.Path("src/interpreter");

Operator Overloading (/)

The Path class overloads the binary division operator (/) to seamlessly join path segments:

$$\text{Path("src")} \;/\; \text{"interpreter"} \quad \implies \quad \text{Path("src/interpreter")}$$

var path = use("lib:path");

var dir = path.Path("src");
var file_path = dir / "interpreter" / "interpreter.rs";

echo file_path; // Output: src/interpreter/interpreter.rs

Properties

Properties are accessed like variables without parentheses:

.name

Returns the final path component (filename with extension).

echo p.name; // e.g. "interpreter.rs"

.stem

Returns the filename without its extension.

echo p.stem; // e.g. "interpreter"

.extension

Returns the file extension including the leading dot (e.g., ".rs" or ".kyro").

echo p.extension; // e.g. ".rs"

.parent

Returns a new Path object representing the parent directory.

echo p.parent; // e.g. "src/interpreter"

.size

Returns the file size in bytes as a number.

echo p.size; // e.g. 1024

.metadata

Returns a dictionary containing full file system metadata (size, is_file, is_dir, is_symlink, readonly, created, modified, accessed).

var meta = p.metadata;
echo meta["is_file"]; // true

File System Query Methods

exists()

Returns true if the file or directory exists on disk.

if (p.exists()) {
    echo "Path exists!";
}

is_file()

Returns true if the path exists and points to a file.

is_dir()

Returns true if the path exists and points to a directory.

is_absolute()

Returns true if the path is an absolute path.

absolute()

Resolves relative path components (. and ..) and returns an absolute Path instance.

File Read & Write Methods

read_text()

Reads the contents of the file as a UTF-8 string.

var content = p.read_text();

write_text(content = "")

Overwrites the file with string data. Returns self for chaining.

p.write_text("Hello World!");

append_text(content)

Appends text to the file. Creates the file if it does not exist.

read_bytes()

Reads raw binary data from the file and returns a list of byte numbers (0-255).

write_bytes(bytes_list)

Writes a list of byte numbers to a binary file.

File Management Methods

copy_to(dest)

Copies the file to the target destination path.

p.copy_to("backup/interpreter.rs.bak");

rename_to(new_path)

Renames or moves the file/directory to a new path.

remove()

Deletes the file from disk.

p.remove();

create_dir(recursive = true)

Creates a directory at the path.

remove_dir(recursive = false)

Deletes the directory at the path.

Directory Search & Globbing

read_dir()

Returns a list of Path objects for all files and folders directly inside the directory.

var src = path.Path("src");
for (var child in src.read_dir()) {
    echo child.name;
}

glob(pattern)

Searches the directory and returns a list of matching Path objects:

var src = path.Path("src");

// Find all .rs files
var rust_files = src.glob("*.rs");

for (var file in rust_files) {
    echo file; // e.g. "src/kyro.rs"
}