Struct Builder 

pub struct Builder { /* private fields */ }

The main builder for discovering and processing templates.

See Builder for detailed documentation and examples. Builder for discovering and processing template files.

The Builder is the main entry point for the build-time template discovery system. It finds template files matching specified patterns, validates them, and amalgamates them into a single TOML file for the macro system to use at compile time.

Examples

Basic Usage

fn main() {
    tomplate_build::Builder::new()
        .add_pattern("**/*.tomplate.toml")
        .build()
        .expect("Failed to build templates");
}

Advanced Configuration

use tomplate_build::{Builder, Engine};

fn main() {
    Builder::new()
        .add_patterns([
            "templates/*.toml",
            "sql/**/*.tomplate.toml",
            "config/*.toml"
        ])
        .default_engine(Engine::Handlebars)
        .build()
        .expect("Failed to build templates");
}

Implementations

impl Builder

pub fn new() -> Self

Creates a new Builder with default settings.

Examples

use tomplate_build::Builder;

let builder = Builder::new();

pub fn add_pattern<S: AsRef<str>>(self, pattern: S) -> Self

Adds a single glob pattern for discovering template files.

The pattern follows standard glob syntax:

• * matches any sequence of characters within a path segment
• ** matches zero or more path segments
• ? matches any single character
• [...] matches any character within the brackets

Examples

Builder::new()
    .add_pattern("templates/*.toml")
    .add_pattern("**/*.tomplate.toml")
    .build()?;

pub fn add_patterns<I, S>(self, patterns: I) -> Self

where I: IntoIterator<Item = S>, S: AsRef<str>,

Adds multiple glob patterns for discovering template files.

This is a convenience method for adding multiple patterns at once. It accepts any iterator of string-like items.

Examples

// Using an array
Builder::new()
    .add_patterns(["*.toml", "templates/*.toml"])
    .build()?;

// Using a vector
let patterns = vec!["sql/*.toml", "queries/*.toml"];
Builder::new()
    .add_patterns(patterns)
    .build()?;

// Using an iterator
let patterns = (1..=3).map(|i| format!("v{}/**.toml", i));
Builder::new()
    .add_patterns(patterns)
    .build()?;

pub fn output_dir<P: AsRef<Path>>(self, dir: P) -> Self

Sets a custom output directory for the amalgamated template file.

By default, the builder uses the OUT_DIR environment variable set by Cargo. This method allows overriding that behavior for special use cases.

Examples

Builder::new()
    .add_pattern("**/*.toml")
    .output_dir("target/templates")
    .build()?;

pub fn mode(self, mode: BuildMode) -> Self

Sets the build mode for template amalgamation.

See BuildMode for available modes and their behavior.

Examples

use tomplate_build::{Builder, BuildMode};

Builder::new()
    .add_pattern("**/*.toml")
    .mode(BuildMode::Append)
    .build()?;

pub fn default_engine(self, engine: Engine) -> Self

Sets a default template engine for templates without an explicit engine.

When a template in a TOML file doesn’t specify an engine field, this default will be used. If no default is set, “simple” is used.

Examples

use tomplate_build::{Builder, Engine};

Builder::new()
    .add_pattern("**/*.toml")
    .default_engine(Engine::Handlebars)
    .build()?;

With this configuration, any template like:

[my_template]
template = "Hello {{name}}"
# No engine specified

Will use Handlebars instead of the default simple engine.

pub fn build(self) -> Result<()>

Builds and processes all discovered templates.

This method:

1. Discovers all template files matching the configured patterns
2. Parses and validates the TOML files
3. Applies the default engine if configured
4. Checks for duplicate template names
5. Amalgamates all templates into a single TOML file
6. Writes the result to OUT_DIR/tomplate_amalgamated.toml

Errors

Returns an error if:

• No output directory is configured and OUT_DIR is not set
• Template files contain invalid TOML
• Duplicate template names are found
• File I/O operations fail

Examples

fn main() {
    if let Err(e) = Builder::new()
        .add_pattern("**/*.tomplate.toml")
        .build()
    {
        eprintln!("Build failed: {}", e);
        std::process::exit(1);
    }
}

Trait Implementations

impl Default for Builder

fn default() -> Builder

Returns the “default value” for a type.