# Tron Template Engine Examples
This directory contains examples demonstrating the capabilities of the Tron template engine. Each example focuses on different aspects and use cases.
## Running the Examples
You can run any example using:
```bash
cargo run --example <example_name>
```
For example:
```bash
cargo run --example basic_usage
cargo run --example template_composition
```
## Example Overview
### 1. `basic_usage.rs`
**Focus:** Core Tron functionality and error handling
- Simple template creation and rendering
- Multiple placeholders usage
- TronRef with dependencies
- Error handling examples
**Key concepts:** TronTemplate, TronRef, error handling, basic API usage
### 2. `template_composition.rs`
**Focus:** Building complex templates from smaller components
- Basic template composition
- Multi-level nested composition
- Reusable template components
- Component-based architecture patterns
**Key concepts:** Template nesting, composition patterns, reusability
### 3. `builder_patterns.rs`
**Focus:** Fluent API usage with builders
- TronTemplateBuilder usage
- TronRefBuilder with dependencies
- Bulk operations with HashMaps
- Method chaining showcase
**Key concepts:** Fluent APIs, builder patterns, ergonomic template creation
### 4. `assembler_usage.rs`
**Focus:** Combining multiple templates into structured output
- Basic template assembly
- Complete Rust file generation
- Global placeholder management
- Dependency collection and deduplication
**Key concepts:** TronAssembler, multi-template composition, dependency management
### 5. `validation_usage.rs`
**Focus:** Template quality assurance and linting
- Basic template validation
- Issue detection and reporting
- Custom validation configuration
- Security validation
- Multiple template validation workflows
**Key concepts:** TemplateValidator, quality assurance, linting, best practices
### 6. `advanced_features.rs`
**Focus:** Real-world application scenarios
- REST API code generation
- Database model generation
- Configuration-driven generation
- Build system integration
**Key concepts:** Code generation, real-world patterns, build integration
## Common Patterns Demonstrated
### Template Creation
```rust
// Direct creation
let template = TronTemplate::new("Hello @[name]@!")?;
// Using builder
let template = TronTemplateBuilder::new()
.content("Hello @[name]@!")
.set("name", "World")
.build()?;
```
### Template Composition
```rust
// Nested templates
let outer = TronTemplate::new("mod @[name]@ { @[content]@ }")?;
let inner = TronTemplate::new("fn @[func]@() { @[body]@ }")?;
let mut outer_ref = TronRef::new(outer);
let mut inner_ref = TronRef::new(inner);
inner_ref.set("func", "example")?;
inner_ref.set("body", "println!(\"Hello!\");")?;
outer_ref.set("name", "generated")?;
outer_ref.set_ref("content", inner_ref)?;
```
### Template Assembly
```rust
let mut assembler = TronAssembler::new();
assembler.add_template(header_template);
assembler.add_template(body_template);
assembler.add_template(footer_template);
let result = assembler.render_all()?;
```
### Validation
```rust
let validator = TemplateValidator::new();
let report = validator.validate(&template)?;
if report.has_issues() {
for issue in report.issues() {
println!("Issue: {}", issue);
}
}
```
## Use Case Categories
### 1. Code Generation
Examples show how to generate:
- Rust structs and implementations
- REST API handlers
- Database models
- Configuration files
### 2. Build System Integration
- Template validation in build scripts
- Configuration-driven generation
- Dependency management
- Template caching strategies
### 3. Quality Assurance
- Template linting and validation
- Best practice enforcement
- Security issue detection
- Performance optimization hints
### 4. Development Workflows
- Fluent API usage
- Error handling strategies
- Template composition patterns
- Reusable component design
## Best Practices Demonstrated
1. **Always validate templates** before using them in production
2. **Use descriptive placeholder names** (avoid single letters)
3. **Leverage composition** for complex template structures
4. **Handle errors gracefully** with proper error types
5. **Use builders** for ergonomic template creation
6. **Collect dependencies** when working with multiple templates
7. **Validate early** in your build process
8. **Cache templates** when appropriate for performance
## Testing the Examples
All examples are designed to be runnable and demonstrate working code. To test all examples:
```bash
# Run each example
for example in basic_usage template_composition builder_patterns assembler_usage validation_usage advanced_features; do
echo "Running $example..."
cargo run --example $example
echo "---"
done
```
## Integration with Your Projects
These examples can serve as starting points for integrating Tron into your own projects. Key integration points:
1. **Build Scripts:** Use validation examples for `build.rs`
2. **Code Generators:** Adapt advanced features examples
3. **CLI Tools:** Use builder patterns for user-friendly APIs
4. **Web Services:** Apply REST API generation patterns
5. **Configuration:** Use configuration-driven examples
For more information, see the main crate documentation and API reference.