Documentation v1.0.2

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 & Commands

The compiler binary is mapped globally to bhidu (or you can invoke it using node dist/cli.js). Here is the complete list of all commands available in the CLI:

Command Syntax	Description	Usage Example
`bhidu run <file.bhidu>`	Execute a `.bhidu` script file directly in your terminal.	`bhidu run test.bhidu`
`bhidu repl` or `bhidu`	Start the interactive REPL shell to run statements line-by-line.	`bhidu repl`
`bhidu ast <file.bhidu>`	Print the parsed Abstract Syntax Tree (AST) as structured JSON.	`bhidu ast test.bhidu`
`bhidu hagde [project-name]`	Scaffold a new project folder structure with `public/`, `components/`, `pages/`, and `index.bhidu`. Prompts if project name is omitted.	`bhidu hagde my-web-app`
`bhidu shuru hoja [file.bhidu]`	Starts the live-reloading Dev Server (default: `index.bhidu`) on port 3000 with static asset resolution from the `public/` folder.	`bhidu shuru hoja`
`bhidu faad de [file.bhidu]`	Compiles the application to production-ready static HTML in `out/index.html` and copies all files from `public/` to `out/`.	`bhidu faad de`
`bhidu help`	Display the helper menu with syntax templates.	`bhidu help`

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.2
   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.

VS Code IDE Extension

Enhance your development experience with the dedicated VS Code extension for bhidu-lang. It supports syntax highlighting, document formatting, and real-time linter diagnostics.

Features:

Syntax Highlighting: Custom TextMate grammar mapping slang keywords to standard VS Code token classes.
Document Formatting: Indents code lines automatically between block boundaries (brackets or entry/exit keywords).
Diagnostics (Linter): Checks code dynamically on edit/save and highlights syntax errors with red squiggles, showing slang error messages.

Installation:
Run the following command in your terminal from the project root folder to install the prepackaged extension:

code --install-extension extension/bhidu-vscode-1.0.2.vsix

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!