elm-ast

Inspired by syn, elm-ast is a Rust library for parsing and constructing Elm 0.19.1 ASTs.

Overview

elm-ast provides a complete, strongly-typed representation of Elm source code as a Rust AST, along with a parser, printer, and visitor/fold traits for traversal and transformation. It is modeled after Rust's syn crate, with a formatting approach inspired by elm-format.

Tested against 291 real-world .elm files from 50 packages (including elm/core, elm/browser, rtfeldman/elm-css, mdgriffith/elm-ui, dillonkearns/elm-markdown, folkertdev/elm-flate, elm-explorations/test) with 100% parse, round-trip, and printer idempotency rates.

Quick start

Add the crate to your project:

cargo add elm-ast

Or add it to Cargo.toml directly:

[dependencies]
elm-ast = "0.2"

Then:

use elm_ast::{parse, print};

let source = r#"
module Main exposing (..)

add : Int -> Int -> Int
add x y = x + y
"#;

// Parse
let module = parse(source)?;

// Inspect
println!("{} declarations", module.declarations.len());

// Print back to valid Elm
let output = print(&module);

Features

All features are enabled by default via full. Disable default-features and pick what you need to reduce compile times.

[dependencies]
elm-ast = "0.2"

Minimal dependency (AST types only)

[dependencies]
elm-ast = { version = "0.2", default-features = false }

AST types

Every Elm 0.19.1 syntax construct has a corresponding Rust type:

All nodes carry source location information via Spanned<T>.

Parsing

use elm_ast::parse;

// Strict: fails on first error
let module = parse(source)?;

// Recovering: returns partial AST + all errors
let (maybe_module, errors) = elm_ast::parse_recovering(source);

Printing

Three printer modes are available, trading off between minimal-change output and full elm-format agreement:

use elm_ast::{parse, print, pretty_print, pretty_print_converged};

let module = parse(source)?;

let compact   = print(&module);                    // Compact: minimal breaking
let formatted = pretty_print(&module);             // ElmFormat: elm-format style
let stable    = pretty_print_converged(&module);   // ElmFormatConverged: stable under re-formatting

// Or use Display for Compact output:
println!("{module}");

For custom indent width or reusable printers, construct one explicitly:

use elm_ast::print::{PrintConfig, PrintStyle, Printer};

let output = Printer::new(PrintConfig {
    indent_width: 2,
    style: PrintStyle::ElmFormat,
}).print_module(&module);

See docs/printing.md for the full breakdown of each mode, idempotency guarantees, and when to pick which.

Comment preservation

Top-level comments (line comments -- and block comments {- -} between declarations) are captured during parsing and round-tripped through the printer. Comments are placed immediately before the declaration they precede.

Comments inside let/in blocks and case/of branches are attached to their respective AST nodes and round-trip correctly. Doc comments ({-| -}) are attached to their declarations and always round-trip correctly.

Visitors

use elm_ast::visit::{Visit, walk_expr};
use elm_ast::expr::Expr;
use elm_ast::node::Spanned;

struct FunctionCallCounter(usize);

impl Visit for FunctionCallCounter {
    fn visit_expr(&mut self, expr: &Spanned<Expr>) {
        if matches!(&expr.value, Expr::Application(_)) {
            self.0 += 1;
        }
        walk_expr(self, expr);
    }
}

let mut counter = FunctionCallCounter(0);
counter.visit_module(&module);
println!("{} function calls", counter.0);

Three traversal traits:

• Visit: immutable traversal (& references)
• VisitMut: in-place mutation (&mut references)
• Fold: owned transformation (takes ownership, returns new tree)

Builder API

Construct AST nodes programmatically (with dummy spans):

use elm_ast::builder::*;

let m = module(
    vec!["Main"],
    vec![
        func("add", vec![pvar("x"), pvar("y")],
            binop("+", var("x"), var("y"))),
    ],
);

println!("{m}"); // prints valid Elm

Serde

With the serde feature, all AST types support JSON serialization:

let module = elm_ast::parse(source)?;
let json = serde_json::to_string_pretty(&module)?;
let module2: elm_ast::ElmModule = serde_json::from_str(&json)?;

Architecture

For the full story, see the ARCHITECTURE.md doc.

The design follows syn's proven patterns:

• Enum-of-structs AST: each variant wraps a dedicated struct with named fields
• Spanned<T>: every node carries a Span (byte offset + line/column)
• Box<T> for recursive sub-expressions
• Feature-gated modules for compile-time control

The printer uses an approach inspired by elm-format: eagerly detect whether sub-expressions are multi-line, then switch containers to vertical layout when any child is multi-line.

Fully iterative expression parser

The expression parser uses zero stack recursion. Traditional recursive-descent parsers can overflow the call stack on deeply nested input. elm-ast eliminates this entirely through three techniques:

1. Iterative Pratt parsing: binary operators use an explicit Vec<PendingOp> heap-allocated operator stack instead of recursive descent through precedence levels.
2. CPS (continuation-passing style): every compound expression (if/case/let/lambda/paren/tuple/list/record) that would normally call parse_expr recursively instead returns a NeedExpr(continuation) step, where the continuation is a closure capturing the partial parse state.
3. Trampoline loop: a top-level loop drives execution: when a compound form needs a sub-expression, its continuation is pushed onto a heap-allocated stack and the loop restarts. When a sub-expression completes, the continuation is popped and invoked.

This guarantees O(1) call-stack depth regardless of expression nesting. The continuation stack is bounded by MAX_EXPR_DEPTH (256) as a resource guard, not a safety requirement.

None of this was actually necessary. A simple depth limit would have sufficed, but it was fun to build, and, most importantly, it is thoroughly tested and works.

Test coverage

381 tests across lexer, parser, printer, visitors, property-based checks, and 291 real-world files from 50 packages. See TEST_COVERAGE.md for the full breakdown.

License

Dual licensed under Apache 2.0 or MIT.