advanced-brainfuck

A high-performance Brainfuck language interpreter for Python with JIT acceleration, library imports, and an interactive REPL.

Documentation | PyPI | Changelog

Features

• JIT-accelerated execution — Compiles Brainfuck programs to an intermediate representation (IR) with run-length encoding, then executes via Numba's @jit(nopython=True) for 3-5x speedup
• Segmented JIT with checkpoints — All programs use the JIT path; I/O operations (,, *, &) trigger checkpoints where Python handles input/output before resuming JIT execution
• Interpreted fallback — If JIT compilation fails, falls back to interpreted IR execution with full compatibility
• Library system — Import external .bf files with {libname} syntax; recursive imports supported
• Interactive REPL — Run brainfuck with no arguments for an interactive shell
• Python API — from brainfuck import BrainFuck for programmatic use

Quick Start

Installation

pip install advanced-brainfuck

Command Line

# Run a program and exit
brainfuck --command-line '++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++.'

# Run a program from file (recommended for large programs)
brainfuck --command-line -f program.b

# Run a program then enter interactive REPL
brainfuck '+++++++++++++++++++++++++++++++++++++++++++++++++++.'

# Redirect output to a file
brainfuck --command-line --output result.txt '+++++++++[>++++++++<-]>+.'

# Save tape state after execution
brainfuck --command-line --dump tape.json '+++'

# Load tape state, run program, and dump result
brainfuck --command-line --load tape.json --output result.txt --dump out.json '.>+++.'

# Enter interactive REPL
brainfuck

Python API

from brainfuck import BrainFuck

bf = BrainFuck()
bf.execute('+++++++++++++++++++++++++++++++++++++++++++++++++++.')  # prints: 3
bf.execute('[-]')                    # clears cell 0
bf.execute('{p10}*{tochar}')         # imports and prints: |10|
bf.execute('&')                       # prints command history
bf.save_tape('tape.json')            # save tape state to file
bf.load_tape('tape.json')            # restore tape state from file
bf.interpreter()                      # starts interactive REPL

Brainfuck Commands

Standard Commands

Additional Commands

Library Modules

The bflib/ directory contains 31 reusable Brainfuck modules:

Architecture

Source Code → Import Resolution → IR Compilation → Execution
                                                        ↓
                                               ┌── Segmented JIT ──┐
                                               │ execute_jit()      │
                                               │ via Numba          │
                                               │                    │
                                               │ Checkpoints at:    │
                                               │  , * &             │
                                               │                    │
                                               │ Python handles I/O │
                                               │ then resumes JIT   │
                                               └────────────────────┘
                                               ┌── Fallback ────────┐
                                               │ (JIT compilation   │
                                               │  failure only)     │
                                               │ Python IR loop     │
                                               └────────────────────┘

IR Compilation

Source code is compiled to an intermediate representation with:

• Run-length encoding — +++++ becomes ('add', 5) in a single operation
• Pre-resolved jumps — [ and ] targets are computed at compile time
• Numeric encoding — IR tuples converted to NumPy int32 arrays for JIT

Tape Memory

Cells use a pre-allocated NumPy tape of 65,536 cells (64K) for JIT execution, with a hybrid Python storage model for the REPL:

• Pre-allocated list of 30,000 integers for indices 0-29,999 (O(1) access)
• Sparse defaultdict for negative indices (rarely used but supported)

Requirements

• Python >= 3.13
• Numba >= 0.58.0
• NumPy >= 1.24.0

Project Structure

advanced-brainfuck/
├── brainfuck/               # Python package
│   ├── __init__.py          # Public API re-exports
│   ├── __main__.py          # python -m brainfuck entry point
│   ├── core.py              # Core interpreter, compiler, JIT, CLI
│   └── bflib/               # Reusable Brainfuck library modules
│       ├── sum.bf
│       ├── copy.bf
│       ├── mul.bf
│       ├── div.bf
│       ├── toint.bf
│       └── ...              # 31 modules total
├── docs/
│   ├── spec/              # Product & technical specifications
│   ├── adr/               # Architecture decision records
│   └── features/           # Feature specifications
├── tests/
│   └── features/           # Test files
├── pyproject.toml          # Package configuration
└── README.md

License

GPLv3 — See LICENSE for details.