Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/felipenugo/cantor-interpreter/llms.txt

Use this file to discover all available pages before exploring further.

This guide assumes you have already cloned the repository, installed the Python dependencies, and generated the ANTLR4 parser files. If you haven’t done that yet, complete the Installation steps first, then come back here.
All commands below are run from the root of the cantor-interpreter repository.

​
Run your first program

The simplest possible Cantor program is suma.cantor. Its entire source is: 
# suma.cantor
main add
The main keyword declares which function the program exposes. Here it is the built-in add, which receives a Cantor-encoded pair <x, y> and returns x + y. Run it by piping two numbers into the interpreter: 
echo "3 2" | python3 cantor.py tests/programs/phase1-core/suma.cantor
Expected output: 
5

​
What just happened?

  1. You provided two numbers, 3 and 2, on standard input.
  2. The interpreter read them and encoded the pair using the Cantor pairing function: <3, 2> becomes a single natural number.
  3. The main function (add) received that encoded number, decoded the pair, and returned 3 + 2 = 5.
  4. The result was printed to standard output.
This encoding step is automatic — you always write plain space-separated numbers on stdin, and the interpreter handles the pairing.

​
A program with definitions

anterior.cantor defines a predecessor function (called anterior — Catalan for “previous”). Because the language has no subtraction that can go negative, it implements max(0, x − 1) using the built-in diff combinator: 
# anterior.cantor
main anterior

define aparella_amb_1
    [Aparella l'entrada x amb 1: <x.1> ]
    pair id k_1

define anterior
    [Anterior amb limit 0]
    comp diff aparella_amb_1
Reading this from the bottom up:
  • aparella_amb_1 uses pair id k_1 to turn input x into the Cantor pair <x, 1>.
  • anterior applies comp diff aparella_amb_1, meaning it first runs aparella_amb_1 on the input to get <x, 1>, then feeds that to diff, which computes max(0, x − 1).
Run it: 
echo "5" | python3 cantor.py tests/programs/phase1-core/anterior.cantor
Expected output: 
4

​
Program structure reference

Every .cantor file follows this layout (only main is required): 
main <function>

import <module-name>      # optional: load definitions from another .cantor file

extended                  # optional: enable compair and primrec combinators

define <name>
    [doc comment]
    <function-body>
  • main <function> — declares the entry-point function. Must appear exactly once.
  • import <module-name> — imports definitions from a file named <module-name>.cantor in the same directory as the current program.
  • extended — unlocks the compair and primrec combinators.
  • define <name> [doc] <body> — gives a name to a function expression. The documentation string in […] is required by the grammar and ignored at runtime — it exists to annotate what the function does.

​
CLI usage

The interpreter always reads from standard input and writes the result to standard output: 
python3 cantor.py <file.cantor>
To supply input from a file instead of typing it inline, redirect it: 
python3 cantor.py <file.cantor> < input.inp
If you call the interpreter with the wrong number of arguments it prints usage help to stderr: 
Usage: python3 cantor.py <file.cantor>

​
Write and run your own program

1

Create a new file

Open a new file called double.cantor in the project root:
touch double.cantor
2

Write the program

Add the following content. This defines a double function that computes x + x by pairing x with itself and passing the result to add. Because each combinator body only accepts plain function names, the intermediate pair id id step must be given its own name first:
main double

define pair_x_x
    [<x.x>]
    pair id id

define double
    [Returns x + x]
    comp add pair_x_x
  • pair_x_x uses pair id id to turn input x into the Cantor pair <x, x>.
  • double applies comp add pair_x_x, meaning it first runs pair_x_x on the input to get <x, x>, then feeds that to add, yielding x + x.
3

Run it

echo "7" | python3 cantor.py double.cantor
Expected output:
14
The tests/programs/ directory contains ready-to-run examples covering booleans, division, modulo, even-number testing, factorial, Fibonacci, max/min, and conditional logic — organised into phases (phase1-core through phase5-primrec). Each program comes with a matching .inp input file and a .out expected-output file, making them a great resource for understanding what the language can express.

Build docs developers (and LLMs) love

Get started for freeTalk to us