Skip to content

std::embed

Files a program carries inside itself. An embed declaration names files by pattern, and the compiler finds them when it compiles the program, so a built executable holds them and needs no other file. A file’s bytes are read when the program reads that file, not when it starts (spec):

import std::embed.Files

embed site `static`

fn page() -> String
    Files.read_text(site, "static/index.html")!
end

The value is a Files: a read-only tree whose paths are slash-separated and run from the module root, as the patterns do, whatever directory the declaring file is in (static/index.html). . and the empty path name its root. A path is cleaned first, so ./static//a.css is static/a.css; one that starts with / or leaves the tree with .. is InvalidPath. Errors are std::io’s, as std::fs returns them, so code written for the disk reads an embedded tree with the same case. Every file reports the Unix epoch, 1970-01-01T00:00:00Z, as its modification time, and mode 0o444; a directory reports 0o555.

A path written as a string literal is checked when the program compiles: Files.read_text(site, "static/indx.html") is an error, since site holds no such file, and so is a list, walk or sub of a directory it does not hold, through Files.sub of a literal directory too. A path built at run time is checked when it is read, and its error is a Result as above.

A pattern naming a folder that does not exist yet, such as a frontend’s web/dist before its first build, is a warning in nomi run, nomi check and nomi test: the tree holds the folder empty, a read under it is NotFound, and literal paths under it are not checked. nomi build refuses it, so a built program always holds the files.

Import with import std::embed.

Types

struct Files

opaque — construction surface is private to its defining module

A read-only tree of files, the value of an embed declaration.

fn read(files: Files, p: String) -> Result<Bytes, Error>

type function on Files

The contents of the file at p. A directory is IsADirectory, and a path the tree does not hold is NotFound.

logo = Files.read(site, "static/logo.png")?
files = from_held([("a/b.txt", String.to_bytes("hi"))])

assert Files.read(files, "a/b.txt") == Ok(String.to_bytes("hi"))
assert Files.read(files, "./a//b.txt") == Ok(String.to_bytes("hi"))
assert Files.read(files, "a") == Err(Error.IsADirectory{path: "a"})
assert Files.read(files, "c.txt") == Err(Error.NotFound{path: "c.txt"})
assert Files.read(files, "../x") is Err(Error.InvalidPath{})
fn read_text(files: Files, p: String) -> Result<String, Error>

type function on Files

The contents of the file at p, as text. Contents that are not UTF-8 are InvalidText, with the offset of the first byte that is not.

files = from_held([
    ("a.txt", String.to_bytes("hé")),
    ("b.bin", Bytes.from_list([104, 255])),
])

assert Files.read_text(files, "a.txt") == Ok("hé")
assert Files.read_text(files, "b.bin") == Err(Error.InvalidText{path: "b.bin", offset: 1})
fn list(files: Files, dir: String) -> Result<List<Entry>, Error>

type function on Files

The entries of the directory dir, in name order. Each entry’s path is dir and its name joined with /, as std::fs’s list writes it.

files = from_held([("d/b.txt", String.to_bytes("")), ("d/a/x.txt", String.to_bytes(""))])

assert Files.list(files, "d") == Ok([
        Entry{path: "d/a", name: "a", kind: Kind.Directory},
        Entry{path: "d/b.txt", name: "b.txt", kind: Kind.File},
    ])

assert Files.list(files, "d/b.txt") == Err(Error.NotADirectory{path: "d/b.txt"})
assert Files.list(files, "e") == Err(Error.NotFound{path: "e"})
fn walk(files: Files, root: String) -> Iter<Result<Entry, Error>>

type function on Files

Every entry under root, depth first: each directory’s entries in name order, and a directory’s own entries right after it, as std::fs’s walk orders them. A root that is not a directory is one Err item.

files = from_held([("d/b.txt", String.to_bytes("")), ("d/a/x.txt", String.to_bytes(""))])

walked = Files.walk(files, "d") |> Iter.map(fn e -> Result.map(e, fn e -> e.path)) |> Iter.to_list()
assert walked == [Ok("d/a"), Ok("d/a/x.txt"), Ok("d/b.txt")]
assert Files.walk(files, "none") |> Iter.to_list() == [Err(Error.NotFound{path: "none"})]
fn metadata(files: Files, p: String) -> Result<Metadata, Error>

type function on Files

What is at p: its kind, its size in bytes (0 for a directory), the Unix epoch as its modification time, and its mode.

files = from_held([("a/b.txt", String.to_bytes("hi"))])

assert Files.metadata(files, "a/b.txt") is Ok(Metadata{kind: Kind.File, size: 2, mode: 0o444})
assert Files.metadata(files, "a") is Ok(Metadata{kind: Kind.Directory, size: 0, mode: 0o555})
assert Files.metadata(files, ".") is Ok(Metadata{kind: Kind.Directory})
assert Files.metadata(files, "x") == Err(Error.NotFound{path: "x"})
fn sum(files: Files, p: String) -> Result<String, Error>

type function on Files

The SHA-256 of the contents of the file at p, in lowercase hex. An embedded file’s was taken when the program was compiled, so it is returned without reading the file: http.serve_embedded sends it as the file’s ETag.

files = Files.from_bytes([("a.txt", String.to_bytes("abc"))])

assert Files.sum(files, "a.txt")
    == Ok("ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad")

assert Files.sum(files, "b.txt") == Err(Error.NotFound{path: "b.txt"})
fn from_bytes(entries: List<(String, Bytes)>) -> Files

type function on Files

A tree of the files entries name, each a path and its contents, held in the value rather than embedded: what a test serves in place of an embed. Each path is cleaned (path.clean).

files = Files.from_bytes([("./static//a.css", String.to_bytes("a"))])

assert Files.paths(files) == ["static/a.css"]
assert Files.read_text(files, "static/a.css") == Ok("a")
fn exists(files: Files, p: String) -> Bool

type function on Files

Whether a file or directory is at p. A path that starts with / or leaves the tree is False.

files = from_held([("a/b.txt", String.to_bytes("hi"))])

assert Files.exists(files, "a/b.txt")
assert Files.exists(files, "a")
refute Files.exists(files, "b")
refute Files.exists(files, "/a")
fn paths(files: Files) -> List<String>

type function on Files

The path of every file in the tree, sorted.

files = from_held([("b.txt", String.to_bytes("")), ("a/c.txt", String.to_bytes(""))])

assert Files.paths(files) == ["a/c.txt", "b.txt"]
fn sub(files: Files, dir: String) -> Result<Files, Error>

type function on Files

The tree under the directory dir, with paths from it: what http.file_server_embedded serves a static folder from, so static/index.html is /index.html.

files = from_held([("static/index.html", String.to_bytes("hi")), ("main.css", String.to_bytes(""))])

site = Files.sub(files, "static")!
assert Files.paths(site) == ["index.html"]
assert Files.read_text(site, "index.html") == Ok("hi")

assert Files.sub(files, "main.css") |> Result.map(Files.paths) == Err(
    Error.NotADirectory{path: "main.css"}
)

impl Debug for Files

fn inspect(value: Files) -> String

impl Debug.inspect