tomplate_build/
lib.rs

1//! # Build-time utilities for Tomplate
2//!
3//! This crate provides build-time template discovery and amalgamation for the Tomplate
4//! template engine. It's designed to be used in `build.rs` scripts to discover template
5//! files in your project and prepare them for compile-time processing.
6//!
7//! ## Overview
8//!
9//! The build process:
10//! 1. Discovers `.tomplate.toml` files using glob patterns
11//! 2. Parses and validates template definitions
12//! 3. Amalgamates all templates into a single TOML file
13//! 4. Places the amalgamated file in `OUT_DIR` for the macro to read
14//!
15//! ## Quick Start
16//!
17//! In your `build.rs`:
18//!
19//! ```rust,ignore
20//! fn main() {
21//!     tomplate_build::Builder::new()
22//!         .add_patterns([
23//!             "**/*.tomplate.toml",
24//!             "templates/*.toml"
25//!         ])
26//!         .build()
27//!         .expect("Failed to build templates");
28//! }
29//! ```
30//!
31//! ## Template File Format
32//!
33//! Templates are defined in TOML files with the following structure:
34//!
35//! ```toml
36//! [template_name]
37//! template = "The template string with {placeholders}"
38//! engine = "simple"  # Optional: "simple", "handlebars", "tera", or "minijinja"
39//!
40//! [another_template]
41//! template = """
42//! Multi-line templates
43//! are also supported
44//! """
45//! ```
46//!
47//! ## Advanced Configuration
48//!
49//! ```rust,ignore
50//! use tomplate_build::{Builder, Engine};
51//!
52//! fn main() {
53//!     Builder::new()
54//!         // Add patterns one by one
55//!         .add_pattern("templates/*.toml")
56//!         .add_pattern("sql/*.toml")
57//!         // Or add multiple at once
58//!         .add_patterns(vec!["config/*.toml", "queries/*.toml"])
59//!         // Set a default engine for templates without explicit engine
60//!         .default_engine(Engine::Handlebars)
61//!         // Build and generate the amalgamated file
62//!         .build()
63//!         .expect("Failed to build templates");
64//! }
65//! ```
66//!
67//! ## Error Handling
68//!
69//! The builder will fail if:
70//! - Template files have invalid TOML syntax
71//! - Duplicate template names are found across files
72//! - File I/O errors occur
73//!
74//! ## Integration with Cargo
75//!
76//! The builder automatically:
77//! - Sets up `cargo:rerun-if-changed` for template files
78//! - Outputs to `OUT_DIR` (respecting Cargo's build system)
79//! - Provides clear error messages for debugging
80
81mod amalgamator;
82mod builder;
83mod discovery;
84
85/// Types used throughout the build system.
86///
87/// This module contains the core types used by the build system including
88/// template definitions, error types, and engine specifications.
89pub mod types;
90
91/// The main builder for discovering and processing templates.
92///
93/// See [`Builder`] for detailed documentation and examples.
94pub use builder::Builder;
95
96/// Build mode for template amalgamation.
97///
98/// See [`BuildMode`] for available modes.
99pub use builder::BuildMode;
100
101/// Template engine specifications.
102///
103/// See [`Engine`] for available engines.
104pub use types::Engine;
105
106/// Error type for build operations.
107///
108/// See [`Error`] for possible error variants.
109pub use types::Error;
110
111/// Result type alias for build operations.
112pub use types::Result;
113
114/// Template definition structure.
115///
116/// See [`Template`] for template structure details.
117pub use types::Template;
tomplate_build/lib.rs

tomplate_build/
lib.rs
