tecs.io.files#

Resolves game paths and performs complete filesystem operations.

Use assetPath for shipped content, writablePath for persistent mutable state, and cachePath for data the application can reconstruct. Set the publisher and game names before resolving the first writable path:

local files <const> = tecs.io.files
files.setPreferenceIdentity("Ex Nihilo", "Starfarer")

local directory <const> = files.writablePath("saves")
local ok, reason = files.createDirectory(directory)
if not ok then
    error(reason)
end

local path <const> = files.writablePath("saves/slot1.json")
local bytes <const> = tecs.data.encodeJSON({level = 3, hp = 100})
ok, reason = files.writeAtomic(path, bytes)
if not ok then
    error(reason)
end

Filesystem outcomes return a status and a platform reason. Invalid arguments raise because they indicate a defect in the calling program. An atomic write inside a system moves its commit to a worker and suspends the system until the result is ready. glob exposes a caller-owned pull stream so recursive enumeration does not retain a complete tree. Temporary files, temporary directories, and streams are Closeable and fit directly in tecs.scoped.

Every operation that accepts a filesystem location accepts either a string or an immutable Path. String results remain useful at Lua and platform boundaries; wrap one with tecs.io.Path.new when the next operation benefits from component-aware manipulation.

tecs.io.watcher polls paths recorded by read and the built-in asset loaders. It does not walk the whole asset tree.

open uses the standard Lua modes and returns one seekable file cursor. The SDL backend operates on the file directly. A storage backend without random access falls back to its required whole-file operations and retains the bytes until the file closes.

Module contents#

Types#

Functions#

Types#

tecs.io.files.DirectoryEntry record#

DirectoryEntry describes one streamed child.

record tecs.io.files.DirectoryEntry
    path: Path
    name: string
    kind: storagebackend.PathType
    depth: integer
    symlink: boolean
end

tecs.io.files.DirectoryEntry.path field#

Read-only. Contains the complete immutable path to this entry.

tecs.io.files.DirectoryEntry.path: Path

tecs.io.files.DirectoryEntry.name field#

Read-only. Contains the entry name relative to its immediate parent.

tecs.io.files.DirectoryEntry.name: string

tecs.io.files.DirectoryEntry.kind field#

Read-only. Identifies the resolved object's kind.

tecs.io.files.DirectoryEntry.kind: storagebackend.PathType

tecs.io.files.DirectoryEntry.depth field#

Read-only. Reports one for an immediate child and increases during a recursive glob.

tecs.io.files.DirectoryEntry.depth: integer

tecs.io.files.DirectoryEntry.symlink field#

Read-only. Reports whether the final path itself is a symbolic link.

tecs.io.files.DirectoryEntry.symlink: boolean

tecs.io.files.DirectoryStream record#

DirectoryStream is a caller-owned pull cursor over directory entries.

record tecs.io.files.DirectoryStream is Closeable
    close: function(self): boolean, string
    next: function(self): DirectoryEntry, string
    skipDirectory: function(self): boolean
    toArray: function(self): {DirectoryEntry}, string
end

Interfaces#

tecs.io.files.DirectoryStream:close Instance#

function tecs.io.files.DirectoryStream.close(self): boolean, string

Arguments

Returns

tecs.io.files.DirectoryStream:next Instance#

Returns the next entry.

function tecs.io.files.DirectoryStream.next(
    self
): DirectoryEntry, string

Arguments

Returns

tecs.io.files.DirectoryStream:skipDirectory Instance#

Prevents descent into the directory returned by the preceding next call.

The method returns false when the preceding entry was not a directory, was a symbolic link, had no deeper pattern component, or has already been skipped. Calling next first makes an earlier directory no longer eligible for pruning.

function tecs.io.files.DirectoryStream.skipDirectory(self): boolean

Arguments

Returns

tecs.io.files.DirectoryStream:toArray Instance#

Consumes the remaining entries into an array and closes the stream.

Entries returned by earlier next calls are not repeated. A traversal failure discards the partial array and closes the stream.

function tecs.io.files.DirectoryStream.toArray(
    self
): {DirectoryEntry}, string

Arguments

Returns

tecs.io.files.File interface#

File is the seekable cursor returned by open.

interface tecs.io.files.File is types.SeekableReader, types.SeekableWriter
end

Interfaces#

tecs.io.files.FileMode enum#

FileMode selects standard read, write, append, or update behavior.

