Docs: Filesystem Helpers

Documentation

Filesystem Helpers

File and directory operations: path checks, directories, links, permissions, file contents and globs. Paths are in the domain's filesystem.

exists / is_file / is_dir

exists(path) is true for anything at the path, is_file(path) only for a regular file and is_dir(path) only for a directory.

Rhai
if is_file(join_path(src.source, "configure")) {
    exec_checked("./configure", ["--prefix=" + PREFIX], #{ cwd: src.source });
}
if is_dir(join_path(WORK, "vendor")) {
    log("vendor directory present");
}

mkdir / rm / mv

  • mkdir(path) creates the directory and its parents, like mkdir -p.
  • rm(pattern) removes every path matching a glob; directories are removed with their contents.
  • mv(src, dst) renames a file or directory.
Rhai
mkdir(join_path(out, "share/man/man1"));
rm(join_path(WORK, "*.tmp"));
mv(join_path(src.source, "config.example"), join_path(src.source, "config.toml"));

ln / ln_force / chmod

ln(target, link) creates a symbolic link; ln_force replaces whatever is at link. chmod(path, mode) takes an octal mode.

Rhai
let bin = join_path(out, "bin");
ln("python3", join_path(bin, "python"));
chmod(join_path(bin, "myapp"), 0o755);

Reading and Writing Files

HelperBehavior
read_file(path)Contents as a string; throws if unreadable.
read_file_or_empty(path)Contents, or an empty string if the file can't be read.
write_file(path, content)Replace the file's contents.
append_file(path, content)Append to the file.
append_line_if_missing(path, line)Append the exact line once; returns true if it was added.
replace_in_file(path, from, to)Replace every occurrence of from in the file.
Rhai
let release = trim(read_file(join_path(src.source, "include/config/kernel.release")));
append_line_if_missing(join_path(out, "etc/shells"), "/bin/zsh");

glob_list / glob_exists

glob_list(pattern) returns the matching paths, sorted; no match is an empty array. glob_exists(pattern) is true if anything matches. An invalid pattern or an unreadable directory is an error.

Rhai
for file in glob_list(join_path(src.source, "src/*.c")) {
    log("found " + file);
}