Geobe

Geobe is an experimental geometric esolang toolkit written in Python. Its current core is a small interpreter for 2D Unicode-symbol programs, plus a triangle alphabet used by spell programs and the interactive geobe --console mode.

This is not yet a broad general-purpose programming language. The runtime MVP focuses on directional flow, one memory cell, input/output nodes, pluggable transforms, array traversal, and the triangle-to-lowercase spelling layer.

Quick Start

Install the CLI:

pipx install geobe

Run a small program that reads one input value and writes it to output:

geobe --code "○→▽" --input hello

Expected output:

{"outputs": ["hello"]}

What Exists Today

Geobe programs are rectangular text grids. The interpreter finds every ○ source node and follows directional flow through the grid until a path ends. The current MVP supports a single deterministic memory cell, input buffering, output collection, and pluggable △ transforms.

Core symbols:

• ○ read the next input value
• □ store the current value in memory
• △ transform the current value
• ▲ change/delta transform the current value
• ▽ append the current value to output
• ◀ append the current value to output
• ▶ traverse the current array by one index
• ▶▶ continue the current array loop, or finish when exhausted
• →, ←, ↑, ↓ move execution through the grid
• «... » read a literal string into the current value
• spell ... decode triangle alphabet symbols into lowercase text output

Spaces are treated as empty cells for traversal. Other non-traversable characters stop a path.

The triangle alphabet is deliberately separate from the execution model. In a .geo file, spell ▹▶▿▿◂ is parser shorthand for a literal string output. In geobe --console, typing lowercase English letters shows their triangle-symbol encoding and Enter decodes the visible line back to English.

Installation

The project targets Python 3.11+.

For normal CLI use, install Geobe with pipx:

pipx install geobe

To install a specific release:

pipx install geobe==0.1.1

If pipx is not installed and you use Homebrew on macOS:

brew install pipx
pipx ensurepath
pipx install geobe

If pipx is not installed in another Python environment, follow the pipx installation guide.

For local development from a cloned checkout, install Geobe in a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"

Avoid installing Geobe into a system Python with pip install geobe. On modern macOS Homebrew Python and some Linux distributions, pip may fail with externally-managed-environment because the operating system or package manager owns that Python installation. Use pipx install geobe for the CLI, or install inside a virtual environment for development.

Running Programs

Run a .geo file:

geobe examples/input_store_transform_output.geo --input hello

{"outputs": ["hello"]}

Run inline source:

geobe --code "○→▽" --input hello

{"outputs": ["hello"]}

Run a literal string program:

geobe --code "«hello, Geobe!»→▽"

{"outputs": ["hello, Geobe!"]}

Read additional input values from standard input:

printf 'first\nsecond\n' | geobe --code "○→▽\n○→▽" --stdin-input

{"outputs": ["first", "second"]}

Start the interactive spelling console:

geobe --console

Console mode is an alphabet exploration tool rather than the main interpreter. Lowercase letters are echoed as Geobe's mapped triangle symbols. Pressing Enter prints the English equivalent of the current line. For example, typing hello! displays ▹▶▿▿◂!, then Enter prints hello!.

Trace execution as JSON:

geobe --code "○→□→▽" --input hello --trace

Trace execution in readable text:

geobe --code "○→□→▽" --input hello --trace --trace-format text

Running the package module directly executes the built-in demo program:

python3 -m geobe

Example Program

examples/input_store_transform_output.geo

○→□→△→▽

With input hello, the program stores the value, applies the default identity transform, and outputs hello.

Array loop:

○→▶→◀→▶▶

With Python input [1, 2, 3], the program traverses the array and outputs [1, 2, 3].

Triangle alphabet shorthand:

spell ▹▶▿▿◂ ◮◂ ◣▿▵!

This decodes to hello world! and is expanded by the parser into a literal string output program.

Python code can also encode English into the triangle alphabet:

from geobe.parser import encode_spell_text

encoded = encode_spell_text("Hello world!")

Custom Transforms

The △ symbol is backed by a transform registry. The default transform is identity, and you can register your own behavior in Python code.

See examples/custom_transform.py for a minimal example that returns a custom formatted value.

Development

Run the test suite:

pytest

Run linting and type checks:

ruff check .
mypy src tests

Project Layout

• src/geobe/ interpreter, parser, runtime state, and CLI
• examples/ documented sample programs
• tests/ coverage for the CLI, parser, interpreter, and examples

Package Entry Points

• geobe CLI: geobe.cli:main
• Module entry point: python3 -m geobe