nupp.io.files

nupp.io.files reads what the filesystem knows about a name: whether it resolves, what it refers to, what a directory contains, and where the platform keeps a user's folders. It also moves and removes names.

local files = nupp.io.files
for _, entry in ipairs(assert(files.list("src"))) do
    print(entry.kind, entry.name)
end

A file's bytes move through the same Reader and Writer contracts a buffer uses, so a parser written against byte I/O works over a file without knowing one is there.

A path argument is a string or a nupp.io.path.Path; a path result is a string. An operation that fails because of the environment answers nil or false with a reason, and a malformed argument raises at the call site.

Querying a name#

info answers one record of attributes:

local info, reason = files.info("nupp.lua")
assert(info, reason)
assert(info.kind == "file")
print(info.size, info.modified, info.readOnly)

info follows symbolic links, so it describes what a name refers to rather than the name itself. size is a byte count, modified is seconds since the Unix epoch with whatever fractional part the platform records, and readOnly is the platform's write refusal rather than a permission model.

exists, isFile and isDirectory answer the same question without the record and without a reason. A missing path is false rather than an error:

if files.isDirectory(candidate) then
    return files.list(candidate)
end

isSymlink is the one query that does not follow, because following is what would hide the answer:

assert(files.createSymlink("target.txt", "alias"))
assert(files.isSymlink("alias"))
assert(files.isFile("alias"))
assert(files.readLink("alias") == "target.txt")

createSymlink takes an optional third argument, "file" or "directory". Only Windows distinguishes the two; elsewhere it is ignored.

Listing a directory#

list answers every entry in a directory, in one call:

local entries, reason = files.list("src/nupp")
assert(entries, reason)

Each entry has a name without any directory part and a kind describing the entry itself, so a link inside a listing reads as symlink rather than as what it points at. The order is the platform's, which is not sorted.

The kind comes from the directory itself rather than a second query per name, so listing a large directory costs one call.

Matching paths#

glob expands a pattern into sorted path strings. * and ? stay within one path component, [abc] and [!abc] select characters, and ** crosses directory boundaries. No matches is an empty list; an invalid pattern or a filesystem error answers a reason.

for _, path in ipairs(assert(files.glob("src/**/*.nupp"))) do
    print(path)
end

Creating, moving and removing#

These three operations move names rather than bytes, so each answers now:

assert(files.createDirectory("out/lib/native"))
assert(files.rename("out/report.tmp", "out/report.json"))
assert(files.remove("out/stale", true))

createDirectory creates every missing parent, and an existing directory succeeds, which is what a caller building a tree wants rather than a race with its own earlier call. rename replaces an existing destination. remove takes a file, a symbolic link, or an empty directory; the second argument removes a directory's contents with it, and without it a populated directory answers a reason.

setReadOnly sets or clears the write refusal that info reports.

Temporary names#

createTemporaryFile and createTemporaryDirectory both take options and answer a path:

local scratch, reason = files.createTemporaryDirectory({prefix = "build-"})
assert(scratch, reason)

The file or directory is created, not proposed, so no second caller can take the name between the answer and the use. directory selects where, defaulting to the platform's temporary directory; prefix and suffix bracket the generated part, which is what puts an extension on a temporary file.

A temporary is an owner: closing it removes what it created, and the checker runs that cleanup at the end of the scope whether the block falls through, returns early, or raises.

do
    local scratch = assert(files.createTemporaryFile({suffix = ".json"}))
    assert(files.write(scratch:toString(), encoded))
    assert(scratch:persist("out/report.json"))
end

persist moves it somewhere permanent and discharges the obligation, so the close that follows does nothing. That pair is the reason to make one: write to a name nobody else can take, then put it where it belongs, so a reader never sees a half-written file under the final name.

Reading and writing a whole file#

read and write move a file's complete contents in one call:

local text, reason = files.read("nupp.lua")
assert(text, reason)
assert(files.write("out/report.json", encoded))

append adds to the end and creates a missing file. copy duplicates one path over another. writeAtomic writes through a temporary beside the destination and renames over it, so an interrupted write leaves the destination as it was rather than half replaced. A failed write removes the temporary rather than leaving it behind.

A NUL byte is content, not a terminator, in every direction.

for line in assert(files.lines("access.log")) do
    print(line)
end

lines closes the file when it reaches the end. A trailing carriage return is removed, so a file written on either platform reads the same. Abandoning the iterator early leaves the file open until it is collected; open it yourself when you mean to stop. A read that fails once iteration has begun raises, because the iterator has no failure channel to answer through.

