Getting started

Install RiX in the RatMath workspace, run the REPL, execute scripts, and embed the evaluator.

RiX currently lives in the RatMath workspace and uses Bun. The package is an active alpha and is not yet presented as a stable registry release; the workspace is the supported way to run it today.

Requirements

  • Bun 1.2 or newer
  • Git
  • Quarto 1.6 or newer only if you want to build this documentation site

Clone and test

git clone https://github.com/jostylr/ratmath.git
cd ratmath
bun install
bun --cwd rix test

The RiX test suite exercises tokenizer, parser, lowering, evaluator, runtime, CLI, examples, exact values, types, methods, tensors, generators, and diagnostics.

Open the REPL

From the RatMath repository root:

bun run rix
rix> 1/3 + 1/6
1/2
rix> Sq(x) -> x^2
<function Sq(x) ...>
rix> Sq(12)
144
rix> 23.456? < 23.4565
?
rix> ? ?: "yes" ?_ "no" ?? "not decided"
"not decided"

The question mark inside a number creates a certified approximation with an exact rational enclosure. A standalone question mark is an undecided decision; it is distinct from null (_) and can be handled by the ?? branch of the three-state conditional.

Executable documentation examples use the same evaluator as the CLI. A trailing ##@ assertion checks a value, and a standalone ## asks the documentation build to render the most recent result:


1 |> half ##@ == 1/2
##
Show setup code

half = x -> x / 2

Output

1/2

Useful REPL commands include .help, .vars, .fns, .ast[expr], .tokens[expr], .load[pkg], .reset, and .exit. End a line with \ for multiline input.

Persistent REPL setup

RiX keeps CLI configuration under $XDG_CONFIG_HOME/rix, falling back to ~/.config/rix. Set RIX_CONFIG_DIR to use another location. Create or update the configuration with:

rix setup --plugins=full
rix setup --plugins=float,renderers

Plugin names and plugin groups are case-insensitive. full selects the standard first-party plugin set; renderers selects the SVG, Canvas-plan, TikZ, PNG, Markdown, HTML, Quarto, LaTeX, PDF, and glTF target plugins. .draw, .plot, .scene3d, and .nd are producers and remain in their own groups. RiX stores the selectors rather than expanding groups permanently, so new standard plugins or group members can join later releases. The proposed oracle package remains specification-only and cannot be selected until it has an executable plugin manifest.

rix setup also creates cli-preamble.rix in the configuration directory. Its leading YAML comment can request more plugins or operator files, and its RiX body runs before each REPL starts:

/**
plugins: [float]
operator-files: [personal.operators.rix]
**/

digits := 50;

Use --no-config for a clean session, --no-preamble to retain configured plugins without running the preamble, or --preamble=FILE for an explicit project preamble. --plugin, --plugins, and --operator-file remain one-session additions. Persistent setup affects the REPL, not script execution.

Run a file

bun run rix ./rix/examples/eval/units-and-exact.rix

Or, from inside rix/:

bun bin/rix.js examples/eval/cayley-polar.rix

Native RiX test files use the .test.rix suffix:

bun bin/rix.js test
bun bin/rix.js test diagnostics

Inspect the intermediate representation

bun run rix-to-ir --pretty ./rix/examples/eval/factorial.rix

The rix-to-ir command exposes the call-shaped IR used by the evaluator. Add --lang to prefix generated system calls with @_.

Embed RiX in JavaScript

import {
  Context,
  createDefaultRegistry,
  createDefaultSystemContext,
  parseAndEvaluate,
} from "rix";

const context = new Context();
const registry = createDefaultRegistry();
const systemContext = createDefaultSystemContext();

const result = parseAndEvaluate("x := 7; x^2 + 1", {
  context,
  registry,
  systemContext,
});

The public package also exports narrower entry points from rix/parser, rix/eval, and rix/runtime. See the developer guide for the pipeline and extension boundaries.

Build this documentation

Install Quarto and run:

cd rix
bun run build:docs

The build refreshes source-derived runtime reference tables, bundles the browser parser demo, validates the documentation inputs, and renders the site into rix/docs/. That output directory is suitable for GitHub Pages with Deploy from a branch, using the main branch and /docs folder.

For local authoring:

bun run preview:docs

Do not hand-edit rix/docs/; edit files in rix/documentation/ and rebuild.

Where next?

Back to top