#YumeXi/nanocake

• GitHub: https://github.com/PrairieFire2b/nanocake
• Package: https://mooncakes.io/docs/YumeXi/nanocake

#Installation

moon add YumeXi/nanocake@0.4.3

moon install YumeXi/nanocake/cmd/nanocake@0.4.3
nanocake --help

git clone https://github.com/PrairieFire2b/nanocake.git
cd nanocake
moon update
moon check
moon test

#Architecture

                   ┌─────────────┐
 .cake / attributes│ meta_parser │  parse metadata, resolve extends chains,
                   └──────┬──────┘  apply removals, 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 .cake sidecars or the compatibility attribute syntax. Resolves language definitions, inheritance, constructor removals, effective entries, surface forms, hooks, 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, structural .cake form 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

#Generate MoonBit sources

nanocake generate \
  --spec schema/arithmetic.cake \
  --language Arithmetic \
  --module user/compiler \
  --pkg schema \
  --out-dir generated

moon run cmd/nanocake -- generate \
  --spec examples/nanocake-demo/schema/arithmetic.cake \
  --language Arithmetic \
  --module YumeXi/nanocake-demo \
  --pkg examples/nanocake-demo/schema \
  --out-dir examples/nanocake-demo/generated

generated/
  ast.mbt
  codec.mbt
  pass.mbt
  moon.pkg

moon run cmd/nanocake -- generate \
  --spec examples/nanocake-demo/schema/arithmetic.cake \
  --language Arithmetic \
  --module YumeXi/nanocake-demo \
  --pkg examples/nanocake-demo/schema \
  --out-dir examples/nanocake-demo/generated \
  --check

#Run the demo

moon -C examples/nanocake-demo run .

moon install ./examples/nanocake-demo
nanocake-demo

#Compatibility: define languages with attributes

///|
pub type LambdaVar = String

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

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

  #nano.form("(lambda ($0 : $1) $2)")
  #nano.form_only
  Lam(LambdaVar, Type, TypedExpr)

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

#nanopass.language(name="NoApp", extends="Lambda")
#nano.remove("App")
enum NoAppExpr {
  // only Lam, Int, LambdaVar are inherited; App is dropped
}

#Library API: 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

#Library API: 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)

#Library API: write passes

#Development

moon check --deny-warn
moon build
moon test --deny-warn
moon fmt --check
moon info
git diff --exit-code

#Repository Layout

#Package Reference

#@meta_parser — Parse annotations

#@language — Generate AST scaffolding

#@unparser/sexp — S-expression runtime

#@unparser/gen — Codec generator

#nanocake — Generator CLI

#@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