#YumeXi/nanocake

#Architecture

                   ┌─────────────┐
#nanopass.language │ meta_parser │  parse annotations, resolve extends chains,
                   └──────┬──────┘  apply #nano.remove, resolve entries/.mbti
                          │ NanoLangDef[]
                          ▼
                   ┌─────────────┐
                   │  language   │  expand inheritance -> a layout, then
                   └──────┬──────┘  generate the unified Tree + wrappers
                          │ GeneratedLanguageLayout
              ┌───────────┼───────────┐
              ▼                       ▼
     ┌─────────────┐          ┌─────────────┐
     │unparser/gen │          │    pass     │  transform/fold scaffolding,
     └──────┬──────┘          └─────────────┘  smart constructors, PassM
            │ from_sexp / to_sexp_doc
            ▼
     ┌─────────────┐
     │unparser/sexp│  S-expression runtime: parse, doc render, form matching
     └─────────────┘

• meta_parser — Parses #nanopass.language / #nanopass.nonterminal and #nano.* annotations from source files. Resolves language definitions, extends chains, #nano.remove deletions, effective entries, and .mbti interfaces.
• language — Expands each language against its parent (inheritance, override, and #nano.remove) into a GeneratedLanguageLayout, then generates the AST scaffolding: unified syntax trees, per-language wrappers, extension enums, and terminal aliases.
• unparser/sexp — S-expression runtime shared by generated code: a parser, a pretty-printing document model, #nano.form pattern matching, and layered parse/decode/hook errors.
• unparser/gen — Generates concrete from_sexp / to_sexp_doc / parse_sexp / unparse_sexp codecs from a language's layout, honoring custom surface syntax and hooks.
• pass — Transformation-pass scaffolding built on the layout (smart constructors, catamorphisms, delayed-subtree rewrites, and the effectful PassM pipeline). See pass/README.mbt.md.

#Quick Start

#1. Define languages

///|
pub type LambdaVar = String

///|
#nanopasslanguage(name="Lambda")
pub(all) enum Expr {
  Int(Int)
  LambdaVar(LambdaVar)
  Lam(LambdaVar, Expr)
  App(Expr, Expr)
}

///|
#nanopasslanguage(name="SimplyTypedLambda", extends="Lambda")
enum TypedExpr {
  True
  False
  Int(Int)
  LambdaVar(LambdaVar)
  If(cond~ : TypedExpr, TypedExpr, TypedExpr)
  Lam(LambdaVar, Type, TypedExpr)
  App(TypedExpr, TypedExpr)
}

  #nanoform("(lambda ($0 : $1) $2)")
  #nanoform_only
  Lam(LambdaVar, Type, TypedExpr)

  #nanoinline           // renders as ($0 $1) — no constructor head
  App(TypedExpr, TypedExpr)

#nanopasslanguage(name="NoApp", extends="Lambda")
#nanoremove("App")
enum NoAppExpr {
  // only Lam, Int, LambdaVar are inherited; App is dropped
}

#2. Generate AST scaffolding

let lang = @language.Language::from_file(
  name="Lambda", path="poc/lang_def.mbt", mod="YumeXi/nanocake",
)
let impls = lang.gen()
@fmt.impls_to_string(impls) // format and write to file

#3. Generate S-expression codecs

let lang = @language.Language::from_file(...)
// Generate from_sexp / parse_sexp / to_sexp_doc / unparse_sexp per type.
let codec_impls = @gen.gen(lang)

#4. Write passes

#Package Reference

#@meta_parser — Parse annotations

#@language — Generate AST scaffolding

#@unparser/sexp — S-expression runtime

#@unparser/gen — Codec generator

#@pass — Transformation-pass scaffolding

#Design Rationale

#Why code generation instead of a generic runtime?

#How extra type variables work

#Goals

#TODOs

• #nano.form named placeholders — $x / $body by meta-var name, repeat (...), optional, and dotted-list patterns are parsed by meta_parser but not yet consumed by the codec generator.
• +/- extension syntax — explicit add/remove in the enum body (current #nano.remove covers top-level removal; inline +/- markers are not yet supported).
• layout.group type convergence — GeneratedLanguageLayout.group is still Array[NanoLangDef]; migrating to ExpandedLanguageGroup would eliminate the parallel shared/own derivation in the layout builder.

#Continued improvements

• Better codegen ergonomics — reduce raise noise in generated output, improve formatting, and add docstrings to generated methods.
• Error handling in passes — allow passes to raise typed errors, with ergonomic error propagation across the pipeline.
• Pass composition — a higher-level API for chaining passes with shared state, dependency tracking, and short-circuit on error.

#Incremental computation

• Pass dependency tracking — each pass declares its input and output language; the framework can infer a dependency graph and determine the minimal set of passes to re-execute.
• Granular caching — cache pass results per AST node or subtree. When a leaf changes, only the ancestor nodes on the path to the root need re-computation.
• Dirtying and invalidation — integrate with editor tooling (LSP) to mark specific AST regions as dirty and incrementally re-run passes on just those regions.

#References