enum tecs.io.files.FileMode
    "a"
    "a+"
    "r"
    "r+"
    "w"
    "w+"
end

tecs.io.files.GlobOptions record#

GlobOptions controls pattern matching and traversal depth.

record tecs.io.files.GlobOptions
    caseInsensitive: boolean
    maxDepth: integer
end

tecs.io.files.GlobOptions.caseInsensitive field#

Caller-writable. Matches ASCII letters without regard to case when true. Defaults to false, which compares every UTF-8 codepoint exactly on every platform including the ones whose filesystem is not.

tecs.io.files.GlobOptions.caseInsensitive: boolean

tecs.io.files.GlobOptions.maxDepth field#

Caller-writable. Limits traversal to this many levels below the root. Zero yields no entries, one yields immediate children, and nil permits unlimited traversal. Defaults to nil.

tecs.io.files.GlobOptions.maxDepth: integer

tecs.io.files.Info record#

Info describes one resolved path.

record tecs.io.files.Info
    kind: PathType
    size: integer
    createdAt: number
    modifiedAt: number
    accessedAt: number
    readOnly: boolean
end

tecs.io.files.Info.kind field#

Read-only. Identifies the resolved platform object's kind.

tecs.io.files.Info.kind: PathType

tecs.io.files.Info.size field#

Read-only. Reports size in bytes. Zero for a directory.

tecs.io.files.Info.size: integer

tecs.io.files.Info.createdAt field#

Read-only. Reports nanoseconds since the epoch as a double. Zero means the platform or filesystem does not record a creation time.

tecs.io.files.Info.createdAt: number

tecs.io.files.Info.modifiedAt field#

Read-only. Reports modification time in nanoseconds since the epoch.

tecs.io.files.Info.modifiedAt: number

tecs.io.files.Info.accessedAt field#

Read-only. Reports access time in nanoseconds since the epoch.

tecs.io.files.Info.accessedAt: number

tecs.io.files.Info.readOnly field#

Read-only. Reports the portable read-only state of the resolved path.

tecs.io.files.Info.readOnly: boolean

tecs.io.files.LineIterator type#

LineIterator yields each line in a file and returns nil at the end.

type tecs.io.files.LineIterator = function(): string

tecs.io.files.PathInput type#

PathInput accepts either a platform path string or an immutable path object.

type tecs.io.files.PathInput = string | Path

tecs.io.files.PathType enum#

PathType identifies a file, directory or other platform object after following symbolic links.

enum tecs.io.files.PathType
    "directory"
    "file"
    "other"
end

tecs.io.files.SymlinkKind enum#

SymlinkKind selects a file or directory symbolic link.

enum tecs.io.files.SymlinkKind
    "directory"
    "file"
end

tecs.io.files.TemporaryOptions record#

TemporaryOptions selects generated-name details.

record tecs.io.files.TemporaryOptions
    directory: string | Path
    prefix: string
    suffix: string
end

tecs.io.files.TemporaryOptions.directory field#

Caller-writable. Selects the parent directory. Nil uses the operating system's temporary directory.

tecs.io.files.TemporaryOptions.directory: string | Path

tecs.io.files.TemporaryOptions.prefix field#

Caller-writable. Prefixes the generated name. Defaults to "tecs-".

tecs.io.files.TemporaryOptions.prefix: string

tecs.io.files.TemporaryOptions.suffix field#

Caller-writable. Suffixes the generated name. Defaults to an empty string.

tecs.io.files.TemporaryOptions.suffix: string

tecs.io.files.TemporaryPath record#

TemporaryPath owns an automatically removed file or directory.

record tecs.io.files.TemporaryPath is Closeable
    path: Path

    close: function(self): boolean, string
    persist: function(self, destination: string | Path): boolean, string
end

Interfaces#

tecs.io.files.TemporaryPath.path field#

Read-only. Contains the exclusively created path.

tecs.io.files.TemporaryPath.path: Path

tecs.io.files.TemporaryPath:close Instance#

function tecs.io.files.TemporaryPath.close(self): boolean, string

Arguments

Returns

tecs.io.files.TemporaryPath:persist Instance#

Moves the resource to a permanent, absent destination and relinquishes cleanup.

function tecs.io.files.TemporaryPath.persist(
    self, destination: string | Path
): boolean, string

Arguments

Returns

tecs.io.files.UserFolder enum#

UserFolder identifies a well-known platform folder.

