Files and paths

std.fs and the file builtins, reading, writing, directories and streams.

vlatest

PickleScript has two layers for file access: the compiler builtins, which are flat functions over strings, and std.fs, which wraps them in small classes.

The builtins

Function Signature
read_file read_file(path: string) -> string?
write_file write_file(path: string, text: string) -> bool
file_exists file_exists(path: string) -> bool
delete delete(path: string) -> bool
mkdir mkdir(path: string) -> bool
list_dir list_dir(path: string) -> List<string>?

read_file and list_dir return optionals; the mutating ones return a bool rather than failing.

fn main() {
    println(write_file("notes.txt", "hello"))
    match (read_file("notes.txt")) {
        case some(text) -> { println(text) }
        case none -> { println("missing") }
    }
    println(delete("notes.txt"))
}

Path helpers

import { pathJoin, pathName, pathDir } from std.fs

fn main() {
    println(pathJoin("a", "b"))         // a/b, or a\b on Windows
    println(pathName("/tmp/log.txt"))   // log.txt
    println(pathDir("/tmp/log.txt"))    // /tmp
}
Function Signature
pathJoin pathJoin(a: string, b: string) -> string
pathName pathName(p: string) -> string
pathDir pathDir(p: string) -> string

Path

import { Path } from std.fs

fn main() {
    let p = Path("/tmp/data")
    println(p.text())             // /tmp/data
    println(p.name())             // data
    println(p.dir())              // /tmp
    println(p.exists())           // bool

    let child = p.join("log.txt")
    println(child.text())         // /tmp/data/log.txt
}
Member Signature
text text() -> string
join join(rel: string) -> Path
name name() -> string
dir dir() -> string
exists exists() -> bool

File

import { File } from std.fs

fn main() {
    let f = File("out/notes.txt")
    println(f.exists())

    match (f.openRead()) {
        case some(stream) -> {
            stream.close()
        }
        case none -> { println("cannot open for reading") }
    }

    println(f.write("hello"))
    match (f.read()) {
        case some(text) -> { println(text) }
        case none -> { println("cannot read") }
    }
    println(f.remove())
}
Member Signature
path path() -> string
read read() -> string?
write write(text: string) -> bool
exists exists() -> bool
remove remove() -> bool
openRead openRead() -> Stream?

Dir

import { Dir } from std.fs

fn main() {
    let d = Dir(".")
    println(d.exists())

    match (d.list()) {
        case some(entries) -> {
            for (e in entries) {
                println(e)
            }
        }
        case none -> { println("cannot list") }
    }

    println(Dir("out").create())
}
Member Signature
path path() -> string
list list() -> List<string>?
exists exists() -> bool
create create() -> bool
remove remove() -> bool

Dir.create is the class equivalent of the mkdir builtin.

Streams

For large files, use a stream rather than reading the whole thing into memory.

Builtin Signature
stream_open_read stream_open_read(path: string) -> Stream?
stream_open_write stream_open_write(path: string) -> Stream?
stream_open_append stream_open_append(path: string) -> Stream?
stdout_stream stdout_stream() -> Stream
stderr_stream stderr_stream() -> Stream

All three stream_open_* functions return none when the path cannot be opened. stdout_stream and stderr_stream take no arguments and never fail.

fn main() {
    match (stream_open_write("out.txt")) {
        case some(s) -> {
            s.write(bytes("first line\n"))
            s.write(bytes("second line\n"))
            s.flush()
            s.close()
        }
        case none -> { println("cannot open") }
    }

    match (stream_open_read("out.txt")) {
        case some(s) -> {
            match (s.read(1024)) {
                case some(chunk) -> { println("read {len(chunk)} bytes") }
                case none -> { println("eof") }
            }
            s.close()
        }
        case none -> { println("cannot open") }
    }
}
Stream member Effect
read Read the next chunk, or none at end of file
write Write bytes to the stream
flush Push buffered data out
close Close the stream

For simple console output, std.io is easier than a stream, see Text processing.

Next steps