The Abstract Syntax Tree: FLIN's Internal Representation

Between your source code and the running program lives a tree. Every node is a decision. Every branch is a relationship between parts of your program. The Abstract Syntax Tree -- AST -- is the compiler's internal representation of what you wrote, stripped of all the syntactic noise that humans need to read code but machines do not.

Parentheses are gone. Semicolons are gone. Whitespace is gone. What remains is pure structure: this expression is a binary addition of these two sub-expressions. This statement declares a variable with this name and this initial value. This view element has these attributes and these children. The AST captures the meaning of the program, not its formatting.

FLIN's AST has an unusual challenge. Most programming languages have one kind of thing: code. FLIN has three: imperative code (variables, control flow, operations), declarative data (entity definitions with typed fields), and reactive views (HTML-like templates with embedded expressions). The AST must represent all three uniformly enough for the type checker and code generator to process them, while preserving enough domain-specific structure for each to retain its semantics.

This article examines how we designed FLIN's AST, what nodes it contains, and the trade-offs we made along the way.

---

The Top Level: Programs and Statements

A FLIN program is a sequence of statements. There is no main function, no module header, no boilerplate. You open a .flin file, write statements, and the compiler processes them top to bottom.

The AST represents this with two types:

pub struct Program {
    pub statements: Vec<Stmt>,
}

pub enum Stmt { VarDecl { name: String, type_annotation: Option, initializer: Expr, span: Span, }, EntityDecl { name: String, fields: Vec, span: Span, }, Save { expr: Expr, span: Span, }, Delete { expr: Expr, where_clause: Option, span: Span, }, If { condition: Expr, then_body: Vec, else_body: Option>, span: Span, }, For { variable: String, index: Option, iterable: Expr, body: Vec, span: Span, }, Route { method: HttpMethod, path: String, body: Vec, span: Span, }, ExprStmt { expr: Expr, span: Span, }, ViewElement(ViewNode), } ```

Every statement variant carries a span -- the source location where it was parsed. This span propagates through the entire compilation pipeline: if the type checker finds an error in a variable declaration, it reports the span of that declaration, not a generic "somewhere in the file." If the code generator emits bytecode for a save statement, it records the span in the line-number table so that runtime errors can point back to the source.

---

Variable Declarations

The simplest statement is also the most common:

count = 0
name: text = "Juste"

Both produce Stmt::VarDecl nodes. The first has type_annotation: None -- the type will be inferred by the type checker. The second has type_annotation: Some(FlinType::Text) -- the developer has explicitly stated the type.

This optional annotation is a key design decision. FLIN's philosophy is "types you rarely write, safety you always get." The type checker will infer count as int from the literal 0. But when inference would be ambiguous (an empty list, a number that could be int or float), the developer can add an explicit annotation. The AST preserves both forms without preference, letting the type checker decide how to handle each case.

---

Entity Declarations

Entities are FLIN's data model. They are not classes, not structs, not tables -- they are all three at once. An entity declaration defines a persistent data type with typed fields, optional default values, and automatic versioning.

entity Todo {
    title: text
    done: bool = false
    created: time = now
}

The AST represents this as:

pub struct FieldDecl {
    pub name: String,
    pub field_type: FlinType,
    pub default: Option<Expr>,
    pub span: Span,
}

Each field has a mandatory type annotation (unlike variables, where annotation is optional). The default is an expression, not a value -- now is a keyword that evaluates to the current timestamp at the moment the entity is created. The AST preserves it as an Expr::Keyword(Keyword::Now) node, which the code generator will emit as a LoadNow bytecode instruction.

Entity declarations are pure data at the AST level. They do not generate control flow or expressions. The code generator handles them by registering the entity schema in a lookup table, so that subsequent save, delete, and find operations know the entity's structure.

---

Expression Nodes

Expressions are the core of any programming language, and FLIN's expression enum is the largest type in the AST:

pub enum Expr {
    // Literals
    Literal(LiteralValue),
    Identifier(String),
    List(Vec<Expr>),
    Map(Vec<(Expr, Expr)>),

// Operations Binary { left: Box, op: BinOp, right: Box }, Unary { op: UnaryOp, operand: Box }, Assign { target: Box, value: Box },

// Access Member { object: Box, field: String }, Index { object: Box, index: Box }, Call { callee: Box, args: Vec }, MethodCall { object: Box, method: String, args: Vec },

// FLIN-specific EntityConstruct { name: String, fields: Vec<(String, Expr)> }, Ask { query: Box }, Search { query: Box, entity: String, field: String, limit: Option> }, Temporal { expr: Box, time: Box }, Match { subject: Box, arms: Vec },

// View (embedded in expressions when used inside views) ViewInterpolation(Box), } ```

Several aspects of this design are worth examining.

Box everywhere. Recursive types in Rust require heap allocation through Box, because the compiler needs to know the size of every type at compile time. A Binary expression contains two sub-expressions, each of which could themselves be Binary. Without Box, the type would have infinite size. This is not a performance concern -- the allocator cost of boxing a few hundred expression nodes is negligible compared to the work the type checker and code generator will do with them.

FLIN-specific variants. EntityConstruct, Ask, Search, and Temporal are not found in general-purpose language ASTs. They encode FLIN's domain-specific semantics directly in the tree structure. An Ask node does not desugar to a function call -- it is a first-class concept that the type checker validates (the query must be a text expression) and the code generator emits as a dedicated Ask bytecode instruction.

