`vfs`

Virtual filesystem overlay - a pure in-memory path→string map that sits in front of the real disk. Read from the overlay first; fall back to the host filesystem if the path isn't in the overlay. Supports set, get, has, remove, list overlay paths, shallow clone, materialise a file from disk into the overlay, and check existence in overlay-or-disk.

Load with: use vfs

What this module does

vfs is useful for testing (inject fake file contents without touching disk), build pipelines (accumulate generated files before writing them all at once), and template systems (stage rendered content in memory). The overlay is a simple object mapping path strings to content strings.

vfsreadordisk is the key function: it tries the overlay first and reads from the actual filesystem only if the path is absent from the overlay.

Quick example

use vfs

v = vfsnew()

# Inject virtual files
v = vfsset(v, "src/app.ilu", "prn(42)")
v = vfsset(v, "config.json", "{}")

# Read (from overlay)
prn(vfsget(v, "src/app.ilu"))  # "prn(42)"

# Has check (overlay only)
prn(vfshas(v, "config.json"))  # tru

# Read or disk (overlay first, then disk)
content = vfsreadordisk(v, "README.md")

# Materialise disk file into overlay
vfsma(v, "existing.txt")

# List overlay paths
prn(vfskeys(v))  # ["src/app.ilu", "config.json"]

# Remove
v = vfsrm(v, "config.json")

# Clone
v2 = vfscopy(v)

Functions

Lifecycle

vfsne()

Creates a new empty VFS overlay {tbl:{}}.

vfsco(v)

Shallow-clones the overlay - creates a new VFS with the same path-to-content mappings.

Read and write

vfsse(v, path, content)

Sets the content for path in the overlay. Both path and content are coerced to strings.

vfsge(v, path)

Returns the overlay content for path, or nil if absent.

vfsre(v, path)

Read-or-disk: returns overlay content if present, otherwise reads from the host filesystem via io_rd.

vfsma(v, path)

Materialise: reads path from disk (or overlay) and stores it in the overlay. Subsequent reads will come from the overlay.

vfsrm(v, path)

Removes a path from the overlay. Returns the updated VFS.

Inspection

vfsha(v, path)

Returns tru if path is in the overlay OR the file exists on disk (best-effort).

vfske(v)

Returns the list of all paths currently stored in the overlay.

Notes

Requires io.