• About The Project
• Key Features
• Getting Started
• Usage / Examples
• Language Reference
• Architecture
• Roadmap
• Contributing
• License
• Contact / Support

Mutant Lang is a dynamically-typed, interpreted scripting language implemented as a tree-walking interpreter entirely in Rust. It was built from first principles to explore every layer of language implementation — from raw character streams to a full object-oriented runtime — without relying on any parser-generator or VM framework.

The project exists to answer one question: what does it actually take to go from a .mutant source file to a running program? Every stage is hand-rolled:

• Full OOP — class, extends, super, this, constructors, and method overriding
• First-class functions & closures — functions capture their defining scope
• F-string interpolation — f"Hello {name}, you are {age} years old!"
• Rich type system — integers, floats, booleans, strings, arrays, hash maps, and null
• Compound assignment operators — +=, -=, *=, /=, %=
• Bitwise operators — &, |, ^, ~, <<, >>
• Flexible control flow — if / elif / else, while, for, break, continue, return
• Nested comment styles — # single-line and /* nested /* block */ */
• Colored REPL output — integers in yellow, strings in green, booleans in cyan
• Precise error messages — every token carries its (line, col) source position

# 1. Clone the repository
git clone https://github.com/utkarsh5026/interpreter.git
cd interpreter/lib

# 2. Build a release binary
cargo build --release

# 3. The binary is now at:
./target/release/mutant-lang

cargo run --release

  ███╗   ███╗██╗   ██╗████████╗ █████╗ ███╗   ██╗████████╗
  ████╗ ████║██║   ██║╚══██╔══╝██╔══██╗████╗  ██║╚══██╔══╝
  ██╔████╔██║██║   ██║   ██║   ███████║██╔██╗ ██║   ██║
  ██║╚██╔╝██║██║   ██║   ██║   ██╔══██║██║╚██╗██║   ██║
  ██║ ╚═╝ ██║╚██████╔╝   ██║   ██║  ██║██║ ╚████║   ██║
  ╚═╝     ╚═╝ ╚═════╝    ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═══╝   ╚═╝
                    L A N G   v 0 . 1
  Type Ctrl-C or Ctrl-D to exit.

>>

cargo test

print("Hello, World!");

let counter = 0;
counter += 1; // mutable — OK

const PI = 3.14159;
// PI = 3;          // compile-time error: cannot reassign constant

fn makeAdder(x) {
    return fn(y) { return x + y; };
}

let add5 = makeAdder(5);
print(add5(3));   // 8

let name = "Alice";
let score = 42;
print(f"Player {name} scored {score * 2} points!");
// Player Alice scored 84 points!

class Animal {
    constructor(name) {
        this.name = name;
    }
    speak() { return f"{this.name} makes a sound"; }
}

class Dog extends Animal {
    speak() { return f"{this.name} barks!"; }
}

let d = new Dog("Rex");
print(d.speak());  // Rex barks!

fn fib(n) {
    if (n <= 1) { return n; }
    return fib(n - 1) + fib(n - 2);
}

for (let i = 0; i < 10; i += 1) {
    print(f"fib({i}) = {fib(i)}");
}

For more examples see the existing README language reference above, or explore lib/src/evaluator/ and lib/src/parser/.

len(arr); // length of array or string
first(arr); // first element
last(arr); // last element
rest(arr); // all elements except first
keys(hash); // array of hash keys
values(hash); // array of hash values
type(value); // "INTEGER" | "FLOAT" | "STRING" | ...
print(a, b, c); // print to stdout, space-separated

# This is a single-line comment

/*
 * This is a block comment.
 * /* Nesting is supported. */
 * Still in the outer comment.
 */

Source Code
    │
    ▼
┌──────────────────────────────────────────────┐
│  LEXER  (lib/src/lexer/)                     │
│  CharacterStream → pull-style Token iterator │
│  Handles: strings, f-strings, nested comments│
│           escape sequences, (line,col) pos   │
└──────────────────────┬───────────────────────┘
                       │ Token stream
                       ▼
┌──────────────────────────────────────────────┐
│  PARSER  (lib/src/parser/)                   │
│  Recursive descent (statements)              │
│  Pratt / TDOP (expressions & precedence)     │
└──────────────────────┬───────────────────────┘
                       │ AST (lib/src/ast/)
                       ▼
┌──────────────────────────────────────────────┐
│  EVALUATOR  (lib/src/evaluator/)             │
│  Tree-walking interpreter                    │
│  Chained Environment scoping                 │
│  Control-flow via Object sentinels           │
│  (Return, Break, Continue)                   │
└──────────────────────┬───────────────────────┘
                       │ Object
                       ▼
┌──────────────────────────────────────────────┐
│  REPL  (lib/src/repl.rs)                     │
│  rustyline editor + colored output           │
│  Persistent Environment across inputs        │
└──────────────────────────────────────────────┘

• Object is a single Rust enum, not a class hierarchy — pattern matching replaces dynamic dispatch everywhere
• Environments are Rc<RefCell<…>> chains — child scopes hold a reference to their parent without cloning the whole chain
• Pratt parser handles all infix/prefix expressions cleanly with explicit precedence levels (see lib/src/parser/precedence.rs)
• thiserror drives all structured error types, giving human-readable messages with source positions for free

• Standard library (math, string utilities, I/O)
• import / module system
• Bytecode compiler + stack-based VM
• Type inference / optional static types
• Garbage collector (replace clone-on-bind with Rc or tracing GC)
• Concurrency primitives (async/await)
• Language Server Protocol (LSP) support
• WASM compilation target

Contributions are warmly welcome. Here's the standard flow:

1. Fork the repository
2. Create a feature branch — git checkout -b feat/my-feature
3. Commit your changes — git commit -m "feat: add my feature"
4. Push to your fork — git push origin feat/my-feature
5. Open a Pull Request against main

Please make sure cargo test and cargo clippy -- -D warnings both pass before opening the PR.

Tip: The rust-migration branch tracks ongoing work porting the original Java implementation to Rust. If you're working on interpreter internals, that's a good place to start reading.

Distributed under the MIT License. See LICENSE for the full text.