# Valkyrie AST Builder
This module provides functionality to build strongly-typed Abstract Syntax Trees (AST) from the parsed syntax tree for the Valkyrie programming language.
## Overview
The builder module transforms the generic red-green tree structure produced by the parser into a strongly-typed AST that represents Valkyrie source code. This transformation provides:
- **Type Safety**: Each AST node has a specific type that corresponds to Valkyrie language constructs
- **Error Handling**: Comprehensive error reporting during AST construction
- **Incremental Building**: Support for incremental parsing and AST construction
## Key Components
### Builder Implementation
The `Builder<ValkyrieLanguage>` trait is implemented for `ValkyrieBuilder`, providing the main entry point for AST construction:
```rust,ignore
impl<'config> Builder<ValkyrieLanguage> for ValkyrieBuilder<'config> {
fn build<'a, S: Source + ?Sized>(
&self,
source: &S,
edits: &[TextEdit],
cache: &'a mut impl BuilderCache<ValkyrieLanguage>,
) -> BuildOutput<ValkyrieLanguage>;
}
```
### AST Construction Methods
The builder provides specialized methods for constructing different types of AST nodes:
- `build_root()` - Constructs the root AST node containing all top-level items
- `build_namespace()` - Builds namespace definitions
- `build_micro()` - Builds micro function definitions
- `build_expr()` - Builds various expression types
- `build_stmt()` - Constructs statement nodes
### Error Handling
The builder provides comprehensive error handling with detailed source location information:
- Syntax errors with precise location reporting
- Missing required elements detection
- Unexpected token/node validation
## Usage
The builder is typically used through the `ValkyrieBuilder` when parsing Valkyrie source code:
```rust
use oak_valkyrie::{ValkyrieBuilder, ValkyrieLanguage};
use oak_core::{Builder, parser::ParseSession, source::SourceText};
let language = ValkyrieLanguage::default();
let builder = ValkyrieBuilder::new(&language);
let source = SourceText::new("namespace MyNamespace { micro main() { let x = 42; } }");
let mut cache = ParseSession::default();
let result = builder.build(&source, &[], &mut cache);
match result.result {
Ok(ast) => {
// Work with the strongly-typed AST
println!("Parsed {} items", ast.items.len());
}
Err(error) => {
eprintln!("Parse error: {}", error);
}
}
```
## Valkyrie Language Features
The builder supports all major Valkyrie language constructs:
- **Namespaces**: Organizational units for code
- **Micro Functions**: Functions with parameters and block bodies
- **Expressions**: Identifiers, literals, binary/unary operations, calls, field access, indexing
- **Statements**: Variable bindings (`let`) and expression statements
## Architecture
The builder follows the red-green tree architecture:
1. **Green Tree**: Immutable, structural representation from the parser
2. **Red Tree**: Provides navigation and span information
3. **AST**: Strongly-typed, language-specific representation
This architecture enables efficient incremental parsing and provides excellent performance characteristics for IDE scenarios.