Nanyx
PlaygroundPackages

file

Reading and writing files

The functions of nanyx.fs/file read and write files, each requiring FileSystem. Import the module under its own name, import nanyx.fs/file as file, to call them as file.read, file.write and so on. Each gives what went wrong as an FsError, which a match takes apart:

::dependency nanyx.fs

import (
  nanyx.fs/file as file
  nanyx.fs/path as path
)

match file.read(path.of("config.json"))
  | #some(text) -> println(text)
  | #error(#notFound) -> println("No config file")
  | #error(e) -> println("Couldn't read the config: {e}")

-- No config file

Writing a file makes it, or replaces what it held, and appending adds to its end:

def log = path.of("run.log")

match file.write(log, "started\n")
  | #ok -> ignore(file.append(log, "finished\n"))
  | #error(e) -> eprintln("Couldn't write the log: {e}")

file.lines reads a file a line at a time, lazily, so a file of any size is never held whole. It gives #error when the file can’t be read, and otherwise a sequence that reads a chunk of the file each time it needs more:

match file.lines(path.of("access.log"))
  | #some(lines) ->
    def errors = lines \seq.filter { line -> string.contains(line, " 500 ") }
    println("{seq.fold(errors, 0, { count, _ -> count + 1 })} server errors")
  | #error(e) -> eprintln("Couldn't read the log: {e}")

Reference

Reading and writing files.

Each function requires FileSystem, and gives what went wrong as an FsError: reading a file that isn’t there is #error(#notFound), and one outside the directories the host gave the program is #error(#permissionDenied). Import the module as import nanyx.fs/file as file to call file.read, file.write and the rest by those names.

read

def read: [Async, FileSystem] Path -> #some(string) | #error(FsError)

The text of the file at at, read as UTF-8.

readBytes

def readBytes: [Async, FileSystem] Path -> #some(array(U8)) | #error(FsError)

The bytes of the file at at.

write

def write: [Async, FileSystem] Path, string -> #ok | #error(FsError)

Writes text to the file at at in UTF-8, in place of what it held, and makes the file when there is none. Its directory must be there already.

append

def append: [Async, FileSystem] Path, string -> #ok | #error(FsError)

Writes text to the end of the file at at in UTF-8, and makes the file when there is none.

exists

def exists: [Async, FileSystem] Path -> bool

Whether there is a file or a directory at at that the program may reach.

delete

def delete: [Async, FileSystem] Path -> #ok | #error(FsError)

Deletes the file at at. A directory is #error(#isDirectory): this deletes only files.

lines

def lines: [Async, FileSystem] Path -> #some([Async, FileSystem] seq(string)) | #error(FsError)

The lines of the file at at, read lazily, a chunk at a time: a file larger than memory is never held whole. Each line is without its line break, \n or \r\n, and a last line with none is a line too. The first chunk is read when this is called, and #error says why the file can’t be read; after that, the file is opened, read and closed again for each chunk the sequence pulls, so a sequence abandoned before its end leaves nothing open. A read that fails partway, because the file was deleted or cut short, say, stops the program with a crash naming the file and why: the sequence never ends early, so a short file and a failed read can’t be mistaken for each other.

match file.lines(path.of("big.log"))
  | #some(lines) ->
    for lines | line -> println(line)
  | #error(e) -> println("Couldn't read the log: {e}")