Skip to main content

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:

export.stofPlayground ↗
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());
}
Output

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:

parse.stofPlayground ↗
#[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());
}
Output

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.x puts it in a field. as X, without self, creates a root named X.

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:

FormatFieldExample
texttextimport text './notes.txt' as self.notes gives self.notes.text
mdmdimport './README.md' gives self.md
bytesbytesraw bytes, as a blob
pdfpdfa Data<Pdf> value, see the PDF library
image formatsimagea 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:

pkg.stof
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.