Abstract Syntax Tree (AST) Nodes

Purpose

The Abstract Syntax Tree (AST) is the internal model of your code. When you write a script, the computer doesn't see it as a single block of text. Instead, the ARES compiler breaks it down into a highly organized tree of "nodes." Each node represents a specific part of your logic, such as a variable, a math calculation, or a loop. This tree is what the compiler uses to understand your intent and transform it into a final program.

Why it exists

Raw text is difficult for a computer to analyze. It doesn't know where one command ends and the next begins just by looking at the characters. The AST exists to solve this problem by providing a clear, hierarchical structure. By turning your code into a tree, the compiler can easily move through your logic, find mistakes, and make optimizations. It provides a single, consistent "blueprint" that all other parts of the compiler (like the optimizer and the emitters) can use to do their work.

How it works

The tree is built from different types of nodes, each with its own purpose.

1. The Root (Program). Every tree starts with a single "Program" node. This is the trunk of the tree that holds all other parts of your script.
2. Branches (Statements). Statements are the main commands in your code. They represent complete actions, like:
   • Read: An input command that gathers data.
   • Print: An output command that shows a result.
   • Use: The "heart" of ARES, where you specify which algorithm to apply to your data.
   • If/While/For: Commands that handle logic decisions and repetition.
3. Leaves (Expressions). Expressions are the "leaves" at the ends of the branches. They represent the values and calculations that make up your statements, such as a number, a variable name, or a math step like $a + b$.
4. The Visitor Pattern. Once the tree is built, the compiler uses a tool called a "visitor" to walk through the nodes. Each visitor is like a specialized inspector that looks at specific parts of the tree to perform tasks like checking types or writing the final code.

Intuition

Think of the AST like a detailed family tree for your code. The "Program" node is the oldest ancestor, and every line of code you write is a descendant. A complex calculation like result = (a + b) * c is like a branch with several generations of children. By looking at the tree, you can immediately see the relationships between all the different parts of the code and how they fit together to form the whole program.

Implementation details

The definition of every node in the ARES language is found in src/parser/ast.ts. Every node follows a standard interface, which includes a type name (like "ReadStmt" or "BinaryExpr") and a method that allows observers (visitors) to visit that node.

• Identifiers: Names for variables and functions are stored as simple Identifier nodes.
• Literals: Raw values like numbers (42) or strings ("Hello") are stored as literal nodes with their values already cleaned up.

Trace example

This is what happens when the system processes if x > 0 { print x }:

1. Creation: The compiler identifies an "if" command and creates an IfStmt node.
2. Condition: It creates a BinaryExpr node for x > 0 and attaches it as the condition child of the "if" node.
3. Body: It creates a PrintStmt node for print x and attaches it as the "then" child of the "if" node.
4. Tree Structure: You now have a small branch where the "if" node connects all these different pieces of logic together.

Related entities

• src/parser/ast.ts: The core file where all node structures are defined.
• 2_language_reference/02_grammar.md: Explains the rules that the compiler follows to turn your text into this tree.