enum tecs.io.files.UserFolder
    "desktop"
    "documents"
    "downloads"
    "home"
    "music"
    "pictures"
    "publicShare"
    "savedGames"
    "screenshots"
    "templates"
    "videos"
end

Functions#

tecs.io.files.assetPath Static#

Resolves relative against the asset root.

function tecs.io.files.assetPath(relative: PathInput): string

Arguments#

Returns#

tecs.io.files.assetRoot Static#

Returns the root from which the engine reads content.

function tecs.io.files.assetRoot(): string

Arguments#

None.

Returns#

tecs.io.files.basePath Static#

Returns the directory that contains the executable.

function tecs.io.files.basePath(): string

Arguments#

None.

Returns#

tecs.io.files.cachePath Static#

Returns the system cache directory for this application and creates it if absent.

The operating system may empty this directory between any two runs. Store only reconstructable downloads, compiled artifacts, thumbnails and similar derived data here. Saves, settings and other durable state belong under preferencePath.

function tecs.io.files.cachePath(): string

Arguments#

None.

Returns#

tecs.io.files.copy Static#

Copies the file at from to to, replacing whatever was at to.

The function refuses directories and requires an existing destination parent.

function tecs.io.files.copy(
    from: PathInput, to: PathInput
): boolean, string

Arguments#

Returns#

tecs.io.files.createDirectory Static#

Creates path, and any parents it needs.

It succeeds when the directory already exists.

function tecs.io.files.createDirectory(path: PathInput): boolean, string

Arguments#

Returns#

tecs.io.files.createSymlink Static#

Creates a symbolic link to a file or directory.

The target spelling is stored unchanged, so a relative target is resolved from the link's parent when later opened. kind is required because Windows must choose a file or directory link even for a dangling target.

function tecs.io.files.createSymlink(
    target: PathInput, link: PathInput, kind: SymlinkKind
): boolean, string

Arguments#

Returns#

tecs.io.files.createTemporaryDirectory Static#

Creates an empty temporary directory owned by the returned resource.

Closing recursively removes its contents without following symbolic links. Call persist to keep the complete tree under an absent destination.

function tecs.io.files.createTemporaryDirectory(
    options: TemporaryOptions
): TemporaryPath, string

Arguments#

Returns#

tecs.io.files.createTemporaryFile Static#

Creates an empty temporary file owned by the returned resource.

Creation is exclusive. Closing removes the file; garbage collection is a leak safety net, while tecs.scoped provides deterministic cleanup. Call persist to keep the file under an absent permanent destination.

function tecs.io.files.createTemporaryFile(
    options: TemporaryOptions
): TemporaryPath, string

Arguments#

Returns#

tecs.io.files.currentDirectory Static#

Returns the process working directory.

Command-line tools receive relative paths and resolve them against this directory. It is not where a game reads content from or writes state to: assetRoot, preferencePath and cachePath answer that, and say why. A platform with no working directory answers nil, which is most of the ones that are not a desktop.

function tecs.io.files.currentDirectory(): string, string

Arguments#

None.

Returns#

tecs.io.files.exists Static#

Returns whether anything occupies path.

function tecs.io.files.exists(path: PathInput): boolean

Arguments#

Returns#

tecs.io.files.glob Static#

Opens a pull stream over entries under path that match pattern.

Recursive unless the pattern stops it: with no pattern this walks the whole tree below path. * and ? never match a separator, and ? consumes one UTF-8 codepoint, so "*" is one level, "*/*" is exactly two, and "*.png" matches only immediate children. Results include directories alongside files. Symbolic links are yielded but never followed. The order is the platform's own and is not sorted.

The stream retains only the unvisited names in each directory on its current descent. Close it when leaving early. After receiving a directory, call skipDirectory before next to prune that complete subtree. Call toArray to consume and close the stream when every remaining entry should be retained.

A fixed bound belongs in maxDepth; skipDirectory remains useful when descent depends on the entry itself. The checked example combines both.

function tecs.io.files.glob(
    path: PathInput, pattern: string, options: GlobOptions
): DirectoryStream, string

Arguments#

Returns#

Examples#

local files <const> = tecs.io.files
tecs.scoped(
    "scan levels",
    function(scope: tecs.Scope)
        local stream, reason = files.glob(
            files.assetPath("levels"), nil, {maxDepth = 2}
        )
        if stream == nil then
            error(reason)
        end
        scope:own(stream)
        while true do
            local entry, nextReason = stream:next()
            if entry == nil then
                if nextReason ~= nil then
                    error(nextReason)
                end
                break
            end
            print(entry.depth, entry.path)
            if
                entry.kind == "directory" and entry.name == "generated"
            then
                stream:skipDirectory()
            end
        end
    end
)

