ShardJS

A minimal JavaScript-like runtime written in C

ShardJS supports basic arithmetic, variables, and expression evaluation through a clean interpreter pipeline.

⚠️ WARNING: This is an experimental runtime for educational purposes only. The project is under active development and in very early stages. Not intended for production use.

Features

• Numbers: Double-precision floating point arithmetic
• Variables: let declarations with assignment
• Arithmetic Operators: +, -, *, / with proper precedence
• Comparison Operators: >, <, >=, <=, ==, != returning boolean values (1 for true, 0 for false)
• Control Flow: if and if-else statements for conditional execution
• Parentheses: Expression grouping support
• Print function: Built-in print() for output

Quick Start

# build the interpreter
make

# run a script
./bin/shardjs script.js

Example Script

let x = 10;
let y = 5;
let result = (x + y) * 2;
print(result); // outputs: 30

// Comparison operators
print(x > y);        // outputs: 1 (true)
print(x == 10);      // outputs: 1 (true)
print(y != 3);       // outputs: 1 (true)
print((x + y) >= 15); // outputs: 1 (true)

// Control flow with if/else
if (x > y) print(42);           // outputs: 42
if (y > x) print(1) else print(2); // outputs: 2

// Conditional variable declarations
if (x == 10) let message = 100;
if (message == 100) print(message); // outputs: 100

Architecture

ShardJS follows a traditional interpreter pipeline:

Source Code → Lexer → Parser → AST → Interpreter → Output

Pipeline Flow

1. Lexer - Tokenizes source code character by character
2. Parser - Builds Abstract Syntax Tree using recursive descent
3. AST - Represents program structure in memory
4. Interpreter - Executes AST nodes and manages variables

Core Components

shardjs/
├── main.c          # entry point and orchestration
├── lexer.c         # tokenization logic
├── parser.c        # recursive descent parser
├── ast.c           # AST node management
├── env.c           # variable environment
├── interpreter.c   # AST execution engine
└── include/
    ├── token.h     # token definitions
    └── runtime.h   # core data structures

Language Grammar

program     → statement*
statement   → letDecl | printCall | ifStmt | expression
letDecl     → "let" IDENTIFIER "=" expression ";"
printCall   → "print" "(" expression ")" ";"
ifStmt      → "if" "(" expression ")" statement ( "else" statement )?
expression  → comparison
comparison  → term ( ( ">" | "<" | ">=" | "<=" | "==" | "!=" ) term )*
term        → factor ( ( "*" | "/" ) factor )*
factor      → NUMBER | IDENTIFIER | "(" expression ")"

Operator Precedence (highest to lowest)

1. Parentheses ()
2. Numbers and identifiers
3. Multiplication and division *, /
4. Addition and subtraction +, -
5. Comparison operators >, <, >=, <=, ==, !=

Boolean Values

Comparison operators return numeric boolean values:

• 1.0 represents true
• 0.0 represents false

This allows boolean results to be used in arithmetic expressions and stored in variables.

Control Flow

If statements evaluate conditions using the same boolean logic:

• Non-zero values (including 1.0) are treated as true
• Zero (0.0) is treated as false

if (1) print(42);        // executes: 1 is true
if (0) print(42);        // skips: 0 is false
if (5 > 3) print(42);    // executes: comparison returns 1 (true)
if (2 == 3) print(42) else print(99); // executes else: comparison returns 0 (false)

Memory Management

• All components handle their own memory allocation/deallocation
• AST nodes are freed recursively after interpretation
• Environment cleanup handles variable storage
• No external dependencies beyond standard C library

Building

Requirements:

• GCC or Clang compiler
• Make build system
• Standard C library

# compile with warnings enabled
make

# run tests
make test

# clean build artifacts
make clean

Error Handling

ShardJS provides clear error messages for:

• Lexical errors: Invalid characters with line/column info
• Parse errors: Syntax issues with expected vs actual tokens
• Runtime errors: Undefined variables, division by zero

Testing

The project includes comprehensive tests:

• Unit tests for each component
• Integration tests for complete pipeline
• Memory leak detection support
• Error condition validation

Run tests with make test to verify functionality.

🤝 Contributing

I welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Quick Start:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

☕ Support

If you find ShardJS helpful, consider supporting the project: