Table of Contents

1. Online Playground (Try Without Installing!)
2. Core Philosophy
3. Installation
4. Language Keywords Reference
5. Example Usage
6. Built-in Fun Functions
7. Ecosystem & Tooling
   • CLI Runner
   • Interactive REPL
   • Package Manager
   • VS Code Extension
8. Standard Library (Stdlib)
9. Funny Error System
10. Automated Testing

🌐 Online Playground (Try Without Installing!)

Want to code in JugaadLang immediately without installing Python or setting up a local environment? Use our free, in-browser interactive compiler & playground:

👉 Launch JugaadLang Online Playground 🚀

Playground Features:

• ⚡ 100% Client-Side: Powered by WebAssembly (Pyodide) — zero server dependencies, instant execution.
• 🎨 Monaco Editor: Full VS Code-like coding environment with custom syntax highlighting and indentation.
• 🔍 Dual-Pane Transpiler: View your generated standard Python code side-by-side in real time.
• 💡 Desi Error Diagnostics: Hilarious and helpful error diagnostics with real-time red squiggly error markers pointing to the exact line.
• 💾 Export & Download: Download your program as .jug (source) or .py (transpiled Python) with a single click.

Core Philosophy

1. Python simplicity: Clear, indentation-based block syntax.
2. Hindi-English keywords: Express logic in the language you think in.
3. Humorous diagnostics: Error messages that make you laugh, not crash.
4. Zero-overhead transpilation: Compiles to Python bytecode and executes in the native Python VM.

Installation

Get started with JugaadLang in just a few minutes.

Requirements

Before installing JugaadLang, make sure you have:

• Python 3.10 or later
• pip package manager

Check your Python version:

python --version

or

python3 --version

🪟 Windows

Install

pip install jugaadlang

Verify Installation

jug --version

Expected output:

JugaadLang v1.2.8 🇮🇳

Run Your First Program

Create a file named hello.jug

bolo("Namaste Duniya 🚀")

Run it:

jug run hello.jug

Output:

Namaste Duniya 🚀

🐧 Linux

Install

Option A: Using Homebrew (Recommended)

brew tap jugaadlang/tap
brew install jugaadlang

Option B: Using pip

pip3 install jugaadlang

Verify Installation

jug --version

Run

jug run hello.jug

🍎 macOS

Install

Option A: Using Homebrew (Recommended)

brew tap jugaadlang/tap
brew install jugaadlang

Option B: Using pip

pip3 install jugaadlang

Verify Installation

jug --version

Run

jug run hello.jug

🚀 Install Latest Development Version

Install directly from GitHub:

pip install git+https://github.com/JugaadLang/jugaadlang.git

Verify:

jug --version

📦 Package Manager

JugaadLang includes a built-in package manager.

Install Package

jug install chai

Search Package

jug search chai

Update Packages

jug update

Remove Package

jug remove chai

⚡ Interactive REPL

Start the JugaadLang shell:

jug repl

Example:

>>> bolo("Namaste")
Namaste

🔧 Common Commands

🎉 Success

Language Keywords Reference

Standard Built-in Function Mappings

JugaadLang supports Roman Hindi wrappers for standard Python built-in functions. They map directly to Python's built-ins:

Python 3.14 & 3.15 Language Features

JugaadLang keeps up with CPython's What's New releases. Each feature compiles to the native construct on interpreters that understand it and to an equivalent older construct otherwise, so one .jug file runs on every supported Python (3.10+).

roop(template) renders a t"..." back to text; without it bolo prints the template object, since templates keep their literal pieces separate for SQL, HTML, or logging. Below Python 3.15 the new builtins raise a JugaadLang error naming the required version.

Example Usage

1. Simple Control Flow (hello.jug)

# Ask for user name
poochho naam

agar naam == "Sumangal":
    bolo("Legend mil gaya! 😎")
warna:
    bolo("Namaste " + naam)

Run it:

jug run hello.jug

2. Classes & Functions (oop.jug)

