javascript-interpreter 0.1.0

A lightweight JavaScript interpreter implemented in Python.

JavaScript Interpreter

A lightweight JavaScript interpreter implemented in Python.

This project reads JavaScript-style source code, turns it into tokens, builds an Abstract Syntax Tree (AST), and evaluates that AST step by step inside a runtime environment.

What This Interpreter Does

• Parses JavaScript-like source code
• Evaluates expressions, variables, and function calls
• Supports control flow: if, while, do...while, for, break, continue, return
• Supports let, const, and var declarations
• Handles arrays, objects, string values, numbers, booleans, null, and undefined
• Provides built-in APIs: console.log, Math, and Date
• Offers an interactive REPL with debug helpers

How It Works: Input to Output

1. Source code is loaded from a file or typed into the REPL.
2. lexer.py reads the characters and converts them into a stream of tokens.
   • Example token types: IDENTIFIER, NUMBER, STRING, PLUS, LPAREN, SEMICOLON
3. parser.py uses a Pratt parser to convert tokens into an AST.
   • The AST is a tree structure representing the program.
   • Example nodes: Program, VariableStatement, InfixExpression, FunctionDeclaration, CallExpression
4. evaluator.py walks the AST and executes each node.
   • Expressions are evaluated, statements are executed, and values are returned.
   • A runtime environment keeps track of variables, scopes, and functions.
5. environment.py manages scope chains and variable lookup.
   • Global scope is created first, then nested scopes are built for blocks and functions.
6. Output is printed to the console, either from console.log or the REPL response.

Example: let x = 10; console.log(x + 5);

• Lexer converts source into tokens: LET, IDENTIFIER(x), ASSIGN, NUMBER(10), SEMICOLON, ...
• Parser builds an AST representing a variable declaration and a call to console.log
• Evaluator declares x and computes x + 5
• console.log prints 15 to stdout

Requirements

• Python 3.8 or newer

Run the Interpreter

Start the REPL

python main.py

Once running, type JavaScript expressions and statements directly.

Run a JavaScript File

python main.py test.js

REPL Example

$ python main.py
   ___       _   _                    _ _
  / _ \_ __ | |_(_) __ _ _ __ __ ___ (_) |_ _   _
 / /_\/ '_ \| __| |/ _` | '__/ _` \ \ / / __| | | |
/ /_\\| |_) | |_| | (_| | | | (_| |\ V /| |_| |_| |
\____/| .__/ \__|_|\__, |_|  \__,_| \_/  \__|\__, |
      |_|          |___/                     |___/
  JavaScript Interpreter (Python implementation)
  Type code to evaluate. Commands:
    .exit / .quit : Exit the shell
    .tokens     : Toggle token stream visualization
    .ast        : Toggle AST tree visualization
    .env        : Print active global scope bindings

js> let x = 5;
js> let y = 7;
js> function add(a, b) { return a + b; }
js> console.log(add(x, y));
12
js> .env
--- Active Scope Bindings ---
  this : [object Object]
  console : [object Object]
  Math : [object Object]
  Date : [object Function]
  x : 5
  y : 7
---
js> .exit
Goodbye!

Example JavaScript File

Create test.js with:

let greeting = "Hello";
let name = "World";

function joinWords(a, b) {
  return a + ", " + b + "!";
}

console.log(joinWords(greeting, name));

Run it:

python main.py test.js

Expected output:

Hello, World!

REPL Debug Helpers

• .tokens — show the current input as a token stream
• .ast — show the current input parsed into an AST tree
• .env — show global scope bindings and values

Project Files

• main.py — entry point for REPL or file execution
• repl.py — interactive shell and helper commands
• lexer.py — tokenizes the source text
• parser.py — builds the AST using Pratt parsing
• ast_nodes.py — AST node definitions and syntax structures
• evaluator.py — executes the AST and manages runtime semantics
• environment.py — scope chain and variable lookup logic
• values.py — JavaScript value wrappers, coercion, and object models
• test_interpreter.py — interpreter test cases
• test.js — sample JavaScript script

Notes & Limitations

• This interpreter is a learning implementation, not a full JavaScript engine.
• It does not implement the full ECMAScript standard.
• Some JavaScript edge cases and built-in APIs are simplified or missing.
• Use it to explore parsing, AST evaluation, and interpreter design.