Stone Language — Rust Implementation

A tutorial-oriented scripting language implementation project, based on "Implementing a Script Language in Two Weeks"

What is Stone?

Stone is a concise dynamic scripting language with the following features:

• First-class functions: Functions can be passed, returned, and stored as values
• Closure support: Anonymous functions can capture their defining environment
• Dynamic arrays: Mutable arrays with index access
• Optional type annotations: Variables and parameters can have type annotations (for documentation)
• Complete expressions: Arithmetic, logical, and comparison operators
• Control flow: if-else, while loops

Code Example

// Fibonacci sequence
def fib(n) {
    if n < 2 {
        n
    } else {
        fib(n - 1) + fib(n - 2)
    }
}

fib(10)  // Output: 55

// Closure example
def make_adder(x) {
    fun(y) { x + y }
}

add10 = make_adder(10)
add10(5)  // Output: 15

// Array operations
arr = [1, 2, 3, 4, 5]
sum = 0
i = 0
while i < 5 {
    sum = sum + arr[i]
    i = i + 1
}
sum  // Output: 15

---

Tutorial Navigation

This tutorial uses progressive teaching, building a complete language interpreter from scratch.

📚 Preparation

• Chapter 0: Project Introduction — Background of Stone language and learning objectives

🏗️ Part 1: Basic Framework

• Chapter 1: Project Setup — Set up Cargo workspace and create project skeleton
• Chapter 2: Lexical Analysis — Tokenization using logos
• Chapter 3: AST Definition — Define abstract syntax tree nodes

🔧 Part 2: Parsing

• Chapter 4: Syntax Parsing — Expression and control flow parsing (precedence climbing algorithm)

⚡ Part 3: Execution

• Chapter 5: Evaluator — AST evaluation and environment management
• Chapter 6: Closure Implementation — Function definition, calling, and closure mechanism
• Chapter 7: Array Support — Array literals and index access

🛠️ Part 4: Tools & Integration

• Chapter 8: CLI Tool — Command-line tool and file execution

📖 Appendix

• BNF Grammar Reference — Complete syntax definition of Stone language
• Standard Library Documentation — Built-in functions and native methods
• Implementation Plan — Detailed implementation roadmap

---

Quick Start

Installation

# Clone repository
git clone https://github.com/AlexiaChen/stone-lang-rs.git
cd stone-lang-rs

# Check Rust environment
rustc --version  # Requires 1.70+
cargo --version

# Install CLI tool (choose one of three methods)
# Method 1: Using Makefile (recommended)
make install

# Method 2: Using install script
./install.sh

# Method 3: Using cargo install
cargo install --path stone-cli --force

Build Project

# Build all crates
cargo build --workspace

# Run tests
cargo test --workspace

Run Example Programs

# Using installed stone command
stone examples/01_arithmetic.stone
stone examples/06_closures.stone
stone examples/08_fibonacci.stone

# Or using cargo run
cargo run --release --bin stone -- examples/01_arithmetic.stone

---

Stone CLI Usage Guide

Basic Usage

Stone CLI (stone) is the command-line interpreter for the Stone language, supporting file execution and interactive REPL mode.

Execute Stone Programs

# Execute single file
stone program.stone

# Execute example programs
stone examples/01_arithmetic.stone      # Basic arithmetic operations
stone examples/02_variables.stone       # Variable declaration and assignment
stone examples/03_functions.stone       # Function definition and calling
stone examples/04_conditionals.stone    # Conditional statements if/else
stone examples/05_while.stone           # while loops
stone examples/06_closures.stone        # Closures and anonymous functions
stone examples/07_arrays.stone          # Array operations
stone examples/08_fibonacci.stone       # Fibonacci sequence (recursive)
stone examples/09_factorial.stone       # Factorial calculation
stone examples/10_map_filter.stone      # Higher-order functions
stone examples/11_closure_scope.stone   # Closure scope

REPL Interactive Mode

# Start REPL (interactive interpreter)
stone --repl

# Or run without arguments
stone

In REPL mode:

