Embedding files

A program can carry its files inside its executable: help text, templates, default settings, or a folder of data. fb reads them as it builds, so the program ships as one file and can’t lose them.

1. Embed a text file

EmbedText gives a file’s text as a String known at compile time, which a Const can hold. The path is from the folder of the file the call is in.

Usage: stock [options] <file>
  -l, --low <n>  List items with fewer than n left

Import std.core
Import std.text

Const Help = EmbedText("help.txt")

Print(Help)
Print("{Help.Length} characters, built in")

Usage: stock [options] <file>
  -l, --low <n>  List items with fewer than n left

81 characters, built in

2. Embed bytes

Embed gives a file’s bytes, as they are, in a new UInt8[] each time it’s called, for a file that isn’t text, like an image.

FB

Import std.core

Local bytes = Embed("logo.txt")
Print("{bytes.Count} bytes: {bytes[0]}, {bytes[1]}")

3 bytes: 70, 66

3. Embed a folder

EmbedFolder gives a Map<String, UInt8[]> of a folder’s files, by their paths in it, like "en/greeting.txt", without hidden files. It’s for a set of files the program looks up by name.

Hello

Bonjour

Import std.core
Import std.collections
Import std.text

Local strings = EmbedFolder("strings")
For path In strings.Keys()
    Print("{path}: {(String.FromUtf8(strings[path]) ?? "").Trim()}")
End For

en.txt: Hello
fr.txt: Bonjour

4. Read them as files

std.io’s Vfs reads embedded files through the same calls as files on disk, so a program can read its defaults from inside itself, and let a folder beside it override them. MountEmbedded mounts what EmbedFolder gives; MountFolder mounts a folder on disk. The std.io.vfs reference has each call.

Rules

• The path is a String known at compile time, inside the package’s folder, with / between folders.
• A missing file, a folder given to Embed or EmbedText, a file given to EmbedFolder, or text that isn’t UTF-8 is an error at the call.
• One call can put at most 64 MiB in the program. A file that large is better read when the program runs.
• Each build reads the files again, so the program always has their latest contents.