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.
Exports
Section titled “Exports”Types
struct Files
Section titled “struct Files”struct Files
opaque — construction surface is private to its defining module
A read-only tree of files, the value of an embed declaration.
Files.read
Section titled “Files.read”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{})
Files.read_text
Section titled “Files.read_text”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})
Files.list
Section titled “Files.list”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"})
Files.walk
Section titled “Files.walk”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"})]
Files.metadata
Section titled “Files.metadata”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"})
Files.sum
Section titled “Files.sum”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"})
Files.from_bytes
Section titled “Files.from_bytes”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")
Files.exists
Section titled “Files.exists”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")
Files.paths
Section titled “Files.paths”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"]
Files.sub
Section titled “Files.sub”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"}
)
Files.inspect
Section titled “Files.inspect”impl Debug for Files
fn inspect(value: Files) -> String
impl Debug.inspect