Skip to content

Adopt the C# syntax template object model from ktsu.Semantics #84

Description

@matt-edmondson

Summary

ktsu.Semantics built a declarative C# syntax object model on top of CodeBlocker and it has turned out to be the most reusable part of that repository's generator stack. It is ~500 lines with zero references to physics, quantities, or anything else Semantics-specific — it is a general "describe a C# file as objects, render it to a CodeBlocker" layer. It should live here, where any generator can use it.

Source: Semantics.SourceGenerators/Templates/

What the model is

Type Role
TemplateBase Name, type, default value, attributes, keywords, comments — shared by everything
SourceFileTemplate File name, namespace, usings, classes
ClassTemplate Base class, interfaces, generic constraints, members, nested classes
MemberTemplate Abstract member base; defines member sort order (fields → properties → methods)
FieldTemplate Optional initializer, quoted or raw
PropertyTemplate Getter/setter/init bodies as delegates; collapses to { get; set; } shorthand when both are auto
MethodTemplate Parameters and a Action<CodeBlocker> body factory; emits ; when there is no body
ConstructorTemplate Parameters, : base(...) arguments, body factory
ParameterTemplate Type, name, optional default

Rendering is via WriteTo(CodeBlocker) plus a set of AddX extension methods, so it layers cleanly on the existing writer without changing it.

The value over raw WriteLine calls is that the generator author describes what to emit and the model owns the punctuation, spacing, member ordering, and shorthand decisions — which is exactly the part that is fiddly to get right and identical across every generator.

Scope of this issue

  • Port Templates/*.cs into this repository under a ktsu.CodeBlocker.Templates namespace, with the types made public (they are internal in Semantics).
  • Decide the packaging: same ktsu.CodeBlocker package, or a sibling ktsu.CodeBlocker.Templates package. Same package is simpler and the model has no extra dependencies; a split lets consumers who only want the writer skip it. Recommendation: same package, separate namespace.
  • Add XML documentation — the ported types are largely undocumented today, and this is public API here.
  • Add unit tests. The Semantics repo has coverage for PropertyTemplate only; every template kind needs at least a render-to-expected-string test.
  • The model must render through the configured indent string and newline (Make output line endings deterministic and configurable #81) rather than assuming either.

Correctness and coverage gaps in the ported code are deliberately not in scope here — they are tracked separately so the port stays a mechanical move. See the follow-up issues for the template model.

Acceptance criteria

  • The template types are public, documented, and render byte-identical output to the Semantics originals for the same inputs.
  • Packaging decision recorded in the issue and reflected in README.md.
  • Per-template render tests.
  • README.md gains a worked example: describe a small class as templates, render it, show the output.

Context

Part of ktsu-dev/Semantics#181 — extracting the code-generation stack out of Semantics.SourceGenerators. This is the largest single piece of that extraction.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions