weaveback-macro is the macro-expansion engine at the heart of the weaveback literate-programming toolchain. It reads a document containing %def / %set / %if / %rhaidef / %pydef macro calls, evaluates them, and emits the expanded text.

This page is the crate-level index. It generates lib.rs and links to every sub-module documented as a literate AsciiDoc source.

Architecture

PlantUML diagram

Modules

Table 1. Literate sources
Module Adoc source Description

types

types.adoc

Shared vocabulary: TokenKind, NodeKind, Token, ParseNode, ASTNode

line_index

line_index.adoc

Byte-offset → (line, column) via SIMD newline scan

lexer

lexer/lexer.adoc

DFA tokeniser; emits Token stream from source text

parser

parser/parser.adoc

Recursive-descent parser; builds ParseNode arena

ast

ast/ast.adoc

Arena → tree conversion, serialisation, AST dump

evaluator

evaluator/evaluator.adoc

Macro expansion engine — see sub-modules below

evaluator::state

evaluator/state.adoc

EvalConfig, scope stack, TrackedValue, EvaluatorState

evaluator::output

evaluator/output.adoc

EvalOutput trait, PlainOutput, TracingOutput, PreciseTracingOutput

evaluator::core

evaluator/core.adoc

Main eval loop — node dispatch, macro call, freeze/export

evaluator::builtins

evaluator/builtins.adoc

Built-in dispatch table, case conversion, %here, WordSplitter

evaluator::scripting

evaluator/scripting.adoc

Rhai and Monty (Python) script back-ends

evaluator::eval_api

evaluator/eval_api.adoc

String / file / batch entry points; in==out guard

macro_api

macro_api.adoc

Byte-oriented public API with tracing and precise attribution

CLI binary

bin/cli.adoc

weaveback-macro binary: clap args, --dir discovery, --dump-ast

lib.rs — crate root

The crate root re-exports the two most commonly used entry types (Lexer and Parser) at the crate level and declares each module.

File structure

// <<@file weaveback-macro/src/lib.rs>>=
// <<lib preamble>>
// <<lib modules>>
// <<lib reexports>>
// @

Module declarations

// <<lib preamble>>=
// crates/weaveback-macro/src/lib.rs
mod types;
pub use types::*;
// @
// <<lib modules>>=
pub mod ast;
pub mod evaluator;
pub mod lexer;
pub mod line_index;
pub mod macro_api;
pub mod parser;
// @
// <<lib reexports>>=
pub use lexer::Lexer;
pub use parser::Parser;
// @

Implementation pages

weaveback-macro is written as a literate program. Each module has a page combining prose, diagrams, and the full source:

Top-level modules

Ast

Bin

Evaluator

Lexer

Parser