Esolang Interpreters

Interpreters and Boolean generators for 64 esoteric languages: 62 text and 2 raster.

generate takes a truth table and returns a program computing it; verify runs that program on every row and checks what it answers.

usage is the caller's guide -- the exported functions, the four odd input shapes, templates, reading an answer back, the debugger. architecture shows how the registry, generators, interpreters, and answer extraction connect. tutorial walks one truth table through text, template, raster, and debugger interfaces; compatibility defines the beta package's stable surface. roadmap tracks live work and limitations records contracts.

Start with the CLI, Python API, or contribution guide.

Command line

python -m pip install esolangs

esolangs --help
esolangs list
esolangs generate Suffolk 0110 > program.txt
printf '0\n1\n' | esolangs run Suffolk program.txt

esolangs generate brainfuck 0110 > bf.txt
printf '0\n1\n' | esolangs debug --steps 20 --watch-cell 0 brainfuck bf.txt

The Polynomial interpreter needs the optional mathematics extra: pip install 'esolangs[math]'. The other languages install without SymPy.

To work on the repository instead, install its development environment and run the quick verification loop:

just install-dev
source .venv/bin/activate        # or prefix each command with `uv run`
just test-quick

Run just test before committing; the contribution guide has the full workflow.

Python API

import esolangs

esolangs.verify("Fargo", "10010110")  # -> True

Pass each command the language it was generated for: running a Suffolk program as brainfuck does not fail, it reports something useless. How a language reads its input bits is not universal either -- let encode_inputs build the stdin.

Examples

esolangs generate Sophie 0110 emits 51 characters computing XOR:

;@$48{;@$48{#$48,&}{#$49,&}}{;@$48{#$49,&}{#$48,&}}

Feeding it the two input bits, one per line, prints their XOR. tests/test_readme_example.py runs all four rows, so the block cannot drift.

Stepping a program

--tui steps it on screen instead. This is a real frame -- Flowchart at step 14, redrawn by tui.render every time this file is generated:

Flowchart  step 14  ip (9, 7, 1, 0)  running
--------------------------------------------------------------------------
 5 |     ┌───< >───┐
 6 |     │         │
 7 |    / /       / /
 8 |     │         │
 9 |   ┌< >─┐    ┌< >─┐
10 |   │    │    │    │
11 |  { ]  [ }  [ }  { ]
12 |   │    │    │    │
13 |  \ \  \ \  \ \  \ \
14 |   │    │    │    │
15 | (( ))(( ))(( ))(( ))
--------------------------------------------------------------------------
memory   (empty)
stack    (empty)
output   ''
views    deques={}  pointers=[_Pointer(row=9, col=7, d=(1, 0), reg=1, dequ
hjkl move | t break | space step | c continue | r run | b back | q quit

The live screen reverse-videos the cell at that ip; colour does not survive the page. usage names every key.

Ready-to-run programs are committed under examples/: examples/ holds a truth-table program for each of the 62 languages with a boolean generator. It regenerates via scripts/generate.py examples.

Implemented languages

Line is an image-language module under esolangs.line; run just test-line for its suite.

Generators

Boolean generators accept a most-significant-input-first binary truth table.

The truth table is a binary string of length 2**n, most-significant input first; its length implies n, so it isn't passed separately. 62 of the languages have such a generator, some covering only a documented subset of tables.

esolangs list --details marks which languages have one (gen), which return a template (tmpl), and which have a committed example (ex); add --json for structured output:

esolangs list --details --json | jq '.[] | select(.name == "Sophie")'

{
  "name": "Sophie",
  "boolean_generator": true,
  "parameterized": false,
  "has_example": true
}

Regenerate the committed examples with python scripts/generate.py examples.

Contributing

Read the contribution guide, then run just test. The project is GPL v3; see LICENSE.