sigil-stitch

Type-safe, import-aware, width-aware code generation for multiple languages.

sigil-stitch combines JavaPoet's builder + CodeBlock model with Wadler-Lindig pretty printing and multi-language support. Reference types with %T in format strings, and the library tracks every import for you, resolves naming conflicts, and emits width-aware formatted output.

Quick Start

cargo add sigil-stitch

Requires Rust edition 2024, MSRV 1.88.0. Runtime dependencies: pretty (Wadler-Lindig formatting), serde with derive (every spec type implements Serialize/Deserialize out of the box, so you can round-trip specs as JSON or YAML), and snafu (structured errors).

Builder vs Macro

sigil-stitch offers two ways to build code. Both produce the same CodeBlock with the same import tracking and rendering.

Builder API -- programmatic, good for dynamic code generation:

use sigil_stitch::prelude::*;
use sigil_stitch::code_block::StringLitArg;

let user_type = TypeName::importable_type("./models", "User");

let mut cb = CodeBlock::builder();
cb.add_statement(
    "const user: %T = await getUser(%S)",
    (user_type.clone(), StringLitArg("id".into())),
);
cb.add_statement("return user", ());
let body = cb.build().unwrap();

let file = FileSpec::builder("user.ts")
    .add_code(body)
    .build()
    .unwrap();

let output = file.render(80).unwrap();
assert!(output.contains("import type { User } from './models'"));
assert!(output.contains("const user: User = await getUser('id');"));

sigil_quote! macro -- inline target-language code, less ceremony:

use sigil_stitch::prelude::*;
use sigil_stitch::lang::typescript::TypeScript;

let user_type = TypeName::importable_type("./models", "User");

let body = sigil_quote!(TypeScript {
    const user: $T(user_type) = await getUser($S("id"));
    if (!user) {
        throw new Error($S("not found"));
    }
    return user;
}).unwrap();

The macro uses $T/$S/$N/$L/$C/$W interpolation markers that expand to the equivalent %T/%S/%N/%L format specifiers at compile time. It also supports $C_each for splicing iterables of code blocks, $if/$else_if/$else for meta-conditionals, $for for compile-time iteration, $let for Rust-level variable bindings, $join for separator-joined lists, and $+ for line continuation in multi-line expressions.

Format Specifiers

Bare &str maps to %L. Use NameArg for %N and StringLitArg for %S. See the Format Specifiers chapter for the full deep dive.

The Spec Layer

Build structured declarations with the spec builders:

All specs emit CodeBlocks internally, so import tracking works everywhere. See Building Functions & Fields, Building Types & Enums, and Files & Projects for examples and the full API.

Supported Languages

Documentation

The sigil-stitch book covers everything in depth:

User Guide:

• Introduction -- what it is and how the pieces fit together
• Getting Started -- first CodeBlock, first FileSpec, first output
• Format Specifiers -- deep dive on %T, %N, %S, %L, %W, and friends
• TypeName -- type references, import tracking, cross-language rendering
• Building Functions & Fields -- ParameterSpec, FieldSpec, FunSpec
• Building Types & Enums -- TypeSpec, PropertySpec, AnnotationSpec, EnumVariantSpec
• Files & Projects -- ImportSpec, FileSpec, ProjectSpec
• sigil_quote! Macro -- inline code with $T/$S/$N/$L/$C_each/$if/$for/$let/$join/$+ interpolation
• Code Templates -- reusable #{name:K} templates
• Language Cookbook -- idiomatic recipes per language

Development Guide:

• Architecture -- four layers, three-pass pipeline, import resolution
• Type Presentation -- data-driven cross-language type rendering
• Adding a Language -- implementing the CodeLang trait step by step

MSRV

The minimum supported Rust version is 1.88.0 (edition 2024, let-chains).

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.