generator-coding

Files (1)

• SKILL.md

SKILL.md (first lines)

# Template-Based Code Generation

Three inputs produce repetitive (typically interface) code:

- **Data model**: Standardized representation -- XML, Domain-Specific Language (DSL), or schema-enforced JSON/YAML.
- **Template**: Templating meta-language markup ([Jinja2](https://jinja.palletsprojects.com/), [ERB](https://docs.ruby-lang.org/en/master/ERB.html), etc.).
- **Helper functions**: Functions that reshape the data model for template consumption.

```
Data Model ──► Parser ──► Helpers ──► Template Engine ──► Generated Output
   (SVD,         (cmsis-svd,   (reshape,    (Jinja2,        (one file per
    IDL,          sqlparse)     filter)      ERB)            generation unit)
    DBML...)
```


## Terms

| Term | Definition |
|------|-----------|
| **Data Model** | Input describing the structure to replicate (e.g. SVD file for hardware registers). |
| **Helpers/Plugins** | Functions that transform/filter/restructure the data model for templates. |
| **Template(s)** | Defines output structure in the target language with template markup for variable parts. |
| **Target Language** | Language of the generated output (e.g. C++, Python, Verilog). |
| **Generated Output** | Files produced by the generator. Must never be hand-edited (see: Rules). |
| **Generation Unit** | Data model component a template operates on (e.g. peripheral, table, message). One output file per unit (see: Step 3). |
| **Data Bridge Template** | Template converting the data model into target-language compile-time representations (enums, constants, macros). Consumed by in-language meta-programming (see: Meta-Programming Rules). |


## Generator Types

| Type | Description | Template Location | Flexibility |
|------|-------------|-------------------|-------------|
| **Fixed function** | Template embedded in generator tool code | Inside the tool | Output format fixed; change requires modifying the tool |
| **Customizable template-based** | Template separated from tool | User-editable files | User can modify/replace templates freely |

**Directive**: Prefer customizable template-based generators for agent use. The agent can read, understand, and modify templates without understanding the tool's internals.


## Meta-Programming

| Type | Mechanism | When to use |
|------|-----------|-------------|
| **In-language** | C++ templates/`constexpr`/`consteval`, C preprocessor, Python decorators, Verilog `generate` | Data can be represented in target language compile-time constructs |
| **External template-based** | Jinja2/ERB generating source files | Data cannot be naturally represented in target language (e.g. register maps, protocol definitions) |

**Directive**: Prefer in-language meta-programming -- the target toolchain handles validation, error reporting, and IDE support. Combine with external generation using the layered approach (see: Meta-Programming Rules).


## Examples

### Generator Tools

| Tool | Type | Templating | Domain |
|------|------|-----------|--------|
| [Protobuf](https://protobuf.dev/) (`protoc`) | Fixed | Embedded | Serialization / RPC |
| [Cyclone DDS](https://cyclonedds.io/) (`idlc`) | Fixed | Embedded | DDS/OMG IDL interfaces |
| [SWIG](https://www.swig.org/) | Fixed | Embedded | Foreign Function Interface (FFI) wrappers |
| [Ruby on Rails](https://guides.rubyonrails.org/generators.html) | Template | ERB | Web scaffolding |
| [Cookiecutter](https://www.cookiecutter.io/) | Template | Jinja2 | Project scaffolding |
| [development-utils](https://github.com/nakane1chome/development-utils) | Template | Jinja2 | Hardware description (SVD, SystemRDL, DBML, Device Tree, IDL) |

### Data Model Formats

| Format | Domain | Type |
|--------|--------|------|
| SQL DDL | Databases | Data exchange |
| XML ([SVD](https://www.keil.com/pack/doc/CMSIS/SVD/html/index.html), ATML) | Hardware, general | Data exchange |
| JSON / YAML / TOML | General (schema required) | Data exchange |
| [IDL](https://www.omg.org/spec/IDL/) (Interface Definition Language) | Distributed systems (CORBA, DDS, Protobuf) | DSL |
| [SystemRDL](https://www.accellera.org/downloads/standards/systemrdl) | Register descriptions | DSL |
| [DBML](https://dbml.dbdiagram.io/) (Database Markup Language) | Database schemas | DSL |
| [AADL](https://www.aadl.info/) (Architecture Analysis and Design Language) | Safety-critical systems | DSL |
| [SysML](https://sysml.org/) | Systems modeling | DSL |
| [Device Tree](https://www.devicetree.org/) | Linux/embedded hardware | DSL |

### Templating Languages

| Language | Ecosystem | Logic | Strengths |
|----------|-----------|-------|-----------|
| [Jinja2](https://jinja.palletsprojects.com/) | Python | Full (loops, macros, filters) | Most expressive; `StrictUndefined`; dominant for standalone generators |
| [ERB](https://docs.ruby-lang.org/en/master/ERB.html) | Ruby | Full Ruby execution | Native to Rails |
| [Liquid](https://shopify.github.io/liquid/) | Ruby | Safe subset | Sandboxed; safe for user-supplied templates |
| [Mako](https://www.makotemplates.org/) | Python | Full Python execution | Fast; used by Alembic |
| [Mustache](https://mustache.github.io/)/[Handlebars](https://handlebarsjs.com/) | Language-agnostic | Logic-less | Forces logic into helpers |


## Process

### Step 1: Identify the Data Model

Use the user's existing data model. If none exists, select a domain standard:

| Domain | Standard formats |
|--------|-----------------|
| Hardware registers | SVD, SystemRDL, [IP-XACT](https://www.accellera.org/downloads/standards/ip-xact) (IEEE 1685) |
| Communication protocols | Protobuf, IDL, [ASN.1](https://www.itu.int/en/ITU-T/asn1/Pages/introduction.aspx) |
| Database schemas | SQL DDL, DBML |
| APIs | [OpenAPI](https://www.openapis.org/)/Swagger, [GraphQL](https://graphql.org/) |
| Hardware architecture | Device Tree, AADL |

### Step 2: Understand the Interface Boundary

Identify the specification-defined interface:

| Boundary | Examples |
|----------|---------|
| Persistent data | Database tables, file formats |
| Inter-Process Communication (IPC) | Shared memory, message queues, pub/sub |
| Hardware/software | Memory-Mapped I/O (MMIO) registers, Direct Memory Access (DMA) descriptors |
| Language interop | Java Native Interface (JNI), Python C extensions, FFI |
| Network protocols | RPC definitions, serialization formats |

### Step 3: Determine the Generation Granularity

| Granularity | Scope | Use case |
|-------------|-------|----------|
| **Component-level** | One output file per generation unit (peripheral, message, table) | Direct usage patterns; simpler templates |
| **System-level** | One output file covering all components | Cross-cutting concerns (dispatch tables, device maps, schema migrations) |

From nakane1chome/claude-skills, Unlicense.

More from nakane1chome/claude-skills