Reference

std/resource/resource

std/resource/src/resource.trb

Resource, EmbeddedBytes and EmbeddedText: the three types a string literal names a file of the package with (docs/design/RESOURCES.md section 4). They are capsules over the stable name the compiler resolved - the owner and name of the package, then the path inside it, always with / - so the only way to make one is a literal.

type Resource

type Resource with Show, Equals, Hash

A file that ships with the program and is read while it runs, found relative to the program and never to the working directory. A literal where a Resource is expected names a file of the package, relative to the file that writes it; torb build copies it to <program>.resources/<stable name> beside the binary, and bytes() and text() read it from there.

Examples

fn load(sheet: Resource): String {
  sheet.name()
}

fn readme(file: Resource): Task<Result<String, ResourceError>> {
  file.text().await()
}

Errors

  • ResourceError from bytes() and text(): not shipped, unreadable, not UTF-8, or the program's location unknown.

Pitfalls

  • A path is compared byte for byte on every platform: ./Hero.png next to hero.png is an error on Windows too.
  • A String value is never a resource: a path chosen while the program runs is a Path, read through std/fs.
  • A binary that is moved needs its <program>.resources directory beside it; without it every read is an Err(NotShipped).

fn name

fn name(): String

What the file is called: acme/game/src/sheets/hero.spr, the text a diagnostic and a log print.

fn bytes

fn bytes(): Task<Result<Bytes, ResourceError>>

The bytes of the file, read from the resource directory of the running program - <program>.resources/ beside its executable, never the working directory. The Task is complete when it is returned on a native target.

Errors

  • ResourceError.NotShipped where the file is not in that directory, such as a binary moved without it.
  • ResourceError.Unreadable where the file is there and cannot be read.
  • ResourceError.Unlocated where the program cannot tell where its executable is.

fn text

fn text(): Task<Result<String, ResourceError>>

The file as text. Bytes that are not UTF-8 are a ResourceError.NotUtf8 with the offset of the first bad byte, and never a replacement character. Its other errors are those of bytes().

fn show

fn show(): String

The stable name, the same text as name().

type EmbeddedBytes

type EmbeddedBytes with Show, Equals, Hash

A file whose bytes are in the binary. Reading them cannot fail: the compiler has the file in its hands.

fn name

fn name(): String

What the file is called: its stable name.

fn show

fn show(): String

The stable name, the same text as name().

type EmbeddedText

type EmbeddedText with Show, Equals, Hash

A file whose text is in the binary, so reading it cannot fail: the compiler reads the file, and checks its UTF-8, where the literal names it (slice 2 of docs/design/RESOURCES.md).

fn text

fn text(): String

The text of the file, as static data of the program. The compiler checked that it is UTF-8.

fn name

fn name(): String

What the file is called: its stable name.

fn show

fn show(): String

The stable name, the same text as name().