Metadata-Version: 2.4
Name: oi-mama
Version: 0.1.0
Summary: A Banglish programming language that transpiles Bangladeshi street expressions into Python
Author: Oi Mama Contributors
License: MIT
Project-URL: Homepage, https://github.com/TahsinRaihan/oi-mama
Project-URL: Repository, https://github.com/TahsinRaihan/oi-mama
Keywords: banglish,bangla,programming-language,transpiler,bangladesh,fun
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Interpreters
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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:

```python
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](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Command Line Usage](#command-line-usage)
- [Full Syntax Reference](#full-syntax-reference)
  - [Declarations and Values](#declarations-and-values)
  - [Input, Output, and Modules](#input-output-and-modules)
  - [Operators and Conditionals](#operators-and-conditionals)
  - [Loops and Control Flow](#loops-and-control-flow)
  - [Functions and Generators](#functions-and-generators)
  - [Object-Oriented Programming](#object-oriented-programming)
  - [Exception Handling](#exception-handling)
  - [Asynchronous Programming](#asynchronous-programming)
- [Error Messages](#error-messages)
- [Project Structure](#project-structure)
- [How It Works](#how-it-works)
- [Running the Test Suite](#running-the-test-suite)
- [Writing Ordinary Python Alongside Oi Mama](#writing-ordinary-python-alongside-oi-mama)
- [Contributing](#contributing)
- [License](#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.
- 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

Clone the repository and install it locally with pip:

```bash
git clone [https://github.com/TahsinRaihan/oi-mama.git](https://github.com/TahsinRaihan/oi-mama.git)
cd oi-mama
pip install .

For active development, install it in editable mode instead:

```bash
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:

```bash
oimama run hello.oimama
```

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

```bash
python -m oimama run hello.oimama
```

## Command Line Usage

```bash
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:

```python
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
│
└── 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:

```bash
python -m unittest discover tests
```

Or run an individual test file directly:

```bash
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](LICENSE)
file for the full text.
