fs (slug.io)

slug.io.fs

slug.io.fs — filesystem I/O

Read, write, and navigate the filesystem. File handles from openFile must be closed with closeFile — use defer closeFile(handle) for safety.

Simple file operations

val { readFile, writeFile, exists } = import("slug.io.fs")

val content = readFile("config.toml")
writeFile("output.txt", "hello\n")

Streaming reads

val { openFile, readLines, closeFile, READ_MODE } = import("slug.io.fs")

val handle = openFile("data.csv", READ_MODE)
defer closeFile(handle)
val lines = readLines(handle)

File modes

• READ_MODE — open for reading ("r")
• WRITE_MODE — open for writing, truncates existing content ("w")
• APPEND_MODE — open for appending ("a")

@effects(‘fs’)

TOC

• APPEND_MODE
• READ_MODE
• WRITE_MODE
• appendFile(contents, path)
• closeFile(handle)
• exists(path)
• info(path)
• isDir(path)
• listFilesRecursive(path, filter, acc)
• ls(path)
• mkDirs(path)
• openFile(path, mode)
• readFile(path)
• readLine(handle)
• readLines(file, lines)
• rm(path)
• write(handle, content)
• writeFile(contents, path)

Constants

APPEND_MODE

str slug.io.fs#APPEND_MODE

READ_MODE

str slug.io.fs#READ_MODE

WRITE_MODE

str slug.io.fs#WRITE_MODE

Functions

appendFile(contents, path)

fn slug.io.fs#appendFile(@str contents, @str path) -> @num

appends contents to the end of a file, creating it if absent.

Returns the number of bytes written.

@effects(‘fs’)

closeFile(handle)

fn slug.io.fs#closeFile(@num handle) -> nil

closes an open file handle.

@effects(‘fs’)

exists(path)

fn slug.io.fs#exists(@str path) -> @bool

returns true if path exists and is accessible.

@effects(‘fs’)

info(path)

fn slug.io.fs#info(@str path) -> @map

returns metadata about a file or directory as a map.

The map contains at minimum name, size, isDir, and modTime fields.

@effects(‘fs’)

isDir(path)

fn slug.io.fs#isDir(@str path) -> @bool

returns true if path is a directory.

@effects(‘fs’)

listFilesRecursive(path, filter, acc)

fn slug.io.fs#listFilesRecursive(@list path, @fn filter = fn((s)) {true}, acc = []) -> @list

recursively collects all files under the given path(s) matching filter.

path is a list of starting paths. Directories are expanded recursively. filter receives each file path and returns true to include it.

listFilesRecursive(["src"], fn(s) { endsWith(s, ".slug") })
// => ["src/main.slug", "src/lib/util.slug", ...]

ls(path)

fn slug.io.fs#ls(@str path) -> @list

returns a list of filenames in a directory (non-recursive).

@effects(‘fs’)

mkDirs(path)

fn slug.io.fs#mkDirs(...path) -> @bool

creates all directories in the given path(s), including intermediates.

Returns true on success.

@effects(‘fs’)

openFile(path, mode)

fn slug.io.fs#openFile(@str path, @str mode) -> @num

opens a file in the specified mode and returns a file handle.

Always close the handle with closeFile. Use defer closeFile(handle) to ensure it is closed even if an error occurs.

@effects(‘fs’)

readFile(path)

fn slug.io.fs#readFile(@str path) -> @str

reads the entire contents of a file and returns it as a string.

@effects(‘fs’)

readLine(handle)

fn slug.io.fs#readLine(@num handle) -> @str

reads the next line from an open file handle.

Returns nil at end of file. The returned string includes the trailing newline — use str[0:-1] to strip it.

@effects(‘fs’)

readLines(file, lines)

fn slug.io.fs#readLines(@num file, lines = []) -> @list

reads all remaining lines from an open file handle into a list.

Trailing newlines are stripped from each line. Returns an empty list if the file is already at EOF.

rm(path)

fn slug.io.fs#rm(@str path) -> nil

removes a file or empty directory at path.

@effects(‘fs’)

write(handle, content)

fn slug.io.fs#write(@num handle, @str content) -> @num

writes content to an open file handle.

Returns the number of bytes written.

@effects(‘fs’)

writeFile(contents, path)

fn slug.io.fs#writeFile(@str contents, @str path) -> nil

writes contents to a file, creating or truncating it.

@effects(‘fs’)