Import & Export
A document takes in data and logic in any format it knows, and exports to any of them. This page covers doing that from inside a document. For your app's side, see Using Stof in Your App.
Exporting
stringify(format, object) exports an object as text, and blobify(format, object) as bytes:
plan: {
name: 'pro'
price: 20
#[no-export] internal_id: 'p_7'
fn monthly() -> float { self.price }
}
#[main]
fn main() {
pln(stringify('json', self.plan));
pln(stringify('yaml', self.plan));
pln(blobify('bstf', self.plan).len());
}Data formats like JSON and YAML get the fields, without functions. A field marked #[no-export] is left out too. Binary Stof (bstf) keeps everything, functions included: it's how you store or send a piece of a document and run it somewhere else.
Parsing at Runtime
parse(source, object, format) reads data or Stof into the document while it runs:
#[main]
fn main() {
const settings = new {};
parse('{"theme": "dark", "size": 12}', settings, 'json');
pln(settings.theme);
parse('fn greet() -> str { "parsed at runtime" }', self);
pln(self.greet());
}parse only adds to the document. It can't reach files or the network, so parsing Stof from somewhere you don't trust is as safe as running the rest of the document. The format defaults to stof, and the object defaults to self.
The import Statement
import reads a file when the document is parsed:
import './rates.json' as self.rates; // JSON, into a field of this object
import './geo.stof' as Geo; // Stof, as a new root named Geo
import yaml './config.txt'; // an explicit format, into this object
- Paths are relative to the file doing the importing, so a package's files can import each other wherever it's run from.
- The file extension picks the format (
.json,.yaml,.toml,.md,.stof, ...). Name a format before the path to choose it yourself. An unknown extension imports as text, and an unknown format name is an error. - Without
as, the file goes into the current object.as self.xputs it in a field.as X, withoutself, creates a root namedX.
Imports read files, so they need file access: they work in the CLI, and in an app only when it allows files with allow_system(). To bring in data from your app, use parse (or doc.parse from the app) instead.
Where Imports Land
Formats that hold structured data (JSON, YAML, TOML, Stof) add their fields. Formats that hold a single value put it in a field named after the format:
| Format | Field | Example |
|---|---|---|
text | text | import text './notes.txt' as self.notes gives self.notes.text |
md | md | import './README.md' gives self.md |
bytes | bytes | raw bytes, as a blob |
pdf | pdf | a Data<Pdf> value, see the PDF library |
| image formats | image | a Data<Image> value, see the Image library |
Formats lists every format.
Packages
A directory with a pkg.stof file is a package. Its import field lists the files it's made of:
name: 'pricing'
version: '0.1.0'
import: 'src/mod.stof'
import pkg './pricing' imports a whole package. A path starting with @ refers to stof/ under the working directory, so import '@pricing/plans' is stof/pricing/plans.stof. The CLI's stof pkg bundles a package into a single file. See Tools.
Next, Formats.