Warning! This documentation is for contributors who wish to help out the project.

It details how the project itself works, not how to write code in it. If you would like to know how to write code in Spindle, please look at the user documentation!
With that out of the way, this document will lay out how Spindle works and will help you contribute to it.
If you want a high-level overview of how Spindle works, you're in just the right place!

Spindle: From Code to Execution

This explanation dives into how Spindle, a programming language, works behind the scenes, transforming your code into a running program. It's important to note that this explanation is geared towards developers contributing to Spindle, not for users writing Spindle code.

The Grand Tour:

Spindle's journey from code to execution involves several key stages:

1. The Warm-Up: Semi-Parsing (Not User-Facing)

   • Skipping the Front-End: Spindle can run code directly or through a front-end file (shell.py). This documentation focuses on the direct execution path.
   • RUN("") Command: Spindle checks for a RUN("") command at the beginning. This is not part of the Spindle language itself but helps the desktop experience. It specifies the file to run.
   • Standardizing IF Statements: Spindle automatically adds ELSE{} to any IF statements missing an ELSE block. This prevents program crashes caused by incomplete IF statements.
   • Function Isolation: If your code contains functions, the semi-parser splits the code into separate chunks, isolating each function definition. This allows Spindle to process each function independently.

2. Step 1: The Lexer - Turning Text into Tokens

   • Character by Character: The lexer scans your code character by character, ignoring whitespace (tabs and spaces) but keeping track of newlines.
   • Creating Tokens: It breaks down your code into smaller, meaningful units called tokens. These tokens represent keywords, identifiers (variable names), operators (like + or -), and literals (like numbers or strings).
   • Error Checking: The lexer performs basic checks to ensure proper syntax for simple elements.

3. Step 2: The Parser - Adding Meaning to Tokens

   • Understanding the Structure: The parser takes the tokens generated by the lexer and analyzes them to understand the overall structure of your code. It recognizes different statements like IF, FOR, and expressions.
   • Syntax Enforcement: The parser rigorously checks for syntax errors. This is where most syntax errors are detected during the Spindle execution process.
   • Building the Logic: The parser essentially translates the token sequence into instructions for the interpreter. It tells Spindle how to handle different constructs like expressions, loops, and function calls.

4. Step 3: The Interpreter - From Meaning to Results

   • Abstract Syntax Tree (AST): The interpreter doesn't directly work with the token list. Instead, the parser creates an AST, a tree-like structure that represents the program's syntactic structure.
   • Executing the Program: The interpreter navigates the AST, following the program's logic and performing the necessary actions. For example, it runs loops, evaluates expressions, and calls functions.
   • Returning the Result: Upon successful execution, the interpreter returns the program's result. If the program runs without explicitly returning anything, it returns null. This null value is filtered out during presentation.

Understanding the Process:

This breakdown helps visualize how Spindle transforms your code. Each stage builds upon the last, ultimately resulting in a running program. If you're interested in contributing to Spindle's development, understanding these steps is crucial for working with the interpreter and parser logic.