ustad Developer:
    banao shuru(khud, naam, language):
        khud.naam = naam
        khud.language = language

    banao batao(khud):
        bolo(khud.naam + " code likh raha hai " + khud.language + " mein!")

dev = Developer("Sumangal", "JugaadLang")
dev.batao()

### 3. Pattern Matching (`match.jug`)
```jugaadlang
banao test_match(x):
    agar_match x:
        kaand sahi:
            wapas "boolean true"
        kaand 1:
            wapas "one"
        kaand [a, b]:
            wapas "sequence of " + str(a) + " and " + str(b)
        kaand _:
            wapas "something else"

bolo(test_match(1))
bolo(test_match(sahi))
bolo(test_match([10, 20]))

---

## Built-in Fun Functions
Enjoy several custom interactive built-ins directly at runtime:
* `chai()`: Prints a warm cup of ASCII tea (`☕ Chai pi lo.`)
* `himmat()`: Prints a motivational programming boost (`🔥 Hidden feature detected.`)
* `ghaas_chhoo()`: Gently reminds you to go touch some grass (`🌱 Bahar ghoom aao.`)
* `bachao()`: Starts a mock search for help (`🚨 StackOverflow search shuru.`)
* `fortune()`: Tells a programmer's fortune (`🔮 Bug line 347 mein ho sakta hai.`)
* `jugaad()`: Gives a random hacking/debugging tip.
* `nazar()`: Blocks bad vibes and bugs (`🧿 Nazar suraksha kavach active! Bad vibes/bugs blocked. 🧿`).
* `ashirwad()`: Boosts runtime success rate with elder blessings (`👵 Sadbhavna aur aashirwad active! Success rate boosted to 100%! 👵`).
* `dhanya_waad()`: Expresses polite gratitude (`🙏 Dhanyawaad! Code chalaane ke liye aapka aabhari hoon. Keep coding! 🙏`).
* `bhagwan_bhala_kare()`: Prays for errors to disappear (`📿 Hey bhagwan, iss error ko apne aap thik kar do! Please! 📿`).
* `paisa_wasool()`: Reminds you that JugaadLang is free (`💸 Paisa Wasool! JugaadLang is 100% free and open-source, your money is safe! 💸`).
* `bas_kar_bhai()`: Advises to stop coding and sleep (`🛑 Bas kar bhai! Kitna code likhega? So ja thodi der. 🛑`).
* `chilla_mat()`: Calms you down during debugging (`🤫 Chilla mat, deep breath le aur debug kar. 🤫`).
* `kundli()`: Performs astrological diagnostics on your code to see if Shani or Rahu are transit-blocking your variables/loops.
* `roop(t"...")`: Renders a template string back to text — `bolo(roop(t"Namaste {naam}!"))` (Python 3.14+; a no-op passthrough on older interpreters).

---

## Ecosystem & Tooling

### CLI Runner
* **Run a file:** `jug run main.jug` (supports script argument passing like `jug run main.jug arg1 arg2`)
* **Check syntax:** `jug check main.jug`
* **Static type-checking:** `jug typecheck main.jug` (performs static analysis using `mypy` behind the scenes)
* **Transpile to Python source:** `jug compile main.jug -o main.py`
* **Create a boilerplate project:** `jug new my_project`

### Interactive REPL
Launch a beautiful interactive terminal shell:
```bash
jug repl

Features auto-completion for all keywords, live syntax highlighting, input history, and double-Enter multiline block detection.

Package Manager

Integrate pip packages or custom bundles:

• Install: jug install web (installs Flask, requests, httpx, and aiohttp)
• Remove: jug remove web
• Update: jug update web
• Search: jug search query

VS Code Extension

Launch the extension from vscode_extension/. Features full syntax highlighting for .jug files, 25+ snippets, hovered keyword documentation in Hindi, and a status bar icon.

Standard Library (Stdlib)

Import standard libraries using lao (e.g. lao ganit):