tecs.io.files.info Static#

Returns information about path, or nil when nothing occupies it.

Nil is the answer for a path that does not exist, for a broken symbolic link, and when the platform cannot search a directory; the second return separates them.

function tecs.io.files.info(path: PathInput): Info, string

Arguments#

Returns#

tecs.io.files.isDirectory Static#

Returns whether path resolves to a directory.

function tecs.io.files.isDirectory(path: PathInput): boolean

Arguments#

Returns#

tecs.io.files.isFile Static#

Returns whether path resolves to a regular file.

function tecs.io.files.isFile(path: PathInput): boolean

Arguments#

Returns#

tecs.io.files.isSymlink Static#

Returns whether the final object named by path is a symbolic link.

Unlike info, this function does not follow the final link. It does follow links in parent directories, so the result is path introspection and not a security boundary. A path that is absent or cannot be inspected returns false.

function tecs.io.files.isSymlink(path: PathInput): boolean

Arguments#

Returns#

tecs.io.files.lines Static#

Iterates over the lines in a whole file.

The function reads and closes the file before it returns the iterator, so breaking the loop retains only the immutable bytes and no file descriptor. It strips LF and CRLF terminators, returns empty lines between adjacent terminators, and does not invent another empty line after a final terminator. Use open when the input is too large to hold whole.

function tecs.io.files.lines(path: PathInput): LineIterator, string

Arguments#

Returns#

Examples#

local files <const> = require("tecs.io.files")
local nextLine <const> = assert(files.lines("save.txt"))

for line in nextLine do
    print(line)
end

tecs.io.files.load Static#

Compiles a Lua file without running it.

The function reads through the installed storage backend rather than loadfile, records the source for file watching, and uses @path as the compiler's chunk name. The default environment is the caller's global environment. A supplied environment is installed exactly as given and is not a security boundary unless the caller makes it one.

function tecs.io.files.load(
    path: PathInput, environment: {string: any}
): function(...: any): any..., string

Arguments#

Returns#

tecs.io.files.open Static#

Opens a file through one seekable cursor.

The mode follows Lua's standard file modes. "r" opens an existing file for reading and is the default. "w" creates or truncates for writing. "a" creates or preserves for writes that always land at the end. Adding + permits both reading and writing. The cursor starts at byte zero except for "a"; "a+" starts at byte zero for reading while every write still lands at the current end. Seeks may not move past the end.

Close the file even after its last write succeeds. close flushes buffered bytes and can report a delayed storage failure. A backend without direct random access retains the complete file until close.

function tecs.io.files.open(
    path: PathInput, mode: FileMode
): File, string

Arguments#

Returns#

Examples#

local files <const> = require("tecs.io.files")
local file, reason = files.open("world.pack", "w+")
if file == nil then
    error(reason)
end

local wrote, writeReason = file:write("HEADpayload bytes")
if not wrote then
    file:close()
    error(writeReason)
end
local position, seekReason = file:seek("start")
if position == nil then
    file:close()
    error(seekReason)
end
local header <const> = assert(file:read(4))
assert(header == "HEAD")

local closed, closeReason = file:close()
assert(closed, closeReason)

tecs.io.files.preferenceIdentity Static#

Returns the publisher and game names used for writable user data.

The pair starts as "tecs", "tecs" and changes when setPreferenceIdentity succeeds.

function tecs.io.files.preferenceIdentity(): string, string

Arguments#

None.

Returns#

tecs.io.files.preferencePath Static#

Returns the writable directory for this application and creates it if absent.

function tecs.io.files.preferencePath(): string

Arguments#

None.

Returns#

tecs.io.files.read Static#

Reads a whole file and returns its bytes, or nil when there is none there.

The binary string retains embedded NUL bytes. On the SDL backend the transfer uses SDL AsyncIO, suspending a system or blocking a direct caller while the same private completion advances.

function tecs.io.files.read(
    path: PathInput, kind: string
): string, string

Arguments#

Returns#

tecs.io.files.readInto Static#

Reads a whole file directly into an owned buffer.

