Install
Stof is a library you add to your app: an npm package, a Python package, or a Rust crate. There's also a command-line tool for running and testing .stof files. You don't need to install anything to learn the language: every example in these docs has a Run button, and the playground runs in your browser.
Each tab below runs the same document:
name: 'Stof'
fn greet() -> str {
`Hello, ${self.name}!`
}
#[main]
fn main() {
pln(self.greet());
}
- JavaScript / TypeScript
- Python
- Rust
- Command line
npm i @formata/stof
import { StofDoc } from '@formata/stof';
const doc = await StofDoc.new(`
name: 'Stof'
fn greet() -> str { \`Hello, \${self.name}!\` }
#[main]
fn main() { pln(self.greet()); }
`);
await doc.run(); // Hello, Stof!
console.log(await doc.call('greet')); // Hello, Stof!
In JavaScript, pln writes to console.log and err to console.error. To send a document's output somewhere else, replace them with your own functions: doc.lib('Std', 'pln', (...args) => ...). Usually you'll call functions and use what they return instead.
Browsers and Bundlers
StofDoc.new loads Stof's WebAssembly automatically in Node.js and in browsers without a bundler. A bundler like Vite or webpack changes how files are loaded, so give it the file yourself, once, before creating documents:
import { initStof } from '@formata/stof';
import stofWasm from '@formata/stof/wasm?url';
await initStof(stofWasm);
import { initStof } from '@formata/stof';
import stofWasm from '@formata/stof/wasm';
await initStof(await stofWasm());
Webpack doesn't load .wasm files on its own. If that import fails to parse, add a rule that treats them as files:
module: {
rules: [{ test: /\.wasm$/, type: 'asset/resource' }]
}
pip install stof
from pystof import Doc
doc = Doc()
doc.parse("""
name: 'Stof'
fn greet() -> str { `Hello, ${self.name}!` }
#[main]
fn main() { pln(self.greet()); }
""")
doc.run() # Hello, Stof!
print(doc.call('greet')) # Hello, Stof!
The package is named stof on PyPI and imported as pystof. It needs Python 3.8 or newer. pip installs a prebuilt
wheel on Linux (x86_64 and ARM), macOS (Intel and Apple silicon), and Windows, so there's nothing to compile.
cargo add stof
use stof::model::Graph;
use stof::runtime::Runtime;
fn main() {
let mut graph = Graph::default();
graph.parse_stof_src(r#"
name: 'Stof'
fn greet() -> str { `Hello, ${self.name}!` }
#[main]
fn main() { pln(self.greet()); }
"#, None, Default::default()).unwrap();
graph.run(None, true).unwrap(); // Hello, Stof!
let greeting = Runtime::call(&mut graph, "greet", vec![]).unwrap();
println!("{greeting:?}");
}
The default features cover the language, the standard libraries, and file access (which documents only get if you allow it). Add features for more: http (network requests), image, pdf, docx, and age_encrypt, or full for all of them.
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dev-formata-io/stof-cli/releases/latest/download/stof-cli-installer.sh | sh
powershell -ExecutionPolicy Bypass -c "irm https://github.com/dev-formata-io/stof-cli/releases/latest/download/stof-cli-installer.ps1 | iex"
These install the prebuilt stof command for macOS (Apple silicon and Intel), Linux (x86_64 and ARM), or Windows; no Rust needed. With Rust, cargo binstall stof-cli downloads the same binary and cargo install stof-cli builds it from source. stof-cli on GitHub has the binaries.
stof run hello.stof # Hello, Stof!
The CLI is for running and testing your own .stof files, so documents it runs can use files, environment variables, and the network. See Tools for its other commands.
Editor Support
The Stof extension for VS Code highlights .stof files, and with the CLI installed it also shows errors as you type, goes to definitions, completes names, and renames across files. See Tools.
Teaching an AI Model Stof
Models can read and write Stof already, since it looks like JSON and JavaScript. To make them reliable, give your agent the Stof skill: a short guide to the language and the mistakes to avoid, with the library references in stof.zip.