Skip to main content

Tools

The stof Command​

The CLI runs and tests .stof files on your machine. Install it with Cargo:

cargo install stof-cli

Since it runs your own files, documents run by the CLI can use the file system, environment variables, imports from disk, and the network. That's different from an app embedding Stof, where all of those are off unless the app allows them.

Running​

stof run parses a file (or a package directory) and calls its #[main] functions:

stof run pricing.stof            # every #[main] function
stof run pricing.stof -a nightly # every #[nightly] function instead

When something fails, you get the message, the line, and the Stof call stack:

error: cannot multiply null: the right value is null or missing (use ?? to give a default)
  --> pricing.stof:4:5
   |
 4 |     units * self.rat
   |     ^
  at root.total (pricing.stof:4:5)
  at root.main (pricing.stof:9:5)

Testing​

stof test runs every #[test] function and exits with an error code if any fail, so it works in CI:

pricing.stof
rate: 2

fn total(units: int) -> float {
    units * self.rate
}

#[test]
fn totals() {
    assert_eq(self.total(3), 6);
}

#[test(10)]        // passes if the function returns 10
fn five_units() -> float { self.total(5) }
$ stof test pricing.stof
running 2 tests ...
test root totals ... ok
test root five_units ... ok

test result: ok. 2 passed; 0 failed; finished in 0s

stof test --leaks also fails any test that leaves objects in the document it didn't clean up, and says where they are. See Testing for writing tests and Memory Management for cleaning up.

Packages and Docs​

A directory with a pkg.stof file is a package: stof run and stof test take the directory, and the package's files are parsed together. stof pkg <dir> bundles one into a single .pkg file, and stof unpkg unpacks it. stof docs <path> <out> writes Markdown docs for a document from its doc comments (/// and /** */), along with references for the libraries.

VS Code​

The Stof extension highlights .stof files. With the CLI installed, it also starts the Stof language server (stof lsp) and gives you:

  • Errors and warnings as you type, including problems in imported files.
  • Go to definition for fields, functions, types, and imports.
  • Hover for signatures, field types and values, doc comments, and every library function.
  • Completion for fields, functions, variables, types, and libraries.
  • Find references and rename across a package.
  • An outline of objects, types, fields, and functions.

If stof isn't on your PATH, set stof.server.path in the extension's settings to the CLI's full path. The language server reads a file in the context of its package when there's a pkg.stof, so types from other files resolve. It never runs your code beyond computing field values, and stops those after 2 seconds.

Other editors can use the same server: run stof lsp as a language server over stdio.

Teaching AI Models Stof​

Models already read and write Stof well, since it looks like JSON and JavaScript. To make them reliable, give your agent or coding assistant the Stof skill. It's a short guide to the language and the mistakes models (and people) tend to make, with each library's reference in stof.zip.

When a model's document fails, Stof's error messages say what went wrong and where, in plain language. Pass them back to the model and it can fix its own mistakes.

Last updated on