Nanyx
PlaygroundPackages

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 at at, read as UTF-8.
  • readFileBytes: The bytes of the file at at.
  • readFileChunk: Up to length bytes of the file at at, from byte offset on: fewer at its end, and none past it, but for an offset past 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: Writes text to the file at at in UTF-8, in place of what it held, making it when there is none.
  • appendFile: Writes text to the end of the file at at in UTF-8, making it when there is none.
  • pathExists: Whether there is a file or a directory at at that the program may reach.
  • deleteFile: Deletes the file at at.
  • listDirectory: The names of what the directory at at holds, in no order, without . and ...
  • createDirectory: Makes the directory at, in a directory that is there already.