1. ganit: Hindi wrappers for arithmetic/geometry (e.g. ganit.sin, ganit.pi, ganit.sqrt).
2. web: HTTP request wrappers (web.get, web.post) and JugaadWeb framework with @web.agar_route("/") and web.chalao().
3. faili: Clean file system API (faili.padho, faili.likho, faili.jodo).
4. json: Native parser (json.banao_string, json.banao_object).
5. samay: DateTime operations (samay.abhibhi(), samay.aaj(), samay.soja()).
6. tantra: Access system variables (tantra.argv, tantra.exit(), tantra.platform).
7. crypto: Hash encryption (crypto.sha256, crypto.base64_encode).
8. database: SQLite ORM (JugaadORM) backing tables with bachao() and filter().
9. Fun Libraries: chai, jokes, motivation, fortune, memes, catfacts.

Funny Error System

Tired of dry Tracebacks? JugaadLang features humorous Hindi exceptions:

SyntaxError

🤦 Bhai kya likh diya?
Faili: hello.jug Line 3, Col 12

  agar x ==
            ^

Error Details: Expected value.
Keyboard strike par hai kya?

NameError

🕵️ Variable 'x' dhundte dhundte thak gaya.
Faili: hello.jug Line 12

  > bolo(x)

Kya gadbad hai?
  'x' mila hi nahi.

Possible reasons:
  • Typo kiya hai
  • Variable declare karna bhool gaye
  • Universe collapse ho gaya

DivisionByZero

💀 Zero se divide?
Faili: hello.jug Line 5

Kya gadbad hai?
  Newton bhi confuse ho gaya. Maths seekh lo thoda.

Developer Tooling & Testing

For local development and testing, we provide a unified helper script run.sh to automate tasks:

# Clean previous builds, run tests, and perform editable installation
./run.sh all

# Run test suite dynamically under the active Python environment
./run.sh test

# Clean build artifacts and package wheels/tarballs
./run.sh build

# Install JugaadLang locally in editable mode with all development dependencies
./run.sh install
All test cases are written using `pytest` inside the `tests/` directory.

---

## Architecture & Project Technical Specification

### 🏗️ Project Architecture & Pipeline
JugaadLang transpiles Roman Hindi syntax into native Python AST with zero runtime overhead:
```text
Source (.jug) ──► Lexer (Token Stream) ──► Parser (JL AST) ──► Transformer (Python AST) ──► compile() / exec()

🧰 Tech Stack

• Language: Python 3.10+ (Tested across Python 3.10, 3.11, 3.12, 3.13, 3.14, 3.15)
• CLI Engine: click with custom JugaadGroup and JugaadCommand
• Terminal UI & Diagnostics: rich
• Linting & Code Quality: ruff
• Testing & Coverage: pytest & pytest-cov (81%+ code coverage)

📦 Key Components & APIs

• jug_cli.main:main: Central Click group supporting -h/--help, formatted command descriptions, and an interactive Examples section.
• jugaadlang.lexer.lexer.Lexer: Indentation-aware tokenizer converting Hindi keywords to tokens.
• jugaadlang.parser.parser.Parser: Recursive descent parser producing language AST.
• jugaadlang.transformer.to_python.JugaadToPythonTransformer: AST transformer rewriting JugaadLang constructs to standard ast nodes.
• jugaadlang.runtime.interpreter.JugaadInterpreter: Execution engine handling bytecode compilation and runtime error traps.
• jugaadlang.package_manager.manager.JugaadPackageManager: Package installation, removal, update, and search engine.

🐛 Fixed Bugs & Enhancements (Issue #115)

• Enhanced CLI Help Output: Implemented native definition list rendering (write_dl) for examples in jug --help and subcommands.
• Dual Flag Support: Enabled -h alias alongside standard --help.
• Clean Command Summaries: Fixed Click sentence-splitting bug that previously truncated the install command description.

🚀 Setup & Verification Commands

# 1. Setup virtual environment
python -m venv .venv
.venv\Scripts\activate   # Windows
source .venv/bin/activate # Linux/macOS

# 2. Install editable with development extras
pip install -e .[dev,all]

# 3. Linting check
ruff check .

# 4. Run test suite with coverage
pytest --cov=jugaadlang