filesystem
The file system, as a context a host provides
FileSystem is in the file system’s interface package, nanyx.fs, which the compiler ships. The console host
provides it, and its prelude brings FileSystem, Path and FsError into every module of a program; the
functions that use it are in file and dir, and paths are made with path. A
script names the package with ::dependency nanyx.fs, and a package lists it in its manifest’s dependencies at the
compiler’s version. Any function that reads or writes files declares [Async, FileSystem] in its type, as a
library’s do, since a call waits for the file system: a library gets FileSystem, and FsError, by importing
nanyx.fs/filesystem, and Async by importing nanyx/async.
::dependency nanyx.fs
import (
nanyx.fs/file as file
nanyx.fs/path as path
)
def colour: [Async, FileSystem] () -> string = {
match file.read(path.of("colour.txt"))
| #some(text) -> text
| #error(_) -> "blue"
}
println(colour())
-- blue
Under nanyx run, a program reaches the current directory and what is in it, and the one directory
--allow-dir names. A path anywhere else, whether relative, as
../secret.txt, or absolute, is #error(#permissionDenied).
Reference
The file system, as a context a host provides.
Code that reads or writes files declares [Async, FileSystem] and calls the functions of
file and dir, which come from whichever FileSystem instance its caller
supplies. The console host (nanyx.console) supplies one to the program’s entry point, on WASI’s
file functions, which sees the current directory and those nanyx run --allow-dir adds; a host
that doesn’t provide it guarantees that nothing in the program touches the file system. A library
depends on nanyx.fs and imports nanyx.fs/filesystem.
FsError
type FsError = #notFound | #permissionDenied | #isDirectory | #notDirectory | #alreadyExists | #other(string)
Why a file or directory couldn’t be read, written, deleted or made: there is nothing at the path;
the program may not reach it (a path outside the directories the host gave it is this too); it
is a directory where a file was meant, or the other way round; or there is something at the path
already. Anything else is #other, with what the host said.
FileSystem
context FileSystem = (
readFile: [Async] Path -> #some(string) | #error(FsError)
readFileBytes: [Async] Path -> #some(array(U8)) | #error(FsError)
readFileChunk: [Async] Path, int, int -> #some(string) | #error(FsError)
writeFile: [Async] Path, string -> #ok | #error(FsError)
appendFile: [Async] Path, string -> #ok | #error(FsError)
pathExists: [Async] Path -> bool
deleteFile: [Async] Path -> #ok | #error(FsError)
listDirectory: [Async] Path -> #some(list(string)) | #error(FsError)
createDirectory: [Async] Path -> #ok | #error(FsError)
)
The file system, which a host supplies. Its members are the operations a host implements; code
calls the functions of file and dir, which are written on them.
readFile: The text of the file atat, read as UTF-8.readFileBytes: The bytes of the file atat.readFileChunk: Up tolengthbytes of the file atat, from byteoffseton: fewer at its end, and none past it, but for anoffsetpast its end, which is an error: the file is shorter than it was. The file is opened for each call, and closed before it returns.writeFile: Writestextto the file atatin UTF-8, in place of what it held, making it when there is none.appendFile: Writestextto the end of the file atatin UTF-8, making it when there is none.pathExists: Whether there is a file or a directory atatthat the program may reach.deleteFile: Deletes the file atat.listDirectory: The names of what the directory atatholds, in no order, without.and...createDirectory: Makes the directoryat, in a directory that is there already.