Reading and writing through a cursor#

open hands over a File and the obligation to close it:

do
    local file = assert(files.open("image.png"))
    local reader = file:newReader()
    print(reader:read(8))
end

The reader and writer satisfy nupp.io.Reader and nupp.io.Writer, so read, readSpan, readInto, transferTo, write, writeSpan and flush mean what they mean over a buffer. Native callers can read and write through checked spans without separating a pointer from its bound. readInto commits the destination buffer only after a successful read, and transferTo streams a file of any size through a fixed window:

do
    local source = assert(files.open("input.bin"))
    local sink = assert(files.open("output.bin", "w"))
    print(source:newReader():transferTo(sink:newWriter()))
end

mode is r, w, a, or the update modes r+, w+ and a+, matching C and Lua. seek(offset, origin) moves the cursor, with origin one of set, current or end; position and size answer where it is and how long the file is. A reader or writer over a closed file answers a reason rather than raising.

Platform directories#

Two queries answer where the process is and where the platform keeps a user's folders:

print(assert(files.currentDirectory()))
print(assert(files.userFolder("documents")))

userFolder takes home, documents, downloads, desktop, pictures, music or videos. It resolves from the environment: the XDG_* variables where they are set, and the platform's conventional names under the home directory otherwise. A desktop that records its folders somewhere else is not consulted, and a folder that does not exist answers a reason rather than a path that is not there.

Waiting#

A whole-file read, write, append, writeAtomic or copy settles on a worker thread rather than on yours, and the call waits for it by suspending. What that means depends on where the call runs, and on nothing the call says:

One call site covers all three. A library that reads a file works inside a game frame and inside a command-line program without knowing which it is in, and a transfer that settled before it was observed never reaches any of this.

The immediate operations cannot suspend, so a region that forbids waiting still permits asking what a path is, listing a directory, or renaming one:

