Documents and Fields
A Stof document is made of objects, and objects hold fields: named values. If you know JSON, you already know most of it.
JSON Is Stof
Any JSON document is a valid Stof document:
{
"name": "Ada",
"age": 36,
"languages": ["en", "fr"],
"address": { "city": "London" }
}
#[main]
fn main() {
pln(`${self.name} lives in ${self.address.city}`);
}#[main] and the function after it aren't JSON. They're there so the Run button has something to run, and self is the document's top level. Every example in Learn ends this way.
Stof also lets you leave out what JSON requires. The quotes around names, the commas, and the outer braces are all optional, so this is the same document:
name: 'Ada' // single or double quotes
age: 36
languages: ['en', 'fr']
address: {
city: 'London'
}
/* Comments work anywhere. */
#[main]
fn main() {
pln(`${self.name} lives in ${self.address.city}`);
}address is an object: a set of fields with a name. Objects can hold other objects, as deep as you need.
Typed Fields
A field can have a type. Its value is cast to that type, when it's declared and every time it's assigned:
str label: 42 // cast to the string '42'
int count: 3.9 // cast to 3
float price: '19.99' // cast to 19.99
#[main]
fn main() {
self.count = '7';
pln(self.label);
pln(self.count + 1);
pln(self.price);
}Fields without a type take whatever you give them. Add types where they help: they document what a field holds and catch bad values early. Types & Units lists them all, including units like 5km and 30s.
Fields That Can't Change
const makes a field read-only. Assigning to it throws:
const str plan: 'pro'
#[main]
fn main() {
try {
self.plan = 'free';
} catch {
pln('plan is const');
}
pln(self.plan);
}Private Fields
#[private] hides a field from code outside its object. Only functions on the same object can read it:
account: {
#[private]
api_key: 'sk-1234'
fn masked() -> str {
'****' + self.api_key.substring(self.api_key.len() - 4)
}
}
#[main]
fn main() {
pln(self.account.masked()); // the object's own function can read it
pln(self.account.api_key); // from outside: null
}#[readonly] is similar: anyone can read the field, but assigning to it throws. To keep a field out of exports like JSON, mark it #[no-export]. The #[...] before a field or function is an attribute, covered in Attributes.
Null and Not Null
Any field can be null, including a typed one. Add ! to the type to make a field reject null:
str! name: 'Ada'
str nickname: null
#[main]
fn main() {
pln(self.name);
pln(self.nickname);
try {
self.name = null;
} catch {
pln('name cannot be null');
}
}Reading a field that doesn't exist isn't an error. It's null: self.missing is null. Null & Initialization covers working with null.
More Than One Type
A field can accept a union of types, or hold a tuple:
int | str id: 42
(str, ver) release: ('beta', 0.5.24)
#[main]
fn main() {
self.id = 'user-42';
pln(self.id);
pln(self.release);
}A value that matches one of the union's types is kept as it is. Anything else is cast to the first type in the union that it can be.
Creating Fields
Assigning to a field that doesn't exist creates it, along with any objects on the way:
#[main]
fn main() {
self.status = 'active';
self.limits.daily.calls = 100; // creates limits and daily too
pln(self.status);
pln(self.limits.daily.calls);
}This is how a document grows while it runs. Next, Types & Units.