Skip to main content

Formats

A format is how Stof reads and writes one kind of data. Formats are named by a string, and the same names work everywhere: parse(src, obj, 'yaml'), stringify('yaml', obj), import yaml './file', and from your app, doc.parse(src, 'yaml'). formats() lists the ones a document has, and format('name') checks for one.

Data: json, yaml, toml​

Fields in, fields out. Functions, types, and attributes aren't part of these formats, so they're left out of exports:

data-formats.stofPlayground ↗
#[main]
fn main() {
  const plan = new { name: 'pro', seats: 5, annual: true };
  pln(stringify('json', plan));
  pln(stringify('toml', plan));

  const loaded = new {};
  parse('name: team\nseats: 10\n', loaded, 'yaml');
  pln(loaded.seats);
}
Output

yml is another name for yaml.

Stof: stof and bstf​

These are the formats that keep everything: functions, types, attributes, and data. stof is the text you write. bstf is binary Stof: compact, fast to load, and the way to store or send part of a document with its logic:

bstf.stofPlayground ↗
pricing: {
  rate: 2
  fn total(units: int) -> float { units * self.rate }
}

#[main]
fn main() {
  const bytes = blobify('bstf', self.pricing);

  const copy = new {};
  parse(bytes, copy, 'bstf');
  pln(copy.total(21));
}
Output

A stof export is readable Stof: objects with their types and attributes, and values as literals (1GB, set(..), map((k, v))). Parse it back with the stof format. Functions are written as their source when the host keeps it (doc.keepSource() before parsing; off by default, since it costs memory), and as data@v1 blocks otherwise, so they still load and run. This playground keeps source. Comments, formatting, and object IDs aren't kept; stof:graph is the exact form, with IDs and compiled functions, for copying a document exactly:

stof-export.stofPlayground ↗
pricing: {
  rate: 2
  limit: 1GB
  tiers: [new { up_to: 100, price: 0.5 }]
  fn total(units: int) -> float { units * self.rate }
}

#[main]
fn main() {
  pln(stringify('stof', self.pricing));
}
Output

Text: text, md, bytes​

These take content as a single value instead of reading structure from it: text (also txt) as a string in a field named text, md (also markdown) as a string in a field named md, and bytes as a blob in a field named bytes:

text.stofPlayground ↗
#[main]
fn main() {
  const note = new {};
  parse('remember to renew', note, 'text');
  pln(note.text);
}
Output

Web: urlencoded​

Form data and query strings (also www-form). Nested objects use brackets, the way browsers send forms:

urlencoded.stofPlayground ↗
#[main]
fn main() {
  pln(stringify('urlencoded', new { q: 'stof', page: 2 }));
}
Output

Markup: html and xml​

These write objects as elements, which is how a document becomes a page, a component tree, or an XML file. An object is an element, and its fields, in order, are what's inside it. Three attributes say how:

  • #[tag('name')] names the element. Put it on the field, the object, or a type, and every instance of the type gets it. Without one, an element is named after its field.
  • #[attr] makes a field an attribute of the element (#[attr('data-id')] gives it a different name).
  • #[text] writes a value as text inside the element.

Child objects become child elements, lists become one element per item, and any other value becomes <name>value</name>. #[no-export] fields, null values, and functions without #[attr] or #[text] are left out.

html.stofPlayground ↗
#[type]
#[tag('ui-metric')]
Metric: {
  #[attr] str label: ''
  #[attr] float | fn value: 0
  #[attr('data-size')]
  fn size() -> str { self.label.len() > 10 ? 'wide' : 'narrow' }
}

#[tag('section')]
dashboard: {
  #[tag('h2')] title: 'Revenue'
  Metric mrr: { label: 'MRR', value: (): float => 1000 + 250 }
  #[text] fn footer() -> str { 'Updated today' }
  #[no-export] cache: {}
}

#[main]
fn main() {
  pln(stringify('html', self.dashboard));
}
Output

Computed Values​

A function marked #[attr] or #[text], and a field that holds a function, is called when the object is exported, and its result is written. That includes functions from the object's type, and async functions, which are awaited. A #[text] function can return objects (or a list of them), which are written as elements, so part of the tree can be built by code:

computed.stofPlayground ↗
#[type]
#[tag('li')]
Item: {
  #[text] str name: ''
}

#[tag('ul')]
list: {
  names: ['north', 'south', 'west']

  #[text]
  fn items() -> list {
      const out = [];
      for (const name in self.names) out.push_back(new Item { name } on self.made);
      out
  }
  #[no-export] made: {}
}

#[main]
fn main() {
  pln(stringify('html', self.list));
}
Output

Safe HTML​

The html format is safe to put on a page, whatever the document holds, including a view a model wrote:

  • Text and attribute values are always escaped.
  • script, style, iframe, object, embed, link, meta, template, and the like are never written, along with what's inside them.
  • on* attributes are dropped, and URLs (href, src, ...) must be relative or http, https, mailto, or tel (or a data: image).
  • style, action, and formaction are written only when your app allows them (doc.allowHtmlAttributes(['style'])), since CSS can cover the page and a form can post somewhere else.
  • Only the standard HTML elements and custom elements (with a - in the name) are written. Your app can allow exactly the elements it renders instead, and a document can't change that list (see Using Stof).
safe-html.stofPlayground ↗
#[tag('div')]
view: {
  #[tag('p')] note: '<b>bold?</b>'
  #[tag('script')] code: 'alert(1)'

  #[tag('a')]
  link: {
      #[attr] href: 'javascript:alert(1)'
      #[attr] onclick: 'alert(1)'
      #[text] label: 'Click'
  }
}

#[main]
fn main() {
  pln(stringify('html', self.view));
}
Output

An object without a tag is exported as a fragment: its content, with no element around it.

XML​

xml works the same way, as data: it starts with an XML declaration, writes empty elements as <name/>, and fails on names that aren't valid XML. Parsing XML reverses the export, so a document comes back the way it was written. Attributes become #[attr] string fields, an element with only text becomes a string field, repeated elements become a list, and other text goes in a #[text] field named text:

xml.stofPlayground ↗
#[main]
fn main() {
  const order = new {};
  parse('<order id="o-1"><item sku="a">Tea</item><item sku="b">Cups</item><total>18.50</total></order>', order, 'xml');

  pln(order.id);
  pln(order.item[1].text);
  pln(order.total);

  order.total = '20.00';
  pln(stringify('xml', order));
}
Output

XML has no types, so values parse as strings ('18.50'): cast them where you need numbers (order.total as float).

Files: pdf, images, docx​

These read richer files into a document: pdf, image formats (png, jpeg/jpg, gif, webp, bmp, tiff, ico), and docx. A PDF becomes a Data<Pdf> value in a field named pdf, and an image a Data<Image> in a field named image, which the PDF and Image libraries work with.

They're available in Python, the CLI, and Rust with the matching features, but not in the JavaScript package.

Packages: pkg​

Imports a directory with a pkg.stof file, or a .pkg file made by stof pkg. See Packages. It reads files, so it needs file access, and it isn't in the JavaScript package.

Which Formats Are Where​

FormatsJavaScriptPython, CLIRust
json, yaml, toml, stof, bstf, text, md, bytes, urlencoded, htmlYesYesYes
xmlYesYesExport; parsing with the xml feature
pkgNoYesYes (default features)
pdf, images, docxNoYesWith the pdf, image, and docx features

Rust apps can add formats of their own: anything that implements Stof's Format trait can be parsed into and exported from a document like the built-in ones. Next, Async.