Kural

Kural (.krl) is a small programming language, a compiler, a virtual machine, and a from-scratch x86-64 native backend — all built in Node.js with zero external dependencies: no lexer/parser libraries, no NASM/MASM/LLVM/GCC, no linker. Kural source compiles to JavaScript, executes directly on a hand-written Virtual Machine, or compiles all the way down to a genuinely standalone Windows .exe.

exp factorial(n) {
    inCase (n <= 1) {
        pass 1
    }
    pass n * factorial(n - 1)
}

krlout(factorial(5))

Installation

git clone https://github.com/Velan0404/kural.git
cd kural
npm install -g .

kural version

A standalone Windows ZIP (no npm required) is also available — see docs/INSTALLATION.md for both paths, including how to verify a global install in a disposable sandbox.

Quick Start

kural new Calculator
cd Calculator
kural run

kural new <name> scaffolds a project (console/library/empty templates); kural run resolves any declared modules and executes directly on the Virtual Machine — no JavaScript file is ever written. See docs/GETTING_STARTED.md for the full walkthrough (build/test/fmt/doctor/clean/update, adding dependencies) and docs/CLI_REFERENCE.md for every kural/kpm command.

Examples

Six runnable programs are bundled under sdk/examples/:

kural run sdk/examples/helloWorld.krl
kural run sdk/examples/calculator.krl
kural run sdk/examples/loops.krl
kural run sdk/examples/functions.krl
kural run sdk/examples/arrays.krl
kural run sdk/examples/strings.krl

Features

• A real language: variables (cont/Array), functions (exp/ pass), control flow (inCase/or), three loop forms (for/ while/do...while) with stop/go, arrays, and a built-in method API for both arrays and strings — no type system, no first-class functions, integers only (see docs/STDLIB.md for exactly what that rules out and how the standard library works around it).
• Four independent backends from one validated AST: a JavaScript code generator, a from-scratch Virtual Machine, an IR optimizer (7 passes to a fixed point), and a full x86-64 native backend (linear- scan register allocation, a hand-written machine code encoder, and a hand-written Windows PE writer — no assembler, no linker).
• Professional diagnostics: colorized, code-framed errors and warnings, with every IR instruction source-mapped back to its originating line/column, all the way through the optimizer and native backend.
• A standard library and package manager, implemented entirely as tooling in front of the (unmodified) compiler: math/string/ array/io/time/random, plus kpm (a local, filesystem-based package manager) and the kural project CLI.
• An SDK: project templates, bundled examples, and both an npm and a standalone Windows distribution path.

Architecture

Source -> Lexer -> Parser -> AST -> Semantic Analyzer -> (validated AST)
                                                              |
                                    +-------------------------+-------------------------+
                                    v                                                     v
                              IR Generator                                    JavaScript Code Generator
                                    |                                                     |
                          +---------+---------+                                  generated/output.js
                          v         v          v
                  IR Printer   Virtual Machine   Optimizer -> x86-64 backend -> generated/program.exe
                    (--ir)        (--vm)         (--opt-ir)   (--asm/--bin/--exe)

See docs/ARCHITECTURE.md for the full pipeline diagram, the standard-library/package-manager layer, and the complete project structure.

Roadmap

Twenty phases, each complete and covered by the test suite: Lexer → Parser → AST → Semantic Analysis → JavaScript Code Generation → Control Flow → Loops → Arrays → Array/String Methods → Intermediate Representation → Virtual Machine → IR Optimizer → x86-64 Instruction Selection → Machine Code Encoding → Windows PE Writing → Diagnostics → Register Allocation → Standard Library & Package Manager → SDK & Distribution. See docs/ROADMAP.md for the detailed, phase-by-phase history.

Contributing

npm test

Runs the full suite (Node's built-in node:test runner — no test framework dependency either). Every subsystem has its own design-notes doc under docs/ (LEXER.md through ARCHITECTURE.md) — read the one for the area you're touching before changing it. Pull requests should include tests that exercise the real pipeline (Lexer → ... → VM/native backend), not mocks, matching this project's own testing style throughout.

License

MIT