SpellScript - A Wizard-Themed Programming Language

A magical programming language built with ANTLR4, where syntax is based on wizard vocabulary.

Language Features

Data Types

• Numbers (tome): 42, 3.14
• Strings (scroll): "hello world"
• Booleans: truth, falsehood

Syntax

Feature	Syntax	Example
Variables	brew name = value;	brew power = 42;
Functions	cast name(params) { ... }	cast amplify(n) { reveal n * 2; }
If/Else	divine (cond) { ... } otherwise { ... }	divine (x > 0) { speak "positive"; }
While Loop	chant (cond) { ... }	chant (i < 5) { ... }
For Loop	enchant (init; cond; step) { ... }	enchant (i = 0; i < 5; i = i + 1) { ... }
Output	speak expr;	speak "hello";
Return	reveal expr;	reveal x * 2;

Operators

• Arithmetic: + - * /
• Logical: and or not
• Comparison: < <= > >= == !=

Example Programs

Basic Example (samples/example.spell)

brew power = 42;

cast amplify(n) {
    reveal n * 2;
}

divine (power > 10) {
    speak "The spell is mighty!";
} otherwise {
    speak "The spell is weak.";
}

brew i = 0;
chant (i < 5) {
    speak amplify(i);
    brew i = i + 1;
}

Output:

The spell is mighty!
0
2
4
6
8

Factorial (samples/functions.spell)

cast factorial(n) {
    divine (n <= 1) {
        reveal 1;
    } otherwise {
        reveal n * factorial(n - 1);
    }
}

speak factorial(5);

Output: 120

Basic Operations (samples/basic.spell)

brew x = 10;
brew y = 20;
speak x + y;

speak "hello" + " " + "world";

brew flag = truth;
divine (flag) {
    speak "flag is true";
}

Output:

30
hello world
flag is true

Project Structure

SpellScript/
├── grammar/
│   └── SpellScript.g4           # ANTLR4 grammar definition
├── src/
│   ├── SpellScript.java         # Main interpreter
│   ├── SpellScriptLexer.java    # Generated lexer
│   ├── SpellScriptParser.java   # Generated parser
│   ├── SpellScriptVisitor.java  # Generated visitor
│   └── SpellScriptBaseVisitor.java # Generated base
├── samples/
│   ├── example.spell            # Main demo
│   ├── basic.spell              # Basic operations
│   └── functions.spell          # Recursion example
├── build.sh                     # Build script
└── README.md                    # This file

Building & Running

Prerequisites

• Java JDK 11+ (for compilation)
• Java Runtime (for execution)
• ANTLR4 JAR (included in .local/lib/)

Build

./build.sh

Run a Program

./build.sh samples/example.spell

Grammar Overview

The ANTLR4 grammar (grammar/SpellScript.g4) defines:

• Lexer: Keywords, operators, identifiers, numbers, strings, comments
• Parser: Program structure, statements, expressions with proper precedence
• Visitor: Tree-walking interpreter for execution

Key rules:

• program: Sequence of statements
• statement: Variable declaration, function definition, conditionals, loops, expressions
• expr: Binary/unary operations with correct operator precedence
• primary: Literals, identifiers, function calls, parenthesized expressions

Implementation Details

The interpreter uses the visitor pattern to traverse the ANTLR parse tree:

1. Lexer tokenizes the input (SpellScriptLexer.java)
2. Parser builds parse tree (SpellScriptParser.java)
3. Interpreter visits nodes and evaluates (SpellScript.java)
   • Maintains variable and function symbol tables
   • Handles function calls with local scope
   • Implements return values with flag-based control flow

Error Handling

The interpreter provides meaningful error messages for:

• Undefined variables: error: variable 'x' not brewed
• Undefined functions: error: function 'foo' not cast
• Type errors: error: cannot convert to number
• Division by zero: error: divide by zero
• Syntax errors from ANTLR parser

Testing

Run sample programs to verify all features:

./build.sh samples/example.spell     # All features
./build.sh samples/basic.spell       # Variables, operators
./build.sh samples/functions.spell   # Recursion

---

Created for Programming Languages course assignment