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.

The Cantor interpreter ships with two complementary layers of tests: Python unit tests that verify the mathematical correctness of the pairing functions in isolation, and end-to-end program tests that run real .cantor files through the CLI and compare their output against expected results. Both layers are wired into make targets so they can be run individually or together.

​
Python unit tests

The file tests/python/test_cantor_stdlib.py contains unit tests for every function exported by src/cantor_stdlib.py. These tests exercise the pairing math directly in Python, without invoking the ANTLR parser or the interpreter at all. They are the fastest way to confirm that the foundational numeric encoding is sound. The tests cover:
  • pi / unpi round-trip — encodes and decodes pairs, including the reference example pi(47, 32) == 3192.
  • List encoding / decoding — verifies pi_from_list and unpi_list across empty lists, singletons, and multi-element lists.
  • Input encoding — checks encode_input_text("1 3 2") == 188 and edge cases such as empty input and non-natural input raising ValueError.
  • k_1 — asserts the constant-one function returns 1 for any input.
  • identity — confirms identity(v) == v and that the "id" key in BUILTIN_FUNCTIONS maps to the same function.
  • add — verifies add(pi(3, 4)) == 7 and similar pairs.
  • mul — checks multiplication via encoded pairs.
  • diff — checks truncated subtraction max(0, x - y) via encoded pairs.
  • fst / snd — decodes the first and second component of every encoded pair.
Run the unit tests with either command: 
python3 tests/python/test_cantor_stdlib.py

make test-python
A passing run prints a single confirmation line: 
Python helper tests passed.
The test file inserts src/ into sys.path at the top, so it can be executed from any working directory without installing the package first.

​
Cantor program tests

End-to-end tests live under tests/programs/. Each test is a group of three files that share the same stem:
  • .cantor — the Cantor source program to execute.
  • .inp — whitespace-separated natural numbers that are fed to the program via stdin.
  • .out — the single line of expected stdout output.
Any .cantor file that does not have a matching .inp and .out counterpart is treated as an import-only dependency (e.g., relacionals.cantor) and is silently skipped by the test runner. The test runner (scripts/run_tests.py) discovers tests by recursively scanning tests/programs/ for .cantor files, then looks for the matching .inp and .out files beside each one. For every matched triple, it invokes the real CLI: 
python3 cantor.py <file.cantor>
with the contents of .inp piped to stdin, and compares the captured stdout with the contents of .out.

​
Running the program tests

python3 scripts/run_tests.py

make test-programs
make test-programs depends on the all target, so it automatically rebuilds the ANTLR-generated parser files before running the tests. If you run the script directly, make sure make has been run first.

​
Output format

Each test prints one line: OK phase/name (three spaces) if stdout matched the expectation, or FAIL phase/name (one space) followed by the expected and actual values plus any stderr output. 
=== Running Cantor program tests ===
OK   phase1-core/suma
OK   phase2-imports/signe
FAIL phase3-extended/fib
     expected: 8
     actual:   5
     error:

=== Summary: 2 passed, 1 failed ===
The process exits with code 0 when all tests pass and 1 when any test fails.

​
Test phases

Tests are organized into phase directories that correspond to language feature groups:
PhaseDirectoryWhat is tested
1phase1-coreBuilt-ins, comp, pair
2phase2-importsimport directive
3phase3-extendedcompair, extended mode
4phase4-minimizationmu operator
5phase5-conditionalsConditional functions
5phase5-primrecPrimitive recursion

​
Make targets

TargetWhat it does
make testRuns both test-python and test-programs
make test-pythonRuns only the Python unit tests
make test-programsBuilds the parser first, then runs the Cantor program tests

​
Adding a new test

1

Create the .cantor source file

Write your Cantor program and save it under the appropriate phase directory, for example tests/programs/phase1-core/my_test.cantor. Make sure the file begins with a main directive that selects the function to evaluate.
main my_function
define my_function [returns input plus one] comp add k_1
2

Create the .inp input file

Create tests/programs/phase1-core/my_test.inp containing the whitespace-separated natural numbers to feed as stdin. For a program expecting a single input, write just one number:
5
For a program expecting a pair, write two numbers on the same line:
3 4
3

Create the .out expected output file

Create tests/programs/phase1-core/my_test.out containing the exact output your program should produce. The test runner strips leading and trailing whitespace before comparing, so a single number on one line is sufficient:
7
4

Run the test runner to verify

Execute the program test suite to confirm your new test is discovered and passes:
python3 scripts/run_tests.py
You should see a line like OK phase1-core/my_test in the output. If you see FAIL, review the expected vs. actual values printed below the test name.

Build docs developers (and LLMs) love

Get started for freeTalk to us