oi-mama 0.1.1

A Banglish programming language that transpiles Bangladeshi street expressions into Python

Oi Mama

Oi Mama is a Banglish programming language built on top of Python. It lets developers write code using everyday Bangladeshi expressions, written in Latin script, which are transpiled directly into valid Python and executed with the full power of the Python runtime and its entire ecosystem of libraries.

dhor mama age = 20

mama jodi age >= 18:
    mama bol("Mama, tui boro hoye gesos!")

is equivalent to:

age = 20

if age >= 18:
    print("Mama, tui boro hoye gesos!")

Oi Mama is not a new language runtime. It is a source-to-source transpiler: Oi Mama source code is converted into an in-memory Python Abstract Syntax Tree using Python's own ast module, then compiled and executed by the standard CPython interpreter. This means every Python library, every Python language feature, and every existing Python debugging tool works with Oi Mama out of the box.

Table of Contents

• Features
• Installation
• Quick Start
• Command Line Usage
• Full Syntax Reference
  • Declarations and Values
  • Input, Output, and Modules
  • Operators and Conditionals
  • Loops and Control Flow
  • Functions and Generators
  • Object-Oriented Programming
  • Exception Handling
  • Asynchronous Programming
• Error Messages
• Project Structure
• How It Works
• Running the Test Suite
• Writing Ordinary Python Alongside Oi Mama
• Contributing
• License

Features

• A complete Banglish vocabulary covering variable declarations, conditionals, loops, functions, classes, exception handling, and asynchronous programming.
• Full interoperability with the Python standard library and any installed third-party package, through the standard mama an (import) construct.
• Line-accurate Banglish error messages. When something goes wrong, the reported line number always matches the line in the original .oimama file, not an internal intermediate representation.
• String literals and comments are never rewritten, so any text, including text that happens to contain Oi Mama keywords, is preserved exactly as written. The one deliberate exception is f-strings: the literal text portions of an f-string are left untouched, but Banglish keywords inside an f-string's {expression} sections, such as nijer in f"{nijer.name}", are correctly translated, since that code is still real Python code being evaluated, not literal text.
• Ordinary, unmodified Python code is also valid Oi Mama code. Nothing is lost by mixing styles or by gradually introducing Banglish syntax into an existing Python file.

Installation

Install directly from PyPI using pip:

pip install oi-mama

Or install directly from the source repository:

git clone https://github.com/TahsinRaihan/oi-mama.git
cd oi-mama
pip install .

For active development, install it in editable mode instead:

pip install -e .

Oi Mama requires Python 3.9 or later.

Quick Start

Create a file named hello.oimama:

dhor mama name = "Mama"
mama bol("Kemon achos,", name, "?")

mama jodi sotti mama:
    mama bol("Oi Mama is working!")

Run it from the command line:

oimama run hello.oimama

Or run it as a Python module without installing the package first:

python -m oimama run hello.oimama

Command Line Usage

oimama run <file.oimama>          Execute an Oi Mama script
oimama transpile <file.oimama>    Print the equivalent Python source
oimama --version                  Print the installed version

Oi Mama can also be used directly from Python code:

import oimama

oimama.run_file("hello.oimama")

oimama.run_string("dhor mama x = 5\nmama bol(x)\n")

python_source = oimama.transpile("dhor mama x = 5\nmama bol(x)\n")
print(python_source)

Full Syntax Reference

Declarations and Values

Banglish Keyword	Python Equivalent	Example
dhor mama <var> = <val>	<var> = <val>	dhor mama speed = 100
mama shob <var>	global <var>	mama shob x
mama eita na <var>	nonlocal <var>	mama eita na y
mama kissu na	None	dhor mama res = mama kissu na
sotti mama	True	dhor mama status = sotti mama
micha mama	False	dhor mama status = micha mama

Input, Output, and Modules

Banglish Keyword	Python Equivalent	Example
mama bol(...)	print(...)	mama bol("Kemon achos mama?")
mama shun(...)	input(...)	dhor mama name = mama shun("Naam ki? ")
mama an <module>	import <module>	mama an math
mama an <module> theke <item>	from <module> import <item>	mama an math theke sqrt
mama daki <alias>	as <alias>	mama an numpy mama daki np

Operators and Conditionals

Banglish Keyword	Python Equivalent	Example
mama jodi <cond>:	if <cond>:	mama jodi score > 50:
mama emne <cond>:	elif <cond>:	mama emne score == 50:
mama naile:	else:	mama naile:
ebong	and	mama jodi a > 0 ebong b > 0:
othoba	or	mama jodi a == 0 othoba b == 0:
na	not	mama jodi na done:
eita	is	mama jodi val eita mama kissu na:
vetore	in	mama jodi "x" vetore text:

Note that eita translates to Python's identity operator is, which tests whether two references point to the same object. For comparing values, such as numbers or strings, use the standard == operator directly; it is valid Oi Mama syntax exactly as it is valid Python syntax, since any operator or symbol not found in this table is passed through unchanged.

Loops and Control Flow

Banglish Keyword	Python Equivalent	Example
mama ghura <var> vetore <iter>:	for <var> in <iter>:	mama ghura i vetore range(5):
mama jotokhon <cond>:	while <cond>:	mama jotokhon count > 0:
mama thamb / mama tham	break	mama thamb
mama chalai ja	continue	mama chalai ja
mama thak	pass	mama thak

Both mama thamb and mama tham are accepted spellings for break.

Functions and Generators

Banglish Keyword	Python Equivalent	Example
mama shon <func>(<args>):	def <func>(<args>):	mama shon jog(a, b):
mama ferot <val>	return <val>	mama ferot a + b
mama de <val>	yield <val>	mama de i
mama choto <args>: <expr>	lambda <args>: <expr>	dhor mama f = mama choto x: x * 2

