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;
use sigil_stitch::lang::typescript::TypeScript;

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

let mut cb = CodeBlock::<TypeScript>::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 mut fb = FileSpec::<TypeScript>::builder("user.ts");
fb.add_code(body);
let file = fb.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::<TypeScript>::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.

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 the Spec Layer chapter for examples and the full API.

Supported Languages

Documentation

The sigil-stitch book covers everything in depth:

• 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
• The Spec Layer -- TypeSpec, FunSpec, FieldSpec, FileSpec, ProjectSpec
• sigil_quote! Macro -- inline code with $T/$S/$N/$L interpolation
• Code Templates -- reusable #{name:K} templates
• Adding a Language -- implementing the CodeLang trait step by step
• Architecture -- four layers, three-pass pipeline, import resolution

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.