Skip to main content

The Document Graph

So far, objects have been nested inside each other like JSON. Underneath, a document is a graph: a set of objects, each with data attached to it. Fields and functions are both data, and so are richer values like images and PDFs. Knowing this shape explains how paths work, why functions behave like fields, and why moving part of a document is cheap.

Objects and Their Data​

An object is a node in the graph. It doesn't contain its fields and functions the way a JSON object contains values: it points to them. Internally, a document is one list of objects and one list of data, connected by IDs, a bit like an entity-component system. Nested objects are children in that graph:

objects.stofPlayground ↗
server: {
  port: 8080
  host: 'localhost'

  fn url() -> str {
      `http://${self.host}:${self.port}`
  }
}

#[main]
fn main() {
  pln(self.server.url());
  pln(self.server.path());
}
Output

server is an object with an identity and a path of its own (root.server), and inside url(), self is server.

self, super, and root​

Paths inside a function start from one of three places:

  • self: the object the function is on.
  • super: that object's parent.
  • root: the top of the tree the object is in.
navigate.stofPlayground ↗
name: 'Acme'

team: {
  name: 'Billing'
  lead: { name: 'Ada' }

  fn describe() -> str {
      `${self.lead.name} leads ${self.name} at ${super.name}`
  }
}

#[main]
fn main() {
  pln(self.team.describe());
}
Output

Every Path Has a Starting Point​

A path always starts at self, super, root, a variable, or a named root. A bare name like team.name inside a function means "the root named team", not "the field named team":

paths.stofPlayground ↗
team: { name: 'Billing' }

#[main]
fn main() {
  pln(self.team.name);    // the field: Billing
  pln(team.name);         // a root named team: there isn't one, so null
}
Output

This is the most common mistake when starting out, so Stof warns about it when the document is parsed:

warning: unknown name 'team' in fn root.main (main.stof:5:9): not a parameter, variable, or root,
so it is always null (use self.team for a field)

If something is unexpectedly null, check for a missing self..

Named Roots​

A document can have more than one root. root Name { ... } declares one, and its name works as the start of a path from anywhere in the document:

roots.stofPlayground ↗
root Settings {
  currency: 'EUR'
}

invoice: {
  total: 120
  fn label() -> str {
      `${self.total} ${Settings.currency}`
  }
}

#[main]
fn main() {
  pln(self.invoice.label());
}
Output

The top level of a file is the main root. Imports can create roots too (import './geo.stof' as Geo;), which is how a package's files refer to each other.

Creating Objects​

Inside a function, new { ... } creates an object. It's added to the document as a child of self, or of another object with on:

new.stofPlayground ↗
orders: {}

#[main]
fn main() {
  const order = new { id: 1, total: 40 } on self.orders;
  pln(order.parent().path());
  pln(self.orders.children().len());
}
Output

Objects stay in the document until something removes them, even when no field points at them. For temporary objects, see Memory Management.

Inspecting the Graph​

A document can look at its own shape while it runs, using the Object Library:

inspect.stofPlayground ↗
team: {
  name: 'Runtime'
  engineer: { name: 'Ada' }
}

#[main]
fn main() {
  pln(self.team.path());
  pln(self.team.is_parent(self.team.engineer));
  pln(self.team.fields().len());
  for (const (name, value) in self.team.engineer.fields()) {
      pln(`${name}: ${value}`);
  }
}
Output

That's how generic code works on any document: a validator that walks every object, an exporter, or a function that lists every tool an agent has.

Moving Objects and Fields​

An object and the field that points to it are separate things in the graph, so each can move on its own. Moving an object changes its parent; moving a field changes where it's found:

move.stofPlayground ↗
active: {
  task: { title: 'Ship the docs' }
}
archive: {}

#[main]
fn main() {
  self.move_field('self.active.task', 'self.archive.task');
  pln(stringify('json'));
}
Output

Nothing underneath is copied, however large it is. Next, Prototypes & Schemas.