fs

Filesystem I/O, metadata, and filesystem path operations.

Usage

fs = require "mods.fs"

fs.mkdir("tmp/cache/app", true)
fs.write_text("tmp/cache/app/data.txt", "hello")
print(fs.read_text("tmp/cache/app/data.txt")) --> "hello"

Functions

Reading:

Function	Description
read_bytes(path)	Read full file in binary mode.
read_text(path)	Read full file in text mode.
dir(path, opts?)	Iterator over items in path.
listdir(path, opts?)	Return direct children of a directory.

Writing:

Function	Description
write_bytes(path, data)	Write full file in binary mode.
write_text(path, data)	Write full file in text mode.
touch(path)	Create file if missing without truncating, or update timestamps if it exists.
rename(oldname, newname)	Rename or move a filesystem entry.
rm(path, recursive?)	Remove a filesystem entry, or a directory tree when recursive is true.
mkdir(path, parents?)	Create a directory.
cp(src, dst)	Copy a file or directory tree.

Metadata:

Function	Description
getsize(path)	Return file size in bytes.
getatime(path)	Return last access time.
getmtime(path)	Return last modification time.
getctime(path)	Return metadata change time.
lstat(path)	Return symlink-aware file attributes.
stat(path)	Return file attributes.
samefile(path_a, path_b)	Return whether two paths refer to the same file, or nil and an error on failure.

Existence Checks:

Function	Description
exists(path)	Return true when a path exists.
lexists(path)	Return true when a path exists without following symlinks.

Reading

read_bytes(path)

Read full file in binary mode.

Parameters:

• path (string): Input path.

Return:

• body (string?): File contents read in binary mode, or nil on failure.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.read_bytes("README.md")

read_text(path)

Read full file in text mode.

Parameters:

• path (string): Input path.

Return:

• body (string?): File contents read in text mode, or nil on failure.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.read_text("README.md")

dir(path, opts?)

Iterator over items in path.

Parameters:

• path (string): Input path.
• opts? ({hidden?:boolean, recursive?:boolean, follow_links?:boolean, type?:string}): Optional traversal options.

Return:

• iterator ((fun(state:table, prev?:string):basename:string?, type:"file"|"directory"|"link"|"fifo"|"socket"|"char"|"block"|"unknown"?)?): Iterator, or nil on failure.
• state (table|string): Iterator state on success, or error message on failure.

Example:

for name, type in fs.dir(path.cwd(), { recursive = true }) do
  print(name, type)
end

listdir(path, opts?)

Return direct children of a directory.

Parameters:

• path (string): Input path.
• opts? ({hidden?:boolean, recursive?:boolean, follow_links?:boolean, type?:string}): Optional traversal options.

Return:

• paths (mods.List<string>?): Direct child paths.
• err (string?): Error message when traversal setup fails.

Example:

fs.listdir("src")

Writing

write_bytes(path, data)

Write full file in binary mode.

Parameters:

• path (string): Input path.
• data (string): Input data.

Return:

• written (true?): true when writing succeeds, or nil on failure.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.write_bytes("tmp.bin", "abc") --> true, nil

write_text(path, data)

Write full file in text mode.

Parameters:

• path (string): Input path.
• data (string): Input data.

Return:

• written (true?): true when writing succeeds, or nil on failure.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.write_text("tmp.txt", "abc") --> true, nil

touch(path)

Create file if missing without truncating, or update timestamps if it exists.

Parameters:

• path (string): Input path.

Return:

• touched (true?): true when the file exists after touch, or nil on failure.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.touch("tmp.txt") --> true, nil

rename(oldname, newname)

Rename or move a filesystem entry.

Parameters:

• oldname (string): Existing path.
• newname (string): Replacement path.

Return:

• renamed (true?): true when the rename succeeds, or nil on failure.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.rename("old.txt", "new.txt")

NOTE

This is an alias for os.rename.

rm(path, recursive?)

Remove a filesystem entry, or a directory tree when recursive is true.

Parameters:

• path (string): Input path.
• recursive? (boolean): Remove a directory tree recursively when true.

Return:

• removed (true?): true when removal succeeds, or nil on failure.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.rm("tmp.txt") --> true, nil
fs.rm("tmp/cache", true) --> true, nil

mkdir(path, parents?)

Create a directory.

Parameters:

• path (string): Input path.
• parents? (boolean): Create missing parent directories when true.

Return:

• created (true?): true when directory creation succeeds, or nil on failure.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.mkdir("tmp/a/b", true)

cp(src, dst)

Copy a file or directory tree.

Parameters:

• src (string): Source path.
• dst (string): Destination path.

Return:

• copied (true?): true when copying succeeds, or nil on failure.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.cp("a.txt", "b.txt")
fs.cp("src", "backup/src")

Metadata

getsize(path)

Return file size in bytes.

Parameters:

• path (string): Input path.

Return:

• size (integer?): File size in bytes.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.getsize("README.md") --> 1234

getatime(path)

Return last access time.

Parameters:

• path (string): Input path.

Return:

• timestamp (number?): Access time (seconds since epoch).
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.getatime("README.md") --> 1712345678

getmtime(path)

Return last modification time.

Parameters:

• path (string): Input path.

Return:

• timestamp (number?): Modification time (seconds since epoch).
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.getmtime("README.md") --> 1712345678

getctime(path)

Return metadata change time.

Parameters:

• path (string): Input path.

Return:

• timestamp (number?): Change time (seconds since epoch).
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.getctime("README.md") --> 1712345678

lstat(path)

Return symlink-aware file attributes.

Parameters:

• path (string): Input path.

Return:

• attrs (LuaFileSystem.Attributes?): Symlink-aware attributes, or nil on failure.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.lstat("README.md")

stat(path)

Return file attributes.

Parameters:

• path (string): Input path.

Return:

• attrs (string|integer|LuaFileSystem.AttributeMode|LuaFileSystem.Attributes?): File attributes, or nil on failure.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.stat("README.md")

samefile(path_a, path_b)

Return whether two paths refer to the same file, or nil and an error on failure.

Parameters:

• path_a (string): Input path.
• path_b (string): Input path.

Return:

• isSameFile (boolean?): True when both paths refer to the same file.
• errmsg (string?): Error message when the check fails.
• errcode (integer?): OS error code when available.

Example:

fs.samefile("README.md", "README.md") --> true

Existence Checks

exists(path)

Return true when a path exists.

Parameters:

• path (string): Input path.

Return:

• exists (boolean): True when the path exists.

Example:

fs.exists("README.md") --> true

NOTE

Broken symlinks return false.

lexists(path)

Return true when a path exists without following symlinks.

Parameters:

• path (string): Input path.

Return:

• exists (boolean): True when the path or symlink entry exists.

Example:

fs.lexists("README.md") --> true

NOTE

Broken symlinks return true.