fs

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

NOTE

This module requires LuaFileSystem (lfs).

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

Existence Checks:

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

Filesystem Mutations:

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

Metadata:

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

Reading:

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

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.

Filesystem Mutations

cd(path)

Change the current working directory.

Parameters:

• path (string): Directory path to switch into.

Return:

• changed (true?): true when the directory change succeeds, or nil on failure.
• errmsg (string?): Error message when the change fails.

Example:

fs.cd("src")

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")

cwd()

Return the current working directory.

Return:

• cwd (string?): Current working directory, or nil on failure.
• errmsg (string?): Error message when the lookup fails.
• errcode (integer?): OS error code when available.

Example:

fs.cwd()

link(path, linkpath)

Create a hard link.

Parameters:

• path (string): Existing path to link to.
• linkpath (string): New link path to create.

Return:

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

Example:

fs.link("target.txt", "hardlink.txt")

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)

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

symlink(path, linkpath)

Create a symbolic link.

Parameters:

• path (string): Path to reference from the new symlink.
• linkpath (string): New symlink path to create.

Return:

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

Example:

fs.symlink("target.txt", "symlink.txt")

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

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

Metadata

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

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

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

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

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")

samefile(a, b)

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

Parameters:

• a (string): Input 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

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")

Reading

dir(path, opts?)

Iterator over items in path.

Options:

• recursive: recurse into subdirectories; defaults to false.
• hidden: include hidden entries; defaults to true.
• follow: recurse into symlinked directories; defaults to false.
• type: filter by entry type, such as "file" or "directory"; defaults to nil.

Parameters:

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

Return:

• iterator ((fun(state:table, prev?:string):basename:string?, type:modsFsEntryType?)?): 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.

Options:

• recursive: recurse into subdirectories; defaults to false.
• hidden: include hidden entries; defaults to true.
• follow: recurse into symlinked directories; defaults to false.
• type: filter by entry type, such as "file" or "directory"; defaults to nil.
• names: return basenames; defaults to false.

Parameters:

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

Return:

• paths (mods.List<string>?): Direct child paths, or basenames when opts.names is true.
• err (string?): Error message when traversal setup fails.

Example:

fs.listdir("src")
fs.listdir("src", { names = true })

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")