Documentation v1.0.1

Overview

bhidu-lang is a premium, feature-rich toy programming language written in TypeScript featuring Mumbai's own local slang (inspired by Jackie Shroff). Compile, run scripts, test environment scopes, and play with error messages, bole toh ekdum jhakaas! 🕶️

Fully Type-Safe Compiler Engine. Built in TypeScript with a custom sticky-regex Tokenizer, recursive-descent AST Parser, parent-linked Environment Scope resolver, and AST Evaluator.

Installation

Install the library globally via NPM to make the command line tools available anywhere on your machine:

npm install -g bhidu-lang

To run during local development, clone the repository, build, and use npm link:

git clone https://github.com/ghostcompiler/bhidu-language.git
cd bhidu-language
npm install
npm run build
npm link

Interactive Simulator

Select a script below, click "Chalao Code! 🚀", and watch the simulated interpreter run your slang code node-by-node in the virtual console.

main.bhidu

Virtual Console

Virtual terminal ready. Click "Chalao Code!"

Choose Example:

CLI Reference

The compiler binary is mapped globally to `bhidu` (or you can invoke it using `node dist/cli.js`). Use the following command parameters:

Execute a file:

bhidu run filename.bhidu

Inspecting AST Structure:

bhidu ast filename.bhidu

Run Interactive REPL:

bhidu repl

Interactive REPL

Start a live interactive session where you can type code statements line-by-line. The REPL preserves variables in a persistent scope environment across lines.

$ bhidu repl
=========================================
   Bhidu-Lang Interactive REPL v1.0.1
   Sab chalta hai bhidu! Type '.exit' to exit.
=========================================
chalu kar bhidu
bhidu> bhidu ye hai x = 10;
bhidu> bhidu ye hai y = 20;
bhidu> bhidu bolta hai("x + y = " + (x + y));
x + y = 30
bhidu> .exit
khatam bhidu

Under the Hood. Since the parser requires code to reside inside program boundaries, the REPL dynamically wraps each line with entry/exit headers (`chalu kar bhidu` / `khatam bhidu`) on the fly, then executes the AST nodes on a persistent global Environment reference.

Bhidu Web Framework

Build and compile interactive web pages directly using bhidu-lang. It supports project scaffolding, static asset serving, hot reloading, and production compilation.

1. Scaffold a project:
bhidu hagde
Creates the directory structure (public/, components/, pages/), copies the default brand logo, and writes a starter homepage at index.bhidu.

2. Run local hot-reloading dev server:
bhidu shuru hoja
Starts the development server at http://localhost:3000. It serves assets from public/ and triggers a browser hot refresh instantly when you save changes in your code.

3. Build production bundle:
bhidu faad de
Transpiles your slang code to out/index.html and copies the public/ folder recursively to out/, ready to deploy to any static provider.

Variables & Reassignment

Variables are declared using the bhidu ye hai keyword, followed by an assignment and a terminating semicolon (;) which is mandatory. Reassigning a variable does not require the declaration prefix.

chalu kar bhidu
  bhidu ye hai naam = "Jackie Shroff";
  bhidu ye hai age = 69;
  
  // Reassignment
  age = 70;
  
  bhidu bolta hai(naam + " is " + age + " years old.");
khatam bhidu

Control Flow (If-Else)

Conditional branches are declared using agar bhidu, warna agar bhidu, and warna bhidu. Braces represent execution block scopes.

chalu kar bhidu
  bhidu ye hai speed = 120;
  
  agar bhidu (speed > 100) {
    bhidu bolta hai("Bohot bhaag raha hai bhidu!");
  } warna agar bhidu (speed > 60) {
    bhidu bolta hai("Sahi jaa raha hai!");
  } warna bhidu {
    bhidu bolta hai("Aadmi hai ki halwa, thoda chal!");
  }
khatam bhidu

Loops (While)

Iterate using the while loop block: jab tak bhidu. Inside a loop block, control execution flow using bas kar bhidu (break) or agli baar bhidu (continue).

chalu kar bhidu
  bhidu ye hai counter = 0;
  
  jab tak bhidu (counter < 10) {
    counter = counter + 1;
    
    agar bhidu (counter == 3) {
      agli baar bhidu; // skip 3
    }
    
    agar bhidu (counter == 7) {
      bas kar bhidu; // stop at 7
    }
    
    bhidu bolta hai(counter);
  }
khatam bhidu

Naked Blocks & Shadowing

Curly braces { ... } define local scoping. If you define a variable with the same name inside a nested block, it shadows the outer scope variable until execution leaves the block.

chalu kar bhidu
  bhidu ye hai a = 10;
  {
    bhidu ye hai a = 20;
    bhidu bolta hai(a); // Prints 20
  }
  bhidu bolta hai(a); // Prints 10
khatam bhidu

Slang Dictionary Reference

Use this table to look up equivalents of standard keywords.

Slang Keyword	JS Equivalent	Description
`chalu kar bhidu`	(implicit)	Program opening tag
`khatam bhidu`	(implicit)	Program closing tag
`bhidu ye hai`	`let / var`	Variable declaration
`sahi bhidu`	`true`	Boolean true
`galat bhidu`	`false`	Boolean false
`khali bhidu`	`null`	Null / Empty value
`bhidu bolta hai(...)`	`console.log(...)`	Prints to stdout console
`agar bhidu(...)`	`if(...)`	Conditional check
`warna agar bhidu(...)`	`else if(...)`	Alternate conditional check
`warna bhidu`	`else`	Fallback condition block
`jab tak bhidu(...)`	`while(...)`	While loop block
`bas kar bhidu`	`break`	Exit loop execution
`agli baar bhidu`	`continue`	Skip current loop cycle

Slang Runtime & Syntax Errors

Errors throw highly descriptive and localized messages in Mumbai slang to make debugging fun!

Undeclared Variable:
Kya re bhidu! Line 3 pe error: Ye 'x' variable kidhar se laya? Pehle declare toh kar ('bhidu ye hai x = ...')!

Redeclared Variable:
Kya re bhidu! Line 4 pe error: Ye 'a' variable pehle se bana chuka hai tu!

Division by Zero:
Kya re bhidu! Line 3 pe error: Zero (0) se divide kar raha hai? Dhandha bandh karwayega kya!

Missing Entry / Exit Point:
Abe bhidu! Khali file kyun diya? Code chalu karne ke liye 'chalu kar bhidu' likh pehle!
Kya re bhidu! Line 12 pe program khatam ho gaya par bandh nahi kiya? 'khatam bhidu' bolna padega!