Getting started

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

RiX runs on Node.js 22+ or Bun 1.4+. Bun is preferred for source development. The package is an active alpha and is not yet presented as a stable registry release: the public npm name rix belongs to an unrelated project. Use the matching RiX and Core checkouts in the RatMath workspace.

Requirements

  • Bun 1.4 or newer for source development; installed packages also run on Node.js 22+
  • 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 run prep
cd rix
bun run build:package
bun run test:short

The workspace preparation command initializes pinned repositories and installs their dependencies. The manifest requires Core ^0.6.0 for NumeralSystem. Standalone registry installation requires that Core version to be published first; workspace development uses the matching local Core implementation. From rix/, use bun run test:suite for the complete verification (longer than the short development checks).

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

Install the package

npm install --global @ratmath/rix installs the rix command for Node.js 22+. For Bun, use bunx --bun --package @ratmath/rix rix. In an application, install with npm install @ratmath/rix or bun add @ratmath/rix, import parseAndEvaluate from @ratmath/rix, and run your module with Node or Bun. The README includes complete standalone and persistent-session examples.

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.

Plugin defaults and persistent REPL setup

A fresh interactive REPL loads the curated full plugin set. File execution and embedded evaluator calls remain bare unless plugins are requested. --plugins=plot,svg replaces the built-in or saved selection, while repeatable --plugin=ID flags add to it. --plugins=none suppresses implicit and saved preloads; it does not forbid explicit loads or dependencies requested by a script or preamble. Use --no-config --plugins=none for a clean bare REPL. Saved empty plugin lists remain bare; an absent setting defaults to full.

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 Terminal ASCII, SVG, Canvas-plan, TikZ, PNG, Markdown, HTML, Quarto, LaTeX, PDF, GIF, glTF, and CSV. .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. Specialist plugins outside full remain available by ID; for example, --plugin=oracle loads the implemented exact Oracle plugin.

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 to ignore saved settings (restoring the full default), --no-preamble to retain configured plugins without running the preamble, or --preamble=FILE for an explicit project preamble. --plugins replaces the preload selection for one session; --plugin and --operator-file add to the selected setup. 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 "@ratmath/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 @ratmath/rix/parser, @ratmath/rix/eval, and @ratmath/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