The operation preserves bytes before offset, grows the destination as needed, and returns the number of bytes written. On the SDL backend the file transfer runs through SDL AsyncIO and never materializes a Lua string. Inside a system it may suspend the logical update; elsewhere the identical call blocks its caller until the transfer settles.

function tecs.io.files.readInto(
    path: PathInput,
    destination: IOBuffer,
    offset: integer,
    kind: string
): integer, string

Arguments#

Returns#

tecs.io.files.readLink Static#

Returns the target spelling stored in a symbolic link.

A relative target remains relative. The function does not resolve it against the link's parent and fails when path is not a symbolic link.

function tecs.io.files.readLink(path: PathInput): Path, string

Arguments#

Returns#

tecs.io.files.remove Static#

Removes a file, or an empty directory.

It does not recurse and fails on a directory with anything in it. It succeeds when there is nothing at path: the result says the path is gone, not that this call is what removed it.

Emptying a tree requires a glob and a deepest-first loop:

local stream = assert(files.glob(root)) local paths = {} while true do local entry, reason = stream:next() if entry == nil then if reason ~= nil then error(reason) end break end paths[#paths + 1] = entry.path end stream:close() table.sort(paths, function(a, b) return #(a:toString()) > #(b:toString()) end) for _, path in ipairs(paths) do files.remove(path) end files.remove(root)

function tecs.io.files.remove(path: PathInput): boolean, string

Arguments#

Returns#

tecs.io.files.rename Static#

Moves from to to, replacing whatever was at to.

Directories move as well as files, and an existing destination is overwritten with no warning and nothing to undo it. Whether this works across filesystems is the platform's business.

function tecs.io.files.rename(
    from: PathInput, to: PathInput
): boolean, string

Arguments#

Returns#

tecs.io.files.setAssetRoot Static#

Overrides the asset root, for a test or a tool.

function tecs.io.files.setAssetRoot(root: PathInput)

Arguments#

Returns#

None.

tecs.io.files.setPreferenceIdentity Static#

Sets the publisher and game names used for writable user data.

SDL combines these values with the current user and platform conventions to choose the directory returned by preferencePath. The defaults are "tecs" and "tecs". Later calls change which directory the next preferencePath, writablePath, or cachePath resolves.

function tecs.io.files.setPreferenceIdentity(
    organization: string, application: string
)

Arguments#

Returns#

None.

tecs.io.files.setReadOnly Static#

Changes the portable read-only state of a path.

On Unix, making a path read-only clears every write bit and making it writable restores only the owner's write bit. The API deliberately does not model platform ACLs, ownership, or executable bits.

function tecs.io.files.setReadOnly(
    path: PathInput, readOnly: boolean
): boolean, string

Arguments#

Returns#

tecs.io.files.userFolder Static#

Returns one of the platform's well-known folders.

Often nil, and legitimately so. A platform that has no such concept says so rather than inventing a path: macOS has no saved-games, screenshots or templates folder and answers nil for all three, and a platform that is not a desktop may have none of them. Treat every one of these as absent until it is not, and never as a place a build may write; preferencePath and cachePath are the two writable roots, with different durability.

function tecs.io.files.userFolder(which: UserFolder): string, string

Arguments#

Returns#

tecs.io.files.writablePath Static#

Resolves relative against the writable root.

function tecs.io.files.writablePath(relative: PathInput): string

Arguments#

Returns#

tecs.io.files.write Static#

Writes bytes to a file, replacing its complete contents.

The default SDL backend transfers through its bounded asynchronous file queue. The call suspends a logical update or blocks an ordinary caller until the complete write settles. It retains an immutable source range for SDL instead of copying a buffer through a Lua string. Embedded NUL bytes remain data and an empty input creates an empty file.

function tecs.io.files.write(
    path: PathInput, bytes: storagebackend.ByteInput
): boolean, string

Arguments#

Returns#

tecs.io.files.writeAtomic Static#

Durably and atomically writes a complete file.

Inside a system on the SDL storage backend, the copy and commit run on a worker and suspend the logical world update. Outside a world update, the same call completes synchronously. Buffers and views are copied before a suspended write begins.

function tecs.io.files.writeAtomic(
    path: PathInput, bytes: ByteInput
): boolean, string

Arguments#

Returns#

Examples#

local save <const> = tecs.io.Path.new(
    tecs.io.files.writablePath("saves"), "slot1.bin"
)
local ok, reason = tecs.io.files.writeAtomic(save, "snapshot bytes")
if not ok then
    error(reason)
end