Documentation v1.0.4

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 compiler globally via NPM to make the command line tools available anywhere on your machine:

npm install -g bhidu-lang

Bole toh update complete! Make sure you have Node.js (v18+) installed. Once the package is installed globally, the bhidu binary will be ready to execute from any folder in your terminal.

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.4
   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 zero-config project scaffolding, asset pipeline serving, local hot-reloading dev server, reactive state updates, and static production bundling.

1. Project Initialization & Scaffolding (bhidu hagde):
To create and initialize a new Bhidu web application, run:

bhidu hagde [project-name]

If you omit the project name, the CLI will interactively ask: "bhidu is project ka naam kya rkhna h wo to bta". This command bootstraps a professional, ready-to-use directory structure:

public/: For static assets (holds logo.png by default).
components/: For modular, reusable components.
pages/: For additional application subpages.
index.bhidu: The entry point rendering a premium dark-themed layout.

2. Run Local Development Server (bhidu shuru hoja):
Start a hot-reloading web server to preview your application on http://localhost:3000:

bhidu shuru hoja [file.bhidu]

This server watches your code files for changes, automatically refreshes the browser page on save, compiles and bundles component CSS, and serves static files from the public/ folder seamlessly.

3. Compile for Production (bhidu faad de):
Compile your dynamic Bhidu application into standalone static HTML and JS ready for deployment:

bhidu faad de [file.bhidu]

This transpiles your slang code to out/index.html, collects and bundles all styles, and copies the public/ folder assets recursively to out/, making the build deployable to GitHub Pages, Netlify, Vercel, or any other static host.

⚡ Reactive State, Effects & Component CSS System:

State Management: Variables declared with bhidu ye hai preserve their values across page renders. Use bhiduSetState('name', value) in your HTML event handlers (e.g. onclick) to update state and trigger automatic UI re-renders.
Side Effects: Invoke side-effects reactively using bhiduEffect(callback, dependencies) inside your slang scripts.
Component CSS System: Stylesheet (.css) files in your project folders (public/, components/, or pages/) are auto-bundled and injected into the HTML page's <head> without any manual import code.

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.4.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!