• Enter Stone code and see results immediately
• Use quit or exit to quit
• Press Ctrl+C to interrupt current input
• Press Ctrl+D to exit REPL

$ stone --repl
Stone REPL v0.1.0
Press Ctrl+D or type 'quit' to exit

>> 1 + 2
=> 3
>> def add(x, y) { x + y }
=> null
>> add(10, 20)
=> 30
>> quit
Goodbye!

Debug Options

# Print token stream (for debugging lexical analysis)
stone --print-tokens examples/01_arithmetic.stone

# Print AST (for debugging syntax parsing)
stone --print-ast examples/03_functions.stone

View Help and Version

# Display help information
stone --help

# Display version number
stone --version

Complete Command-Line Arguments List

Argument	Description
[FILE]	Path to Stone source file (optional)
-r, --repl	Enable REPL mode
--print-ast	Print AST without executing
--print-tokens	Print token stream without executing
-h, --help	Display help information
-V, --version	Display version number

Example Programs Description

File	Description
01_arithmetic.stone	Basic arithmetic operations and operator precedence
02_variables.stone	Variable declaration (var) and assignment
03_functions.stone	Function definition (def) and calling
04_conditionals.stone	if/else conditional statements
05_while.stone	while loops and accumulative summation
06_closures.stone	Closures and anonymous functions (fun)
07_arrays.stone	Array literals and index access
08_fibonacci.stone	Recursive function implementing Fibonacci sequence
09_factorial.stone	Recursive function implementing factorial
10_map_filter.stone	Higher-order functions map/filter simulation
11_closure_scope.stone	Multi-level closures and scope

---

---

Project Architecture

This project uses modular design with Cargo workspace organizing multiple crates:

stone-lang-rs/
├── Cargo.toml              # workspace configuration
├── stone-core/             # Core types (Location, error definitions)
├── stone-lexer/            # Lexer (logos)
├── stone-ast/              # AST node definitions
├── stone-parser/           # Parser (nom)
├── stone-evaluator/        # Interpreter engine
├── stone-cli/              # Command-line tool
├── docs/                   # Tutorial documentation
├── examples/               # Stone example code

Module Dependencies

stone-cli
    ↓
stone-evaluator ──→ stone-ast
    ↓              ↓
stone-parser ──→ stone-core
    ↓
stone-lexer

---

Learning Path

Beginner Path

If you are new to compiler design, it's recommended to follow the tutorial in order:

1. Read Chapter 0 first to understand the project background
2. Follow Chapter 1 to set up the project
3. Implement chapter by chapter, each with complete code examples and tests

Advanced Path

If you already have compiler basics:

1. Quickly browse Architecture Overview
2. Refer to BNF Grammar to understand the syntax

---

Implementation Progress

Stage	Chapter	Content	Status
0	Project Initialization	Workspace setup	✅ Completed
1	Lexical Analysis	Tokenization (logos)	✅ Completed
2	AST Definition	Node type definitions	✅ Completed
3	Syntax Parsing	Expressions and control flow	✅ Completed
4	Evaluator	Environment and evaluation	✅ Completed
5	Closure Implementation	Functions and closures	✅ Completed
6	Array Support	Array literals and indexing	✅ Completed
7	CLI Tool	Command-line interface	✅ Completed

---

Tech Stack

• Rust 2024 Edition — Main implementation language
• logos 0.16 — Lexical analysis library
• nom 7.1 — Parser combinator library
• thiserror 2.0 — Error handling
• clap 4.5 — Command-line argument parsing
• rustyline 14.0 — REPL readline support

---

Resources

Original Materials

• Java Original Implementation — Original Java code from "Implementing a Script Language in Two Weeks"
• Stone Language DeepWiki — AI-generated language documentation

Rust Ecosystem

• nom documentation — Parser combinator library documentation
• logos documentation — Lexer library documentation
• The Nomicon — Rust advanced topics

---

License

MIT License

---

Acknowledgments

• Author of "Implementing a Script Language in Two Weeks"
• All contributors to the original Java implementation of Stone language
• Authors of nom and logos libraries in the Rust community