nosuspend do
    if files.isDirectory(candidate) then
        print(#assert(files.list(candidate)))
    end
    print(files.read(candidate)) -- NUPP2701: `read` may suspend
end

Cost#

Reaching nupp.io.files selects the compiler-owned Rust provider, whose filesystem operations use the platform standard library and whose blocking transfers run through the shared native executor, and loads it on first use. A program that never reaches it links nothing and initializes nothing, which is the rule for every facility in the standard library. A target that uses it also carries the suspension runtime, because that is what answers the wait above.

The lane those workers run is bounded three ways: how many transfers may be live, how many bytes they may hold between them, and how large one may be. Past any of the three a submission answers a reason rather than queueing, because a queue that grows with its callers eventually takes the process with it. pendingTransfers answers what the lane is holding.

Metadata, listings and cursor reads through an open File do not use the lane. Scheduling a transfer costs more than those cost to run.

record Entry
    name: string
    kind: Kind
end

name: string

kind: Kind

record File
    function newReader(self): FileReader end

    function newWriter(self): FileWriter end

    function size(self): (integer?, string?) end

    function seek(self, offset: integer?, origin: Origin?): (integer?, string?) end

    function position(self): (integer?, string?) end

    function flush(self): (boolean, string?) end

    function isReleased(self): boolean end

    drop: nosuspend function(takes self: File): nil
    function close(takes self): boolean end
end

newReader: function newReader(self): FileReader

newWriter: function newWriter(self): FileWriter

size: function size(self): integer?, string?

seek: function seek(self, offset: integer?, origin: Origin?): integer?, string?

position: function position(self): integer?, string?

flush: function flush(self): boolean, string?

isReleased: function isReleased(self): boolean

drop: nosuspend function(takes self: File): nil

close: function close(takes self): boolean

record FileReader is io.Reader
    drop: nosuspend function(takes self: FileReader): nil
    function read(self, count: integer): (string?, string?) end

    function readSpan(self, exclusive destination: span.Writable<uint8>): (integer?, string?) end

    function readInto(self, exclusive destination: io.Buffer, offset: integer?, count: integer?): (integer?, string?) end

    function transferTo(self, exclusive destination: io.Writer): (integer?, string?) end

    function close(takes self): nil end
end

drop: nosuspend function(takes self: FileReader): nil

read: function read(self, count: integer): string?, string?

readSpan: function readSpan(self, exclusive destination: span.Writable<uint8>): integer?, string?

readInto: function readInto(self, exclusive destination: io.Buffer, offset: integer?, count: integer?): integer?, string?

transferTo: function transferTo(self, exclusive destination: io.Writer): integer?, string?

close: function close(takes self): nil

record FileWriter is io.Writer
    drop: nosuspend function(takes self: FileWriter): nil
    function write(exclusive self, bytes: string): (boolean, string?) end

    function writeSpan(exclusive self, borrows source: span.ByteSpan): (integer?, string?) end

    function flush(self): (boolean, string?) end

    function close(takes self): nil end
end

drop: nosuspend function(takes self: FileWriter): nil

write: function write(exclusive self, bytes: string): boolean, string?

writeSpan: function writeSpan(exclusive self, borrows source: span.ByteSpan): integer?, string?

flush: function flush(self): boolean, string?

close: function close(takes self): nil

record Info
    kind: Kind
    size: integer
    modified: number
    readOnly: boolean
end

kind: Kind

size: integer

modified: number

readOnly: boolean

type Kind = "file" | "directory" | "symlink" | "other"

type LineIterator = function(): string?

type Mode = "r" | "w" | "a" | "r+" | "w+" | "a+"

type Origin = "set" | "current" | "end"

record TemporaryOptions
    directory: (string | paths.Path)?
    prefix: string?
    suffix: string?
end

directory: (string | paths.Path)?

prefix: string?

suffix: string?

record TemporaryPath
    function toString(self): string end

    function persist(self, destination: string | paths.Path): (boolean, string?) end

    function isReleased(self): boolean end

    drop: nosuspend function(takes self: TemporaryPath): nil
    function close(takes self): boolean end

    metamethod __tostring: function(self): string
end

toString: function toString(self): string

persist: function persist(self, destination: string | paths.Path): boolean, string?

isReleased: function isReleased(self): boolean

drop: nosuspend function(takes self: TemporaryPath): nil

close: function close(takes self): boolean

__tostring: function(self): string

type UserFolder = "home" | "documents" | "downloads" | "desktop" | "pictures" | "music" | "videos"

function append(path: string | paths.Path, bytes: string | io.ByteView): boolean, string?

function copy(from: string | paths.Path, to: string | paths.Path): boolean, string?

function createDirectory(path: string | paths.Path): boolean, string?

function createSymlink(target: string | paths.Path, link: string | paths.Path, kind: ("file" | "directory")?): boolean, string?

function createTemporaryDirectory(options: TemporaryOptions?): affine(TemporaryPath?, destroyOwner), string?

function createTemporaryFile(options: TemporaryOptions?): affine(TemporaryPath?, destroyOwner), string?

do
    local scratch = assert(nupp.io.files.createTemporaryFile({directory = "build"}))
    assert(nupp.io.files.write(scratch:toString(), bytes))
    assert(scratch:persist("build/output.bin"))
end

function currentDirectory(): string?, string?

function exists(path: string | paths.Path): boolean

function glob(pattern: string | paths.Path): {string}?, string?

for _, match in ipairs(assert(nupp.io.files.glob("src/**/*.nupp"))) do
    print(match)
end

function info(path: string | paths.Path): Info?, string?

local info = assert(nupp.io.files.info("nupp.lua"))
assert(info.kind == "file" and info.size > 0)

function isDirectory(path: string | paths.Path): boolean

function isFile(path: string | paths.Path): boolean

function isSymlink(path: string | paths.Path): boolean

function lines(path: string | paths.Path): LineIterator?, string?

function list(path: string | paths.Path): {Entry}?, string?

local entries = assert(nupp.io.files.list("src"))
for _, entry in ipairs(entries) do
    print(entry.kind, entry.name)
end

function open(path: string | paths.Path, mode: Mode?): affine(File?, destroyOwner), string?

do
    local file = assert(nupp.io.files.open("image.png"))
    print(file:newReader():read(8))
end

function pendingTransfers(): integer

function read(path: string | paths.Path): string?, string?

local text, reason = nupp.io.files.read("nupp.lua")
assert(text, reason)

function readLink(path: string | paths.Path): string?, string?

function remove(path: string | paths.Path, recursive: boolean?): boolean, string?

function rename(from: string | paths.Path, to: string | paths.Path): boolean, string?

function setReadOnly(path: string | paths.Path, readOnly: boolean): boolean, string?

function userFolder(which: UserFolder): string?, string?

function write(path: string | paths.Path, bytes: string | io.ByteView): boolean, string?

function writeAtomic(path: string | paths.Path, bytes: string | io.ByteView): boolean, string?