No parentheses, no precedence. The tree structure encodes precedence implicitly. The expression 2 + 3 * 4 is represented as Binary(Literal(2), Add, Binary(Literal(3), Mul, Literal(4))) -- the multiplication is a child of the addition, so it evaluates first. The parser did the work of encoding precedence into the tree structure; the AST does not need to record it separately.

---

View Nodes

FLIN's view layer is where the AST departs most dramatically from traditional language ASTs. A view node represents an HTML-like element with attributes, event handlers, and children:

pub struct ViewNode {
    pub tag: String,
    pub attributes: Vec<ViewAttribute>,
    pub children: Vec<ViewChild>,
    pub span: Span,
}

pub enum ViewAttribute { Static { name: String, value: String }, Dynamic { name: String, expr: Expr }, EventHandler { event: String, handler: Expr }, }

pub enum ViewChild { Element(ViewNode), Text(String), Expression(Expr), If { condition: Expr, then_children: Vec, else_children: Option> }, For { variable: String, index: Option, iterable: Expr, children: Vec }, } ```

Consider this FLIN code:

<button class="primary" click={count++}>
    {count}
</button>

The AST representation:

• ViewNode with tag "button"
• - ViewAttribute::Static { name: "class", value: "primary" }
• - ViewAttribute::EventHandler { event: "click", handler: Expr::Unary(PostIncrement, Identifier("count")) }
• - ViewChild::Expression(Expr::Identifier("count"))

The view node structure mirrors the HTML structure, but with FLIN expressions embedded at every point where dynamic behavior occurs. Static attributes are strings. Dynamic attributes contain expressions. Event handlers contain expressions. Child content can be static text, nested elements, interpolated expressions, or conditional/loop constructs.

This design means the type checker can validate view expressions the same way it validates code expressions: count++ in an event handler is type-checked exactly like count++ in a code block. The code generator handles the view-specific aspects (creating DOM elements, binding handlers, setting up reactivity) while delegating expression emission to the same methods it uses for code.

---

The Type Representation

Every expression in the AST will eventually have a type, determined by the type checker. But the AST itself does not carry type information -- it represents the program as the developer wrote it, before any analysis. Types appear in the AST only when the developer explicitly wrote them:

pub enum FlinType {
    Text,
    Int,
    Float,
    Bool,
    Time,
    File,
    Money,
    Semantic(Box<FlinType>),  // semantic text
    List(Box<FlinType>),       // [text]
    Optional(Box<FlinType>),   // text?
    Entity(String),            // User, Todo
    Any,                       // Used internally
    TypeVar(u32),              // Used by type inference
}

The Semantic, List, and Optional variants are type constructors -- they take an inner type and produce a new type. semantic text is a Semantic(Box(Text)). [int] is a List(Box(Int)). text? is an Optional(Box(Text)).

The TypeVar(u32) variant does not appear in the parsed AST. It is created by the type inference algorithm (Hindley-Milner, covered in the next article) to represent unknown types that will be resolved through unification. The fact that it lives in the same enum as concrete types means the type checker can mix known and unknown types freely, without wrapper types or special cases.

---

Design Decisions and Trade-offs

Untyped AST vs. typed AST. Some compilers use a single AST type that accumulates type information as analysis proceeds. Others use two separate types: an untyped AST produced by the parser and a typed AST produced by the type checker. We chose the single-AST approach, where the type checker annotates the existing AST rather than producing a new one. This reduces code duplication (no parallel type hierarchies) at the cost of type safety (the type checker must trust that types are populated before the code generator reads them). For a two-person team, less code wins.

Spans on every node. Carrying a Span on every statement and expression node costs 16 bytes per node (two Position values of 12 bytes each, minus padding). For a typical FLIN program with a few hundred AST nodes, that is a few kilobytes -- completely negligible. The benefit is that every compiler error, every type error, every code generation warning can point to the exact source location. We never had to debug a "where did this error come from?" problem.

Flat children vs. recursive nesting. View children are stored as Vec rather than as a recursive tree. This means a

fn emit_stmt(&mut self, stmt: &Stmt) -> Result<(), CodeGenError> {
    match stmt {
        Stmt::VarDecl { name, initializer, .. } => {
            self.emit_expr(initializer)?;
            self.define_variable(name);
            Ok(())
        }
        Stmt::EntityDecl { name, fields, .. } => {
            self.register_entity(name, fields);
            Ok(())
        }
        Stmt::If { condition, then_body, else_body, .. } => {
            self.emit_if(condition, then_body, else_body.as_deref())
        }
        Stmt::For { variable, index, iterable, body, .. } => {
            self.emit_for(variable, index.as_deref(), iterable, body)
        }
        Stmt::Save { expr, .. } => {
            self.emit_expr(expr)?;
            self.emit_opcode(OpCode::Save);
            Ok(())
        }
        // ... other variants
    }
}

count = 0
<button click={count++}>{count}</button>

Program
  Stmt::VarDecl
    name: "count"
    type_annotation: None
    initializer: Expr::Literal(Integer(0))
  Stmt::ViewElement
    ViewNode
      tag: "button"
      attributes:
        EventHandler
          event: "click"
          handler: Expr::Unary(PostIncrement, Identifier("count"))
      children:
        ViewChild::Expression(Expr::Identifier("count"))