Esolang Interpreters

Interpreters and boolean-circuit generators for 65 esoteric languages. 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. roadmap tracks live work and limitations records contracts.

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

Command line

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

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
just test

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 65 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. 65 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.