An esoteric programming language where arrays start at -1, booleans have three values, and whitespace controls operator precedence.
Gulf of Mexico is a production-ready interpreter and IDE for the language conceptually designed by Lu Wilson (TodePond). It features -1-based indexing, three-valued booleans (true, false, maybe), significant whitespace for operator binding, four tiers of equality, temporal variable lifetimes, word-number literals, and statement terminators with confidence levels.
print "Hello, World!"!
print "I am VERY sure this prints."!!
print "I am ABSOLUTELY sure this prints."!!!
| Feature | What it does |
|---|---|
| -1-based indexing | [10, 20, 30][-1] → 10. Arrays, strings, and numbers all start at -1. |
| Three-valued booleans | maybe evaluates probabilistically — if maybe { ... } runs ~50% of the time. |
| Significant whitespace | 2 * 1+3 = 8 but 2*1 + 3 = 5. Tighter spacing binds harder. |
| Tiered equality | = (approximate), == (exact), === (strict), ==== (identity). |
| Tilde equality | ~= (AEMI), ~== (ABI), ~=== (AQMI) — approximate match operators. |
| Temporal lifetimes | var x <5> = "temp"! — variable expires after 5 statements. |
| Negative hoisting | const x<-1> = 42! — variable available one line before declaration. |
| Word numbers | five, nineteen, hundred(3), half, quarter — write numbers as English. |
| Confidence terminators | Statements end with !, !!, or !!! to indicate confidence. ? for debug. |
| No loops | Recursion is the only iteration mechanism. |
| Single-instance classes | Each class can have at most one instance at a time. |
| Emoji identifiers | const 🎉 = 42! — use emoji as variable and function names. |
| Compound assignment | +=, -=, *=, /=, ^= — modify-in-place operators. |
| Currency interpolation | "${x}", "£{x}", "¥{x}" — three currency symbols for string interpolation. |
# Install from PyPI
pip install gulfofmexico
# — or install from source —
git clone https://github.com/James-HoneyBadger/GulfOfMexico.git
cd GulfOfMexico
pip install -e .
# Run a program
gom examples/01_hello_world.gom
# Start the interactive REPL
gom
# Launch the graphical IDE (requires PySide6)
pip install gulfofmexico[ide]
gom-ideConvenience scripts are also provided at the project root:
./run_cli.shand./run_ide.sh.
See docs/INSTALLATION.md for detailed platform-specific setup instructions.
const name = "GOM"! // immutable
var counter = 0! // mutable
var counter = counter + 1! // reassign
// Types: Number, String, Boolean, List, Map, Undefined
const pi = 3.14!
const flag = maybe!
const items = [1, 2, 3]!
const arr = [10, 20, 30]!
print arr[-1]! // 10 — first element
print arr[0]! // 20 — second element
print arr[1]! // 30 — third element
Whitespace controls operator binding — tighter spacing groups first:
const a = 2 * 1+3! // 2 * (1+3) = 8
const b = 2*1 + 3! // (2*1) + 3 = 5
const a = true! // always true
const b = false! // always false
const c = maybe! // true ~50% of the time
;true // false (semicolon = NOT)
;maybe // maybe
10 = 11 // true — approximate (within ~10%)
10 == 11 // false — exact value
10 == 10 // true
10 === 10 // true — value + type
10 ;= 5 // true — inequality (semicolon-equals)
5 ~= 10 // true — AEMI: same type → true
5 ~= "hello" // maybe — different type → maybe
"Hello" ~== "hello" // true — ABI: case-insensitive
100 ~=== 100.5 // true — AQMI: within 1%
function add(a, b) => {
return a + b!
}!
// Single-arg: call with space syntax
function greet(name) => {
print "Hello, ${name}!"!
}!
greet "World"! // space syntax
const sum = add(3, 7)! // parenthesized call
function countdown(n) => {
if n > 0 {
print n!
const prev = n - 1!
countdown(prev)!
}
}!
countdown(5)!
class Counter {
var count = 0!
function increment() => {
count = count + 1!
}!
}!
const c = new Counter!
c.increment()!
print c.count! // 1
// When-watchers: fire when condition becomes true
var x = 0!
when x > 5 {
print "x is now big!"!
}
x = 10! // triggers the watcher
// Variable lifetimes
var temp <3> = "alive"! // expires after 3 statements
// Previous values
var y = 100!
y = 200!
print previous y! // 100
gom # Start the REPL
gom script.gom # Run a file
gom -c "print 42!" # Run inline code
gom -s script.gom # Show Python traceback on error
gom --debug script.gom # Show internal debug messages
The python -m gulfofmexico invocation works identically to gom. Run
gom --help for usage modes, environment variables, and examples. Errors are
reported with source context and clear messages.
The REPL supports persistent history (stored in ~/.gom_history), tab
completion for keywords, in-scope names, and meta-commands, and multi-line
editing that correctly tracks braces across strings and comments.
| Command | Description |
|---|---|
:help |
Show help |
:quit |
Exit REPL |
:reset |
Clear all state |
:load <file> |
Load and execute a .gom file |
:vars |
Show all variables in scope |
:history |
Show command history |
:save <file> |
Save history to a file |
:open <file> |
Open file in default editor |
:run <file> |
Run a file and keep state |
:clip |
Copy last output to clipboard |
48 example programs are included in examples/, covering every feature of the language from hello world to recursive algorithms. See examples/README.md for the full program index.
# Run a single example
gom examples/01_hello_world.gom
# Run all examples
for f in examples/*.gom; do
echo "--- $(basename "$f") ---"
gom "$f"
done| Document | Description |
|---|---|
| Language Reference | Complete syntax and semantics for every language feature |
| Architecture Guide | Interpreter internals, execution pipeline, and module map |
| Installation Guide | Platform-specific setup, virtual environments, extras |
| Contributing Guide | How to contribute, coding standards, and testing workflow |
| Changelog | Version history and release notes |
| Examples Index | Annotated guide to all 48 example programs |
| Code of Conduct | Community standards |
gulfofmexico/ # Main package
├── __init__.py # Entry point — run_file()
├── __main__.py # CLI (argparse)
├── base.py # Token, TokenType, OperatorType, errors
├── builtin.py # Value types, built-in functions, keywords
├── repl.py # Interactive REPL
├── serialize.py # Value serialization for persistence
├── processor/ # Front-end pipeline
│ ├── lexer.py # Tokenizer (source → tokens)
│ ├── syntax_tree.py # Statement parser (tokens → AST)
│ └── expression_tree.py # Expression tree builder
├── interpreter/ # Back-end execution engine
│ ├── context.py # InterpreterContext, type aliases
│ ├── dispatch.py # Statement type classification
│ ├── execution.py # Main interpretation loop
│ ├── expressions.py # Expression evaluator
│ ├── variables.py # Declaration, assignment, lifetimes
│ ├── operators.py # Tiered equality, arithmetic, logic
│ ├── namespaces.py # Scope lookup, literal resolution
│ ├── watchers.py # When-statements, next/previous
│ ├── persistence.py # File I/O for persistent variables
│ └── helpers.py # Small utilities
└── ide/ # Graphical IDE (optional, PySide6)
├── app.py # Main window
├── editor.py # Code editor with line numbers
├── highlighter.py # Syntax highlighting
├── runner.py # Background execution
└── qt_compat.py # PySide6 / PyQt5 compatibility
examples/ # 48 example programs (.gom)
tests/ # 170 unit + integration tests
docs/ # Language reference, architecture, guides
# Run the full test suite (170 tests)
python -m pytest
# Run spec compliance directly
gom tests/spec_compliance.gomSee CONTRIBUTING.md for the full testing workflow.
pip install gulfofmexico # Core interpreter
pip install gulfofmexico[ide] # + Graphical IDE (PySide6)
pip install gulfofmexico[all] # All optional extras| Extra | Package | Feature |
|---|---|---|
ide |
PySide6 | Graphical IDE with 7 themes, movable panels, settings dialog, and syntax highlighting |
input |
pynput | Keyboard input support |
graphics |
Pillow | Image processing |
yaml |
PyYAML | YAML configuration files |
globals |
PyGithub | GitHub-based public variable sharing |
MIT License — see LICENSE for details.
- Language Design — Lu Wilson (TodePond)
- Implementation — James Temple