fs

File system operations. All paths are strings. Functions that write to the file system return null on success.

Functions

Reads the entire file at path and returns its contents as a string.

let content = fs.read("config.txt")
say content

Writes content to the file at path, creating or overwriting the file.

fs.write("output.txt", "Hello, world!")

Appends content to the file at path. Creates the file if it does not exist.

fs.append("log.txt", "New log entry\n")

Returns true if a file or directory exists at path.

if fs.exists("config.json") {
    say "Config found"
}

Returns an array of file and directory names in the directory at path. Names only, not full paths.

let files = fs.list("./src")
// ["main.fg", "utils.fg", "lib"]

Deletes a file or directory (recursively) at path.

fs.remove("temp.txt")
fs.remove("build/")     // removes directory and all contents

Creates the directory at path, including any necessary parent directories.

fs.mkdir("build/output/logs")

Copies a file from source to destination. Returns the number of bytes copied.

let bytes = fs.copy("original.txt", "backup.txt")
say bytes  // e.g. 1024

Renames or moves a file or directory.

fs.rename("draft.txt", "final.txt")

Returns the size of the file at path in bytes.

let s = fs.size("data.bin")
say s  // e.g. 4096

Returns the file extension without the leading dot. Returns an empty string if none.

fs.ext("photo.png")     // "png"
fs.ext("Makefile")      // ""

Reads a JSON file and returns the parsed Forge value (object, array, etc.).

let config = fs.read_json("config.json")
say config.name

Serializes value as pretty-printed JSON and writes it to path.

let data = { name: "forge", version: "0.3.3" }
fs.write_json("package.json", data)

Reads a file and returns an array of strings, one per line.

let lines = fs.lines("data.csv")
say len(lines)  // number of lines

Returns the directory portion of path.

fs.dirname("/home/user/file.txt")  // "/home/user"

Returns the file name portion of path.

fs.basename("/home/user/file.txt")  // "file.txt"

Joins two path segments with the platform path separator.

fs.join_path("/home", "user")  // "/home/user"

Returns true if path is a directory.

fs.is_dir("/tmp")      // true
fs.is_dir("file.txt")  // false

Returns true if path is a regular file.

fs.is_file("main.fg")  // true
fs.is_file("/tmp")      // false

Returns the path to the system temporary directory.

let tmp = fs.temp_dir()
say tmp  // e.g. "/tmp"