poop 💩 — ek Hinglish programming language

Bhai ka apna language. Variables, loops, functions, dictionaries, try/catch — sab kuch, bas English ki jagah Hinglish mein likha jaata hai.

kaam namaste(naam)
    wapas `Hanji {naam}, kaise ho?`
band

dikha namaste("duniya")

No compiler, no build step — it's a single-file Python interpreter (poop.py) that reads a .poop file line by line and runs it.

---

Requirements

Just Python 3 (3.8+ is safe). No pip installs, no dependencies. That's it.

Check what you've got:

python3 --version

Running a program

1. Write some poop in a file ending in .poop:

// hello.poop
likh naam = "bhai"
dikha "Kem cho", naam

2. Run it with the interpreter:

python3 poop.py hello.poop

That's the whole workflow. poop.py is the entire language — one file, no install step, no virtual environment needed.

Making it feel like a "real" command (optional)

If you want to type poop hello.poop instead of python3 poop.py hello.poop, drop this in your shell config (.bashrc / .zshrc):

alias poop="python3 /path/to/poop.py"

On Linux/macOS you can also make it directly executable:

chmod +x poop.py
./poop.py hello.poop

(as long as the first line of poop.py stays #!/usr/bin/env python3, which it already does)

---

Project structure

.
├── poop.py          the interpreter — the whole language lives here
├── REFERENCE.md      full language reference: every keyword, operator, builtin
├── index.html        docs site (just open it in a browser, no server needed)
└── main.poop          example program

What's in the language

• Variables, printing, input — likh, dikha, sun
• if / elif / else — dekh / warna_dekh / nahi_toh
• while and for-each loops — jabtak, har_baar
• Functions, including recursion — kaam / wapas
• Lists and dictionaries, with literal syntax ([...] and {...})
• try/catch — koshish / pakad
• String interpolation — `Hello {naam}`
• Compound assignment and increment/decrement — +=, x++
• Importing other .poop files — mangwa
• ~35 builtin functions (math, string, list, dict, file I/O)

See REFERENCE.md for the full breakdown with examples of everything above.

How the interpreter works (if you want to poke around)

poop.py is a tree-walking, line-based interpreter — there's no formal tokenizer/parser/AST stage. It reads the file into a list of lines, and:

• run_block() walks a list of lines and executes them one at a time
• run_line() pattern-matches each line's keyword prefix ("dekh ", "jabtak ", "likh ", etc.) and figures out what to do
• Blocks (if/while/for/functions/try) are found by scanning forward for the matching band, tracking nesting depth as it goes
• poop_eval() evaluates any expression (arithmetic, comparisons, function calls, indexing, literals) recursively
• Control flow (wapas, tod_de) is passed back up the call stack as a small dict like {"type": "wapas", "value": ...} — every layer (if, loops, try) checks for this and re-propagates it instead of swallowing it, which is what lets wapas correctly break out of a function even when it's several loops/ifs deep.

It's not fast and it's not "correct" in a formal-language-design sense — but it's readable, hackable, and every keyword is one if line.startswith(...) away from being findable in the source. If you want to add a keyword, that's the pattern to follow.

Adding your own keyword

Say you want to add bol as another way to print. In run_line():

if line.startswith("bol "):
    rest = line[4:].strip()
    print(poop_eval(rest, {**local_vars}))
    return

Drop it in near the other statement handlers, done. No grammar file to regenerate, no parser to rebuild.

Known limitations

• No real operator precedence beyond what Python's eval() gives you for the arithmetic parts — expressions are mostly evaluated left-to-right by keyword.
• No classes/objects — dictionaries are the closest thing to structured data.
• No exponential-time protection on evaluation depth — jabtak has a hard iteration cap (5,000,000) as a safety net against accidental infinite loops, but recursion is bounded only by Python's own recursion limit.
• Arithmetic expressions are evaluated through a restricted Python eval() (__builtins__ stripped, only your own variables exposed) — fine for a toy language you run locally, not something to expose to untrusted input over a network.

Contributing / extending

It's your language — poop.py is small enough to read start to finish in one sitting. Good next additions if you want to keep going:

• classes / structs (banda types with fields + methods)
• ternary expressions
• switch/match (chuno / case?)
• a real tokenizer if the string-matching starts breaking on edge cases

Have fun, bhai.