Luau Bindings — `fs`

The require("fs") script API — the AntOS filesystem extras standard Lua never had: directory listing, stat, mkdir, existence checks, and the DBFS tag / metadata / query surface. Keeping these off os/io is what keeps those two exactly standard. Every function here is [antos]. Design & native core: antos_fs.

local fs = require("fs")
for entry in fs.dir("D:/scripts") do print(entry.name, entry.size) end

All functions are AntOS additions ([antos]); failures return nil, errmsg. Paths are drive-letter paths.

Directory & metadata

Function	Behaviour
`fs.dir(path)`	Iterator yielding `{ name, path, kind="file"\\|"dir", size, mtime }` per entry.
`fs.list(path)`	Same data as an array (whole listing at once).
`fs.stat(path)`	`{ kind, size, mtime, ctime, checksum, tags, meta }` (`tags`/`meta` on `D:` only); `nil, err` if absent.
`fs.exists(path)`	`true`/`false`.
`fs.mkdir(path [, parents])`	Create a directory; `parents=true` → `mkdir -p`.
`fs.remove(path [, recurse])`	Delete a file, or a tree with `recurse=true`.
`fs.copy(src, dst [, opts])`	Copy; `opts.recurse`, and on a `D:` dest `opts.tags`/`opts.meta`.
`fs.move(src, dst)`	Move/rename.
`fs.pwd()`	Current working directory (drive-letter path).
`fs.cd(path)`	Change the current working directory; relative paths resolve against it.

local st = fs.stat("D:/notes/idea.txt")
if st then
  print(st.size, os.date("%Y-%m-%d", st.mtime))
  for _, tag in ipairs(st.tags or {}) do print("#" .. tag) end
end

DBFS tags & metadata (`D:` only)

DBFS auto-catalogues every file structurally; these manage the user semantics on top. Off D: they return nil, err (nowhere to store tags), so intent-to-tag fails loudly.

Function	Behaviour
`fs.tag(path, tags)`	Add tag(s) (string or array).
`fs.untag(path, tags)`	Remove tag(s).
`fs.tags(path)`	Array of a file's tags.
`fs.meta(path [, tbl])`	Get the metadata table, or merge `tbl` into it.

Tag lifetime (policy — antos_library_design §12): system columns always refreshed on write; user tags sticky across content rewrites, cleared on delete.

Querying the catalogue (`D:` only)

Function	Behaviour
`fs.query(filter)`	Entries matching a filter table.
`fs.find(root, filter)`	As `query`, scoped to a subtree (the `find` command's backend).

For arbitrary SQL against the DBFS database (custom tables, joins fs.query can't express), drop to db — fs.query is the safe, shaped layer over the same database.

Filter fields: tag/tags, kind, name (glob), path (prefix), modified_after/modified_before, min_size/max_size, limit, order.

local recent = fs.query{
  tags = { "note", "draft" },
  modified_after = os.time() - 86400,
  order = "mtime desc",
}
for _, e in ipairs(recent) do print(e.path) end

Drives

Function	Behaviour
`fs.drives()`	Mounted drive letters (mirror of `os.list_drives`).
`fs.drive(letter)`	Info for one drive (mirror of `os.drive_info`).

A mounted real floppy is an ordinary drive here — fs.dir("E:/") lists it like anything else. fs has no device surface, by design: to reach the disk below the mount — flux, format detection, copying, formatting — use floppy.

antos_fs (design & native core) · luau_io (opening & reading files) · luau_floppy (the device level beneath a mounted disk) · luau_os · Filesystem · AntOS Libraries

Luau Bindings — fs

Directory & metadata

DBFS tags & metadata (D: only)

Querying the catalogue (D: only)

Drives

Related

Luau Bindings — `fs`

DBFS tags & metadata (`D:` only)

Querying the catalogue (`D:` only)