Abstract Syntax Tree (sploosh-ast)
Relevant source files
The following files were used as context for generating this wiki page:
The sploosh-ast crate defines the core typed Abstract Syntax Tree (AST) for the Sploosh programming language. It serves as the shared data model between the frontend parser and later stages of the compiler pipeline, such as semantic analysis and code generation. The AST is designed to preserve source metadata, including attribute information and source spans, which are critical for providing high-quality diagnostics for both human developers and AI agents.
Sources: crates/sploosh-ast/src/lib.rs, README.md:102-105
Architecture and Data Structures
The AST is organized into a hierarchy of types that represent the structure of a Sploosh program. A Program consists of a sequence of Item nodes, each representing a top-level declaration such as a function, struct, or actor.
Metadata and Spans
Every significant node in the AST is wrapped in a structure that includes a Span. This Span tracks the byte offsets of the node in the original source code, facilitating error reporting and source-mapped debugging.
Core Language Items
Sploosh items represent the major building blocks of the language. The ItemKind enum categorizes these declarations.
| Item Type | Description |
|---|---|
Function | A named unit of execution, potentially async or offchain. |
Struct | A named product type with typed fields. |
Enum | A sum type with multiple variants (unit, tuple, or struct-like). |
Actor | An isolated concurrency unit with private state and mailbox handlers. |
OnchainModule | A module restricted to blockchain-specific targets (EVM/SVM). |
ExternBlock | Declarations of external functions (e.g., C FFI or on-chain calls). |
Sources: crates/sploosh-ast/src/lib.rs:36-80, crates/sploosh-parser/src/lib.rs:72-97
Actor and On-chain Structures
Actors are first-class citizens in the Sploosh AST, containing both state fields and handlers. OnchainModule nodes represent specialized modules where specific prohibitions (e.g., no floating point, no host I/O) are enforced.
Expressions and Patterns
The AST represents executable logic through an recursive Expr tree. The ExprKind enum covers literals, binary/unary operations, control flow, and specialized Sploosh features like the pipe operator.
Pipeline Desugaring
The pipe operator (|>) is represented as a BinaryOp::Pipe in the AST. The parser handles the specific side conditions of pipe stages, such as the error propagation operator (?) applying to the accumulated result.
Destructuring Patterns
The Pattern tree is used primarily in match expressions. It supports various destructuring forms, including:
- Wildcards:
_ - Bindings:
nameorref name - Destructuring: Tuple, Path (variants), and Struct patterns.
- Or-patterns:
A | B
Sources: crates/sploosh-ast/src/lib.rs:194-260, crates/sploosh-parser/src/lib.rs:520-565
Type System Representation
The AST provides a comprehensive representation of Sploosh's static type system, including support for generics and trait references.
| Type Node | AST Representation |
|---|---|
Primitive | Core types like i64, u256, bool, Address. |
Path | User-defined types or namespaced identifiers (e.g., std::Result). |
Reference | Borrowed types, optionally mut. |
Array / Slice | Fixed-size or dynamically sized sequences. |
Function | First-class function types. |
Dyn | Dynamic dispatch via trait objects (e.g., dyn Trait). |
Sources: crates/sploosh-ast/src/lib.rs:142-175, crates/sploosh-parser/src/lib.rs:308-348
Implementation Notes
The sploosh-ast crate is designed to be lightweight and dependency-free to facilitate fast compilation of the compiler frontend.
The flow shows how sploosh-ast acts as the terminal data structure for the parsing phase.
Sources: crates/AGENTS.md:1-20, Cargo.toml:1-10
Crate Dependencies
[package]
name = "sploosh-ast"
version = "0.1.0"
edition.workspace = true
[lib]
path = "src/lib.rs"
Sources: crates/sploosh-ast/Cargo.toml:1-10
The AST is currently in a "bootstrap" phase, where certain complex bounds (like those in where clauses) are parsed for validation but not yet stored in the permanent tree nodes.
Sources: crates/AGENTS.md:30-50