Getting started

Install

Octant is a Rust crate. Build and install it from a clone of the repository:

git clone git@github.com:Chelis-Lang/octant.git
cd octant
cargo install --path .

The octant binary lands on your $PATH as a standalone executable. Installing requires a working Rust toolchain. The Chelis compiler is needed on your $PATH for the workflows that validate Octant's output, and for compiling the Deep that Octant emits.

A first translation

Octant reads a LaTeX file and writes two outputs: a Deep .dp file and a .spans.json provenance manifest.

Take a simple formula. Write the Pythagorean theorem to pythagoras.tex:

% chelis: a : f32
% chelis: b : f32
% chelis: c : f32
c = \sqrt{a^2 + b^2}

The % chelis: lines are magic comments. They declare the type of every free identifier in the formula. Without them the type-inference pass cannot bind a, b, and c, and translation fails with an unbound identifier error. See The supported LaTeX subset for the magic-comment forms.

Translate it:

octant translate pythagoras.tex --output pythagoras.dp --spans pythagoras.spans.json

Octant writes pythagoras.dp (the Deep program) and pythagoras.spans.json (the provenance manifest). The emitted Deep, with its {span: "..."} metadata elided for readability, has the shape:

(app (var sqrt) (app (var add) (app (var mul) (var a) (var a)) (app (var mul) (var b) (var b))))

The square root maps to the sqrt builtin. Squaring lowers to repeated multiplication: a^2 becomes (mul a a). There is no pow in the output. See the pow lowering table for why.

Check without writing output

To validate that a formula parses and type-infers cleanly without producing any files, use check:

octant check pythagoras.tex

check exits 0 on success and a nonzero code on failure. It is the form to run in continuous integration. The exit codes are listed in The CLI.

Default output paths

If you omit --output and --spans, Octant derives the paths from the input by replacing the .tex extension:

octant translate pythagoras.tex
# writes pythagoras.dp and pythagoras.spans.json next to the input

Reading from stdin

Pass - as the input to read LaTeX from standard input. Pair it with --inline to write the Deep to stdout and the spans manifest to stderr, which keeps the translation out of the filesystem entirely:

echo 'c = \sqrt{a^2 + b^2}' | octant translate - --inline

In --inline mode the Deep goes to stdout, so it pipes cleanly into a downstream Chelis command.

Tracing a node back to its source

Every Deep node has a stable identifier recorded in the spans manifest. Given an identifier, explain prints the LaTeX it came from:

octant explain pythagoras.tex --target n_002

The output reports the byte range, the line and column, the literal source slice, and a few lines of surrounding context. See Provenance and span tracking for how the identifiers are assigned and how they survive compilation.