TemplateForge

A powerful and extensible template-based code generation framework for .NET.

Features

Core Features

• Multiple Template Engines - Built-in Scriban support, extensible for others

• Flexible Package Formats - Binary packages, directory-based, or custom formats

• Customizable Magic Numbers - Define your own package format identifier

• Value Processors - Built-in hex, bool-to-int, formatting, and more

• Output Processors - Auto-formatting, line ending normalization

• Event System - Progress tracking, logging, and cancellation support

• Fluent API - Chain configuration calls for clean code

• Generation Pipeline - Advanced pipeline with hooks and validation

• Template Partials - Include/import support for template reuse

• Schema Validation - JSON Schema-based context validation

• Configuration Presets - Save and reuse configuration profiles

• Batch Generation - Generate for multiple targets in parallel

• Preview & Diff - Preview changes before writing files

• Built-in Hooks - ZIP archive, manifest, README, clang-format

Quick Start

Template Syntax (Scriban)

{{ variable_name }} {{ if condition }}...{{ end }} {{ for item in collection }}...{{ end }} {{ variable | string.upcase }}

Basic Usage

using TemplateForge; using TemplateForge.Core; // Create generator var generator = new CodeGenerator(); // Load templates await generator.LoadPackageAsync("templates.bin"); // Create context with variables var context = new TemplateContext() .Set("project_name", "MyProject") .Set("version", "1.0.0") .Set("author", "John Doe"); // Generate code var result = await generator.GenerateAsync(context, outputPath);

Custom Magic Number

// Using hex value var generator = new CodeGenerator(0x4D595047); // "MYPG" // Using string var generator = new CodeGenerator("MYPG"); // Using helper using TemplateForge.Utilities; var magic = MagicNumberHelper.FromString("CHIP"); var generator = new CodeGenerator(magic);

Creating Template Packages

using TemplateForge.Packaging; // Build package programmatically var builder = new TemplatePackageBuilder() .WithId("my-templates") .WithName("My Template Package") .WithVersion("1.0.0") .WithMagicNumber("MYPG") // Custom magic number .AddTemplatesFromDirectory("./templates"); await builder.SaveAsync("my-templates.bin"); // Or quick pack await PackageBuilderExtensions.PackDirectoryAsync( "./templates", "output.bin", "*.template", MagicNumberHelper.FromString("MYPG") );

Using Extension Methods

using TemplateForge.Extensions; var context = new TemplateContext() .SetHex("config_reg", 0x1A, 2) // "1a" .SetBool("feature_enabled", true) // Sets 3 vars: feature_enabled, feature_enabled_int, is_feature_enabled .SetDouble("timeout", 2.5) // Smart formatting .SetEnum("mode", MyEnum.Option1); // Sets mode, mode_value, is_mode_option1, etc.

Event Handling

var generator = new CodeGenerator(); generator.ProgressChanged += (s, e) => Console.WriteLine($"[{e.ProgressPercentage:F0}%] {e.CurrentTemplate}"); generator.Log += (s, e) => Console.WriteLine($"[{e.Level}] {e.Message}"); generator.BeforeRendering += (s, e) => { if (e.TemplateName.Contains("debug")) e.Cancel = true; // Skip debug templates }; generator.Completed += (s, e) => Console.WriteLine($"Done! {e.FilesGenerated} files in {e.Duration.TotalSeconds:F2}s");

Configuration Options

var generator = new CodeGenerator() .WithDefaults() .WithDirectories("obj", "build") .Configure(options => { options.OverwriteExisting = true; options.ContinueOnError = false; options.ValidateTemplates = true; options.OutputEncoding = Encoding.UTF8; });

Generation Pipeline with Hooks

using TemplateForge; using TemplateForge.Advanced; using TemplateForge.Extensions; var generator = new CodeGenerator(); await generator.LoadPackageAsync("templates.bin"); // Create pipeline with hooks var pipeline = generator.CreatePipeline() .WithCommonHooks() // Add logging and manifest .WithCodeFormatting() // Add clang-format hook .RegisterHook("CustomHook", HookTiming.AfterGeneration, ctx => { Console.WriteLine($"Generated {ctx.GeneratedFiles.Count} files"); return HookResult.Ok(); }); // Execute pipeline var result = await pipeline.ExecuteAsync(context, outputPath);

Schema Validation

// Define a generic schema using builder var pipeline = generator.CreatePipeline() .WithSchema(schema => schema .WithName("AppConfig") .AddInteger("retry_count", required: true, min: 0, max: 10) .AddDouble("timeout_seconds", required: true, min: 0.1, max: 300) .AddBoolean("feature_enabled") .AddEnum("log_level", new[] { "Debug", "Info", "Warn", "Error" })); // Validation happens automatically before generation var result = await pipeline.ExecuteAsync(context, outputPath);

Configuration Presets

// Register a preset pipeline.Presets.Register(new ConfigurationPreset { Id = "staging", Name = "Staging Defaults", Variables = new Dictionary<string, object?> { ["retry_count"] = 3, ["timeout_seconds"] = 30.0, ["feature_enabled"] = true, ["log_level"] = "Info" } }); // Apply preset to context pipeline.Presets.ApplyPreset("staging", context);

Batch Generation

var batchService = generator.CreateBatchService(); // Create targets for multiple variants var targets = new BatchTargetBuilder() .WithBaseContext(baseContext) .AddTarget("Standard", ctx => ctx.Set("variant", "standard")) .AddTarget("Pro", ctx => ctx.Set("variant", "pro")) .AddCombinations("log_level", new[] { "Info", "Debug" }) .Build(); // Generate all targets var result = await batchService.GenerateAsync(targets, outputPath, new BatchGenerationOptions { MaxParallelism = 4, CreateSubdirectories = true });

Preview Before Generation

var pipeline = generator.CreatePipeline() .WithPreview(async preview => { Console.WriteLine(preview.GetSummary()); Console.WriteLine($"New files: {preview.NewFiles}"); Console.WriteLine($"Modified: {preview.ModifiedFiles}"); // Return true to proceed, false to cancel return await ConfirmWithUser(); });

Template Partials

// Load partials from directory (files starting with _) await pipeline.Partials.LoadFromDirectoryAsync("./templates/_partials"); // Or register manually pipeline.Partials.Register("header", "/* Common header content */"); // Use in templates with include // {{ include 'header' }}

Project Structure

TemplateForge/ ├── Core/ # Template engine interfaces ├── Packaging/ # Package formats and loaders ├── Processing/ # Value and output processors ├── Configuration/ # Generator options ├── Extensions/ # Extension methods ├── Advanced/ # v2.0 Advanced features │ ├── GenerationPipeline # Pipeline orchestration │ ├── IGenerationHook # Hook system │ ├── IContextValidator # Schema validation │ ├── ConfigurationPreset # Preset management │ ├── BatchGeneration # Multi-target generation │ ├── GenerationPreview # Preview and diff │ └── BuiltInHooks # Common hooks ├── Utilities/ # Helper classes └── CodeGenerator.cs # Main entry point

License

MIT License