Luau Bindings — io

The require("io") script API — standard Lua io. io.open returns a normal Lua file handle with the usual methods and the usual nil, err failure form; a Lua programmer's file code runs unchanged. The only AntOS-visible differences are drive-letter paths and an optional trailing table to attach DBFS tags/metadata on D:. Design & native core: antos_io; contract: antos_library_design §5–6.

-- io is a global; no require needed
local f = io.open("D:/notes.txt", "r")

Tagged [standard] or [antos].

Opening files

Function Tag Behaviour
io.open(path, mode) [standard] Open path in mode ("r","w","a","r+","w+","a+", +"b"). Returns a file handle, or nil, errmsg [, errno].
io.open(path, mode, opts) [antos] Same, plus an optional trailing opts table (below). Two-arg form unaffected.
io.lines(path [, ...]) [standard] Line iterator over path; opens and auto-closes.
io.close([f]) · io.type(x) [standard] As reference Lua. io.type → "file" / "closed file" / nil.
io.input([f]) · io.output([f]) [standard] Get/set default input/output handle.
io.read(...) · io.write(...) [standard] Read from default input / write to default output.

path is a drive-letter path (D:/scripts/foo.lua, B:/games/rom.bin) — the only thing that differs from a POSIX system, and transparent, because it is just the string the VFS resolves.

The file handle — all [standard]

A normal Lua file object; every method behaves as reference Lua.

Method Behaviour
f:read(...) Formats "a" (all), "l" (line), "L" (line+newline), "n" (number), or a byte count. Legacy "*a" etc. accepted.
f:write(...) Write strings/numbers; returns f or nil, err.
f:lines([...]) Line iterator over the open handle.
f:seek([whence [, offset]]) "set"/"cur"/"end"; returns new position. Works on DBFS BLOBs via SQLite incremental I/O.
f:flush() · f:setvbuf(mode [,size]) As reference Lua.
f:close() Close; commits the DBFS transaction on a D: write. 
local f = io.open("D:/log.txt", "a")
if f then f:write(("[%s] ok\n"):format(os.date("%H:%M:%S"))); f:close() end

for line in io.lines("D:/scripts/list.txt") do print(line) end

Files can be arbitrarily large — SQLite incremental BLOB I/O bounds size by disk, not RAM; seek/streaming work on multi-gigabyte files.

The opts extension ([antos], D: only)

io.open(path, mode, opts) accepts an optional third table on write/append:

Field Meaning
tags array of string tags catalogued in DBFS for the file
meta key→value table of arbitrary metadata 
io.open("D:/notes/idea.txt", "w", {
  tags = { "note", "draft" },
  meta = { author = "anthony" },
})

Rules: the opts table is always last and always optional; it is only meaningful on D:. On a plain FAT volume it is silently ignored (casual cross-volume code never breaks). To fail loudly on intent-to-tag, use fs.tag.

Structural cataloguing happens regardless of opts — DBFS records path/size/mtime/checksum/kind for every D: write from any source; tags/meta are user semantics on top (antos_library_design §7).

Related

Important: The Ant64 family of home computers are at early design/prototype stage, everything you see here is subject to change.