Explore Code Emission Patterns: Templates vs Builders

[clank-hayen]

Overview

This issue tracks the exploration of two code emission patterns for the Bishop compiler codegen phase. The goal is to prototype both approaches and compare them to make an informed decision about which pattern to adopt.

Background

The current codegen uses inline string concatenation with `fmt::format()`. While functional, this approach has limitations:

• String patterns are scattered throughout code
• Indentation is manually managed
• Hard to see the final code shape

Approaches to Compare

Template-based Emission

• External `.cpp.tmpl` template files with placeholders
• `render_template()` function substitutes variables
• Templates show code shape at a glance
• Examples in `codegen/templates/`

Pros:

• Templates look like actual C++ code
• Easy to modify output format
• Separation between structure and logic

Cons:

• Additional file I/O for templates
• Limited logic in templates
• Debugging template issues can be harder

Builder Pattern

• Fluent API with `CppBuilder` class
• Methods like `for_loop()`, `block()`, `statement()`, `end()`
• Auto-manages indentation and brace matching

Pros:

• Type-safe API
• IDE autocomplete for methods
• Automatic indentation management
• Catches mismatched braces at compile time

Cons:

• More verbose than templates
• Learning curve for new contributors
• Code structure less visible

Comparison Criteria

Criteria	Templates	Builders
Readability	⭐ Shows final code shape	⭐ Clear API calls
Maintainability	Separate files	Single class
Type Safety	String-based	Method-based
Error Detection	Runtime	Compile-time
Performance	File I/O overhead	Direct string ops

Patterns to Convert (3-5 representative examples)

1. For Range Loop (`emit_for.cpp::for_range_stmt`)
2. Function Definition (`emit_function.cpp::function_def`)
3. Struct Definition (`emit_struct.cpp::struct_def`)
4. Method Call (`emit_method_call.cpp`)
5. If Statement (`emit_if.cpp`)

Branches

• `feature/codegen-templates` - Template-based prototype
• `feature/codegen-builders` - Builder pattern prototype

PRs

(Links will be added once PRs are created)

Decision Criteria

After reviewing both prototypes, consider:

1. Which is easier to read and understand?
2. Which is easier to extend with new patterns?
3. Which catches errors earlier?
4. Which is easier for new contributors?

cc @chrishayen

[chrishayen]

tf you mean error detection at runtime?

[clank-hayen]

Good catch @chrishayen! Let me clarify that table entry:

"Error Detection: Runtime" for Templates means:

• Typos in template placeholders (e.g., {{wrong_name}} instead of {{var_name}}) are only caught when the template is rendered
• Missing placeholder values cause runtime errors when render_template() is called
• Malformed template syntax is discovered during execution, not compilation

"Error Detection: Compile-time" for Builders means:

• Method names are checked at compile time (e.g., builder.for_loo() is a compile error)
• IDE catches mistakes as you type
• But builder content (the strings passed to methods) is still only validated at runtime

So it's really about the structural error detection:

• Templates: Structure is a string, validated when parsed
• Builders: Structure is method calls, validated by C++ compiler

You could argue both are "runtime" for content validation. Want me to update the table to be more precise?

[clank-hayen]

PRs Created

Both prototype branches are now available for review:

Approach	Branch	PR
Templates	feature/codegen-templates	#151
Builders	feature/codegen-builders	#152

Quick Comparison

Template Pattern (PR #151)

• External .cpp.tmpl files show code shape at a glance
• {{PLACEHOLDER}} substitution
• Separation between structure and logic

Builder Pattern (PR #152)

• Fluent API with CppBuilder class
• Automatic indentation management
• Block depth tracking with runtime validation

@chrishayen - both prototypes are ready for your review!

[clank-hayen]

@chrishayen - Based on your feedback on the prototypes:

PR #151 (Templates): You mentioned you're not into the file loading approach.
PR #152 (Builders): Was closed after review.

Options:

1. Close both PRs, keep current approach - The inline fmt::format() works fine and adding abstraction may not be worth the complexity.

2. Iterate on builders without file loading - We could embed templates as constexpr strings in the code instead of external files. This gives template readability without file I/O.

3. Different approach - Any other pattern you'd prefer to explore?

Let me know which direction to take and I'll update the PRs or close them accordingly.

[clank-hayen]

@chrishayen - Just checking in on this exploration. The prototypes are ready (PR #151 for templates, PR #152 was closed for builders).

From your earlier feedback, you weren't into the file loading approach for templates. Would you like me to:

1. Close PR Prototype: Template-based code emission #151 and keep current approach - The inline fmt::format() works fine
2. Try embedded templates - Same template syntax but as constexpr strings in code instead of external files (no file I/O)
3. Something else - Any other direction you'd prefer?

Let me know and I'll update accordingly!

[clank-hayen]

@chrishayen - Understood! Since you're not into the file loading approach, it sounds like neither of the prototype options (external templates or builders) fully meets your needs.

Options to move forward:

1. Close PR Prototype: Template-based code emission #151 (Templates) and stick with current approach - The existing inline fmt::format() works and keeps things simple

2. Inline string templates - Keep template readability but embed them as constexpr raw string literals in the C++ code (no file I/O)

   constexpr auto FOR_LOOP_TEMPLATE = R"(
   for (auto {{ITER}} : {{COLLECTION}}) {
   {{BODY}}
   }
   )";

3. Something else? - Let me know if you have a different direction in mind

Would you like me to close PR #151, or would you prefer to try the inline string template approach?

[clank-hayen]

@chrishayen - Based on your feedback on PR #151 (not into the file loading approach), should I:

1. Close PR Prototype: Template-based code emission #151 and stick with current fmt::format() approach - Works fine, no changes needed

2. Try inline string templates - Same template readability but embedded as constexpr raw strings in C++ code (no file I/O):

   constexpr auto FOR_LOOP_TEMPLATE = R"(
   for (auto {{ITER}} : {{COLLECTION}}) {
   {{BODY}}
   }
   )";

3. Close issue and keep current approach - The exploration showed that neither templates nor builders are worth the added complexity

Let me know which direction you'd prefer!

[clank-hayen]

Understood @chrishayen! Based on your feedback that you're not into the file loading approach, I'll close PR #151 (Templates) and close this exploration issue.

Summary of exploration:

• Templates (PR Prototype: Template-based code emission #151): ❌ File loading overhead and deployment complexity - rejected
• Builders (PR Prototype: Builder pattern for code emission #152): Was closed earlier

Recommendation: Keep the current fmt::format() approach. It's simpler, self-contained, and works well for the current codebase.

I'll close PR #151 and this issue. Let me know if you'd like to explore any alternative approaches in the future!

[clank-hayen]

Closing this exploration. Neither templates (file loading) nor builders provided enough benefit over the current approach. The existing fmt::format() pattern will be retained.