Object-Oriented Programming

Banglish Keyword	Python Equivalent	Example
mama jat <Class>:	class <Class>:	mama jat Car:
nijer	self	nijer.speed = 0
mama chacha	super	mama chacha().__init__()

Exception Handling

Banglish Keyword	Python Equivalent	Example
mama dekhi:	try:	mama dekhi:
mama dhor <Err> mama daki <e>:	except <Err> as <e>:	mama dhor Exception mama daki e:
mama sheshe:	finally:	mama sheshe:
mama shob thik:	else: (inside try)	mama shob thik:
mama bhalobhasho <msg>	raise <msg>	mama bhalobhasho Exception("Error!")
mama shure <cond>, <msg>	assert <cond>, <msg>	mama shure x > 0, "Choto number!"
mama dhore <ctx> mama daki <var>:	with <ctx> as <var>:	mama dhore open("f.txt") mama daki f:

Asynchronous Programming

Banglish Keyword	Python Equivalent	Example
mama aste <func>(<args>):	async def <func>(<args>):	mama aste get_data():
mama thambish <expr>	await <expr>	dhor mama res = mama thambish get_data()

Error Messages

When something goes wrong, Oi Mama reports the problem in Banglish, pointing directly at the offending line in the original .oimama file:

Mama Jamela Hoise! (SyntaxError)
----------------------------------------
Line 4: mama jodi age >= 18
                    ^
Error: Mama colon (:) dite bhule gesos!

Mama Bhool Karchos! (NameError)
----------------------------------------
Line 12: mama bol(kicchu)
         ^
Error: 'kicchu' naame to kono variable khuje pailam na mama!

Mama Shon! (ZeroDivisionError)
----------------------------------------
Line 8: dhor mama ans = 10 / 0
        ^
Error: 0 diya ki bhag kora jai mama? Pagol hoisos?

Every common Python exception type has a corresponding Banglish message, including TypeError, IndexError, KeyError, AttributeError, ImportError, ValueError, and RecursionError. Any exception type without a specific Banglish translation still receives a general Banglish message along with the original Python error text, so no failure is ever silently hidden.

Project Structure

oi-mama/
├── PROJECT_PLAN.md             Original project blueprint and design notes
├── README.md                   This document
├── LICENSE                     MIT License
├── pyproject.toml              Build and installation configuration
│
├── oimama/                     Core package
│   ├── __init__.py              Public API: run_file, run_string, transpile, compile_source
│   ├── __main__.py              Command line entry point (the `oimama` command)
│   ├── keywords.py              Banglish-to-Python keyword mapping tables
│   ├── lexer.py                 Transforms Oi Mama source into valid Python source
│   ├── parser.py                Turns transformed source into a Python AST and code object
│   ├── errors.py                Formats exceptions as Banglish error messages
│   └── runner.py                Wires the lexer, parser, and error formatter together
│
├── examples/                   Sample scripts
│   ├── hello.oimama              Variables, conditionals, input and output
│   ├── loop.oimama               For loops, while loops, break, and continue
│   ├── async_demo.oimama         Asynchronous functions and await
│   └── everything_demo.oimama    Inheritance, linked lists, recursion,
│                                 pattern matching, decorators, comprehensions,
│                                 operator overloading, and f-strings
│
└── tests/                      Automated test suite
    ├── __init__.py
    ├── test_lexer.py             Tests for the Banglish-to-Python transformation
    └── test_parser.py            Tests for AST generation and compilation

How It Works

Running an .oimama file happens in four stages:

1. Lexing (oimama/lexer.py). The raw .oimama source text is scanned line by line. String literals and comments are located and protected so their contents are never rewritten. Everywhere else, the source is scanned word by word and matched against the keyword tables in oimama/keywords.py, using the longest possible phrase match at each position. The result is a string of fully valid Python source code, with the exact same number of physical lines as the original file.

2. Parsing (oimama/parser.py). The transformed Python source text is handed to Python's own ast.parse function. This is a deliberate design decision: rather than reimplementing Python's grammar by hand, Oi Mama relies on the same parser that CPython itself uses, which guarantees full compatibility with every Python language feature without any additional engineering effort. Any syntax error raised at this stage is re-raised as an OiMamaSyntaxError, which preserves the original line number, column offset, and message.

3. Compilation. The resulting AST is passed through ast.fix_missing_locations and then compiled into a Python code object using the built-in compile function.

4. Execution and error reporting (oimama/runner.py). The code object is executed with exec. If a runtime exception is raised, oimama/errors.py inspects the traceback, finds the relevant frame in the user's own file, and formats a Banglish error message that points at the correct line in the original .oimama source.

Running the Test Suite

The project uses the built-in unittest framework. From the project root:

python -m unittest discover tests

Or run an individual test file directly:

python -m unittest tests.test_lexer
python -m unittest tests.test_parser

Writing Ordinary Python Alongside Oi Mama

Because Oi Mama keywords are only recognized as whole words, and because any word that is not part of the Banglish vocabulary is left completely untouched, ordinary Python code is always valid Oi Mama code. This makes it possible to introduce Banglish syntax gradually into an existing Python file, or to freely mix both styles in the same script:

import json

mama shon build_payload(name, score):
    dhor mama payload = {"name": name, "score": score}
    mama ferot json.dumps(payload)

print(build_payload("Sakib", 95))

Contributing

Contributions are welcome. When adding a new Banglish keyword, update oimama/keywords.py, add a corresponding entry to the syntax reference table in this document, and add a test case in tests/test_lexer.py that exercises both the transformation and the resulting runtime behavior.

License

This project is licensed under the MIT License. See the LICENSE file for the full text.