smelt.fs¶

Tier: Host — Available in every runtime, including headless mode.

Sync filesystem primitives. Errors use the (value, err_string) convention so callers can distinguish failures without pcall.

smelt.fs.copy¶

fun(from: string, to: string): integer?, string?

Copy file from to to. Returns (bytes_copied, nil) on success or (nil, err_string) on failure.

smelt.fs.exists¶

fun(p: string): boolean

Return true if a filesystem entry exists at p.

smelt.fs.glob¶

fun(pattern: string, path: string?, opts: table?): string[]?, string?

Find paths matching pattern under path (defaults to cwd). Returns the matches sorted newest-first, capped at opts.max (default 200). On error returns (nil, err_string).

smelt.fs.is_dir¶

fun(p: string): boolean

Return true if p exists and refers to a directory.

smelt.fs.is_file¶

fun(p: string): boolean

Return true if p exists and refers to a regular file.

smelt.fs.mkdir¶

fun(p: string): boolean, string?

Create directory p (parents must exist). Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.mkdir_all¶

fun(p: string): boolean, string?

Create directory p along with any missing parent directories. Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.read¶

fun(p: string): string?, string?

Read p into a string. Returns (content, nil) on success or (nil, err_string) on failure.

smelt.fs.read_async¶

fun(path: string): string?, string?

Read path off the main thread. Must be called from inside smelt.spawn(fn) or a tool.execute (anything that runs on the Lua task runtime). Returns (content, nil) on success or (nil, err) on failure — same convention as smelt.fs.read.

smelt.fs.read_dir¶

fun(p: string): string[]?, string?

List the immediate entries of directory p. Returns (entries, nil) on success or (nil, err_string) on failure.

smelt.fs.remove_dir¶

fun(p: string): boolean, string?

Delete the empty directory at p. Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.remove_dir_all¶

fun(p: string): boolean, string?

Recursively delete the directory tree rooted at p. Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.remove_file¶

fun(p: string): boolean, string?

Delete the file at p. Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.rename¶

fun(from: string, to: string): boolean, string?

Rename or move from to to. Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.size¶

fun(p: string): integer?, string?

Return the size of file p in bytes. Returns (size, nil) or (nil, err_string) on failure.

smelt.fs.watch¶

fun(path: string, handler: fun(event: { kind: string, detail: string?, paths: string[] }), opts: table?): smelt.Reg

Types: smelt.Reg

Filesystem watcher. Calls handler(event) for each event, where event = { kind, detail?, paths }. kind is one of "create" | "modify" | "remove" | "rename" | "access" | "other" | "any"; detail carries notify's sub-kind when one is reported (e.g. kind = "create" → detail = "file" | "folder"). opts.recursive defaults to true; set false to watch only the immediate entries of a directory. Returns a Reg whose :remove() stops the watcher and cancels the polling coroutine.

smelt.fs.write¶

fun(p: string, contents: string): boolean, string?

Write contents to file p, creating it if necessary. Returns (true, nil) on success or (false, err_string) on failure.

smelt.fs.write_async¶

fun(path: string, contents: string): boolean, string?

Write contents to path off the main thread. Same yielding rules as smelt.fs.read_async. Returns (true, nil) on success or (false, err) on failure — mirrors smelt.fs.write.