Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Table of Contents

Ggen DX Features

This document covers all developer experience features in ggen, including both marketplace and local template workflows. These features focus on ergonomics, authoring workflows, error handling, and development productivity.

CLI Ergonomics

One Verb Philosophy

# Single command for everything
ggen gen <template> key=val ...

# No complex subcommand trees
# Just: ggen gen [template-ref] [options] [variables]

Auto-Discovery

# Automatically finds project configuration
cd my-project/
ggen gen cli subcommand name=hello  # Finds ggen.toml automatically

# Discovers templates directory
# Loads project-specific RDF graphs
# Merges environment variables

Variable Precedence

Variables are resolved in this order (later values override earlier):

  1. Environment variables (from .env files)
  2. System environment ($HOME, $USER, etc.)
  3. Project presets (from ggen.toml [preset] section)
  4. Template frontmatter (vars: section in template)
  5. CLI arguments (--var key=value)
# .env file
author=John Doe

# ggen.toml
[preset]
vars = { license = "MIT" }

# template frontmatter
vars:
  author: "Jane Smith"  # Overridden by CLI
  feature: "basic"

# CLI call
ggen gen cli subcommand --var author="CLI Author" --var feature="advanced"
# Result: author="CLI Author", license="MIT", feature="advanced"

Rich Dry Run

# Side-by-side diff view
ggen gen cli subcommand name=hello --dry

# Shows unified diff with context
# Displays target paths and variable summary
# No files written until you remove --dry

Execution Tracing

# See everything that happens during generation
GGEN_TRACE=1 ggen gen cli subcommand name=hello

# Outputs:
# === GGEN TRACE ===
# Template path: templates/cli/subcommand/rust.tmpl
# Resolved frontmatter:
# {to: "src/cmds/{{name}}.rs", vars: {name: "hello"}, ...}
# SPARQL prolog:
# @prefix cli: <urn:ggen:cli#> . @base <http://example.org/> .
# Target output path: src/cmds/hello.rs

Marketplace DX Features

Gpack Development Workflow

# Initialize new gpack
ggen pack init

# Add templates and dependencies
mkdir -p templates/cli/subcommand
# Create template files...

# Test gpack locally
ggen pack test

# Lint for publishing
ggen pack lint

# Publish to registry
ggen pack publish

Gpack Testing Best Practices

# Run golden tests
ggen pack test

# Test with different variables
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=test1
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=test2

# Verify deterministic output
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=test1
# Should produce identical output

Gpack Versioning Strategies

# Semantic versioning for gpacks
# Major.Minor.Patch
# 1.0.0 -> 1.0.1 (patch: bug fixes)
# 1.0.0 -> 1.1.0 (minor: new features)
# 1.0.0 -> 2.0.0 (major: breaking changes)

# Update gpack version
# Edit ggen.toml:
# version = "0.2.1"

# Test before publishing
ggen pack test
ggen pack lint

Authoring Loop

Live Development Mode

# Watch mode for rapid iteration
ggen dev --watch templates/

# Automatically re-renders when:
# - Template files change
# - Frontmatter is modified
# - RDF graphs are updated
# - SPARQL queries change

# Outputs to temp directory with live diff
# Perfect for template development

Gpack Development Mode

# Watch mode for gpack development
ggen pack dev --watch

# Automatically re-renders when:
# - Gpack templates change
# - Dependencies update
# - RDF graphs are modified
# - Tests need re-running

# Outputs to temp directory with live diff
# Perfect for gpack development

Template Scaffolding

# Generate new template with sensible defaults
ggen new template cli/subcommand/typescript

# Creates:
# templates/cli/subcommand/typescript.tmpl
# With standard frontmatter structure
# Includes example RDF and SPARQL
# Ready for customization

Template Documentation

# Get help for any template
ggen help cli/subcommand/rust.tmpl

# Shows:
# Template: cli/subcommand/rust.tmpl
# Description: Generate Rust CLI subcommand
# Required Variables:
#   name (string): Subcommand name
#   description (string): Help text
# Optional Variables:
#   author (string): Code author
# Examples:
#   ggen gen cli/subcommand/rust.tmpl name=status description="Show status"
# Dependencies:
#   RDF: graphs/cli.ttl
#   Queries: SELECT ?name ?description WHERE { ?cmd rdfs:label ?name }

Manifest Preview

# See what would be generated without running templates
ggen plan cli subcommand

# Shows:
# Would generate:
#   src/cmds/hello.rs (from templates/cli/subcommand/rust.tmpl)
#   src/cmds/goodbye.rs (from templates/cli/subcommand/rust.tmpl)
#   commands/hello.py (from templates/cli/subcommand/python.tmpl)
#
# Variables applied:
#   name=hello, description="Say hello"
#   name=goodbye, description="Say goodbye"

Error Handling

Tera Template Errors

# File:line:col with 5-line snippet and highlighted token
Error in templates/api/endpoint/rust.tmpl:12:8
   |
10 | pub struct {{name|pascal}}Handler {
11 |     // TODO: Add fields
12 |     pub {{field_name}
   |           ^^^^^^^^
   |
Expected closing `}}` for variable `field_name`

Suggestion: Add `}}` after field_name

Frontmatter Validation Errors

# Path.to.field with expected type and example
Error in templates/cli/subcommand/rust.tmpl frontmatter:
  .rdf[0] : Expected string, found array

  Expected format:
  rdf:
    - "graphs/cli.ttl"

  Got:
  rdf:
    - ["graphs/cli.ttl"]

Suggestion: Use string instead of array for single file

SPARQL Query Errors

# Shows prepended prolog and failing variable binding
SPARQL Error in templates/api/endpoint/rust.tmpl:
Query:
  @prefix api: <urn:ggen:api#> .
  @base <http://example.org/> .
  SELECT ?name ?type WHERE {
    ?endpoint a api:Endpoint .
    ?endpoint api:name ?name .
    ?endpoint api:type ?type
  }

Variable binding failed for ?type:
  No value found for variable 'type' in graph

Suggestion: Check RDF data or query pattern
Available variables: ?name, ?endpoint

Injection Errors

# Shows first non-matching context lines and regex used
Injection Error in src/main.rs:
Pattern 'fn main\(\) {' not found in file

Context (first 10 lines):
  1 | use std::env;
  2 |
  3 | fn main() {
  4 |     println!("Hello, world!");
  5 | }

Regex used: fn main\(\) \{

Suggestion: Check if pattern exists in target file
Try: --dry to preview injection before applying

Hygen Parity

Complete Frontmatter Support

All Hygen frontmatter keys supported 1:1:

---
to: "src/{{type}}s/{{name}}.rs"           # Output path
from: "templates/base.rs"                  # Source template
force: true                               # Overwrite existing
unless_exists: true                       # Skip if exists
inject: true                              # Enable injection mode
before: "// Existing content"             # Inject before pattern
after: "fn main() {"                      # Inject after pattern
prepend: true                             # Prepend to file
append: true                              # Append to file
at_line: 10                               # Inject at line number
eof_last: true                            # Inject before EOF
skip_if: "// GENERATED"                   # Skip if pattern found
sh_before: "echo 'Generating...'"         # Pre-generation shell
sh_after: "cargo fmt"                     # Post-generation shell
---

Regex-Based Injection

# Compiled once for performance
# Deterministic first-match behavior
# All injection modes use regex patterns

# Inject before existing function
before: "fn existing_function\(\) {"

# Inject after struct definition
after: "struct ExistingStruct \{[^}]*\}"

# Skip if already injected
skip_if: "// GENERATED CODE"

Idempotency Guarantees

# Checked before any write operation
# Echo reason in dry-run mode

# If skip_if pattern found:
#   → Skip injection entirely
#   → Log: "Skipped injection: pattern found"

# If unless_exists and file exists:
#   → Skip generation entirely
#   → Log: "Skipped generation: file exists"

Determinism & Previews

Default Diff View

# Diff shown by default in --dry mode
ggen gen cli subcommand name=hello --dry

# Unified diff format:
# --- templates/cli/subcommand/rust.tmpl
# +++ would generate: src/cmds/hello.rs
# @@ -1,4 +1,4 @@
# -use utils::error::Result;
# +use utils::error::Result;
# +
# +#[derive(clap::Args, Debug)]
# +pub struct HelloArgs {
# +    /// Name to greet
# +    #[arg(short, long, default_value = "World")]
# +    pub name: String,
# +}

Content Hashing

# Printed after successful write
ggen gen cli subcommand name=hello

# Output:
# Generated: src/cmds/hello.rs
# Content hash: sha256:a1b2c3d4e5f6...

# Same inputs → identical bytes
# Enables caching and change detection

Stable Ordering

# --idempotency-key seeds stable ordering
ggen gen cli subcommand --idempotency-key "my-project"

# Multi-file generation produces consistent output order
# Same key → same file ordering across runs

Graph (RDF) Integration

Single Shared Graph

#![allow(unused)]
fn main() {
// One Graph instance per pipeline run
// Preloads project + template RDF once
// Cached query results for performance

let mut pipeline = Pipeline::new()?;
pipeline.load_rdf("graphs/project.ttl")?;
pipeline.load_rdf("graphs/cli.ttl")?;
}

SPARQL Functions

// In templates:
{{ sparql(query="SELECT ?name WHERE { ?cmd rdfs:label ?name }") }}

// Named queries with parameters:
{{ sparql_named(name="command_by_name", var="name=hello") }}

// Results available as JSON in templates
{% for cmd in sparql_results %}
pub struct {{cmd.name}}Args;
{% endfor %}

Automatic Prolog Building

# Frontmatter automatically builds prolog:
prefixes:
  cli: "urn:ggen:cli#"
  ex: "http://example.org/"

base: "http://example.org/"

# Generates:
# @prefix cli: <urn:ggen:cli#> .
# @prefix ex: <http://example.org/> .
# @base <http://example.org/> .

Template Helpers

Text Transformation Filters

// All Inflector + Heck filters available:
{{ name | camel }}           // userName
{{ name | pascal }}          // UserName
{{ name | snake }}           // user_name
{{ name | kebab }}           // user-name
{{ name | shouty_snake }}    // USER_NAME
{{ name | plural }}          // users
{{ name | singular }}        // user

Built-in Functions

// Local name from IRI
{{ local(iri="<http://example.org/User>") }}  // "User"

// Slug generation
{{ slug(text="Hello World!") }}              // "hello-world"

// Indentation control
{{ indent(text="line1\nline2", n=2) }}       // "  line1\n  line2"

// Newline insertion
{{ newline(n=3) }}                           // "\n\n\n"

Safety & Guardrails

Safe Write Root

# Safe write root = current directory
ggen gen cli subcommand name=hello

# Generates: ./src/cmds/hello.rs
# Cannot write outside project root

# Override with --unsafe-write (requires explicit opt-in)
ggen gen cli subcommand name=hello --unsafe-write /tmp/output

Shell Hook Controls

# Off by default for security
sh_before: "echo 'Generating...'"    # Not executed
sh_after: "cargo fmt"                # Not executed

# Enable with --allow-sh flag
ggen gen template --allow-sh

# Always preview in --dry mode
ggen gen template --dry --allow-sh  # Shows what shell commands would run

Network Restrictions

# No network during render by default
# Prevents malicious template behavior

# Enable network for gpack fetching only
ggen add io.ggen.rust.cli-subcommand --net

# Network only for registry operations
# Templates cannot make HTTP requests

Configuration & Discovery

Project Configuration

# ggen.toml - single source of project config
[project]
name = "My CLI Tool"
version = "0.1.0"

[prefixes]
ex = "http://example.org/"

[rdf]
files = ["templates/**/graphs/*.ttl"]
inline = ["@prefix ex: <http://example.org/> . ex:Project a ex:Tool ."]

[preset]
vars = { author = "Team", license = "MIT" }

Health Check

# Validate entire project setup
ggen doctor

# Checks:
# ✓ ggen.toml syntax
# ✓ Template frontmatter validity
# ✓ RDF graph well-formedness
# ✓ SPARQL query syntax
# ✓ File path resolution
# ✓ Gpack compatibility

Path Resolution

# All paths resolved relative to ggen.toml location
# Printed in --trace mode for debugging

# Project structure:
# my-project/
#   ggen.toml
#   graphs/cli.ttl
#   templates/cli/subcommand/rust.tmpl

# Paths automatically resolved:
# graphs/cli.ttl → /path/to/my-project/graphs/cli.ttl
# templates/cli/subcommand/rust.tmpl → /path/to/my-project/templates/cli/subcommand/rust.tmpl

Testing Infrastructure

Golden Test System

# Run golden tests for specific template
ggen test cli/subcommand/rust.tmpl

# Test structure:
# tests/golden/cli/subcommand/rust.tmpl/
#   input.toml     # Variables for test
#   output.rs      # Expected output

# Update goldens after changes
ggen test cli/subcommand/rust.tmpl --update-goldens

Test Organization

# tests/golden/cli/subcommand/rust.tmpl/input.toml
name = "hello"
description = "Print a greeting"
author = "Team"

# Generates and compares against:
# tests/golden/cli/subcommand/rust.tmpl/output.rs

Pipeline Integration

Builder Pattern

#![allow(unused)]
fn main() {
// Fluent API for pipeline configuration
let pipeline = Pipeline::builder()
    .with_rdf("graphs/project.ttl")
    .with_prefixes([("ex", "http://example.org/")])
    .with_templates_dir("custom-templates")
    .with_cache_strategy(CacheStrategy::Memory)
    .build()?;
}

Single Render Call

#![allow(unused)]
fn main() {
// One method handles everything
let plan = pipeline.render_file(
    "templates/cli/subcommand/rust.tmpl",
    &variables,
    DryRun::No
)?;

// Apply or preview
plan.apply()?;           // Write files
plan.print_diff()?;      // Show diff
}

Sensible Defaults

Pre-filled Context

// Available in all templates:
{{ cwd }}              // Current working directory
{{ env.HOME }}         // User home directory
{{ git.branch }}       // Current git branch
{{ git.user }}         // Git user name
{{ now }}              // RFC3339 timestamp

Flexible Output Control

# to: can be null to skip file generation
to: null               # No file written

# from: overrides template body
from: "base-template.rs"  # Use different source

# Works with all injection modes
inject: true
before: "fn main() {"

Error Recovery

Graceful Degradation

# Missing optional RDF → continues with empty graph
# Invalid SPARQL query → shows helpful error
# Template syntax error → precise location + suggestion
# Path traversal attempt → clear security message

Recovery Suggestions

# Every error includes actionable next steps
Error: Template 'missing.tmpl' not found
Suggestion: Available templates:
  - cli/subcommand/rust.tmpl
  - api/endpoint/typescript.tmpl
  - Run 'ggen list' to see all options

Performance Optimizations

Streaming & Caching

# Large RDF graphs processed incrementally
# Repeated queries cached automatically
# Template compilation cached per-run
# File I/O batched for efficiency

Memory Efficiency

# Bounded caches prevent memory leaks
# Stream processing for large files
# Minimal allocations in hot paths
# LTO enabled in release builds

Development Workflow

Rapid Iteration Cycle

# 1. Edit template
# 2. Test with --dry
# 3. Check --trace output
# 4. Iterate quickly

ggen gen template --dry --trace
# → See exactly what happens
# → Fix issues immediately
# → No waiting for file writes

Template Debugging

# Debug template logic step by step
GGEN_TRACE=1 ggen gen template

# See:
# - Frontmatter resolution
# - Variable precedence
# - SPARQL query execution
# - Template rendering
# - File path calculation

Integration Benefits

IDE Support

# Rich error messages work in IDEs
# Template syntax highlighting
# Variable name completion
# Live preview of generated code
# Source maps for debugging

Tool Integration

# JSON output for CI/CD
ggen gen template --dry --json > plan.json

# Machine-readable error format
# Structured logging for dashboards
# Metrics collection hooks

Best Practices

Template Organization

templates/
  cli/
    subcommand/
      rust.tmpl
      python.tmpl
      bash.tmpl
  api/
    endpoint/
      rust.tmpl
      typescript.tmpl
  component/
    mod.rs.tmpl

Variable Naming

# Use descriptive variable names
vars:
  component_name: "UserService"
  api_version: "v1"
  author_email: "team@example.com"

# Avoid generic names like 'name', 'type'
# Use domain-specific names

Error Prevention

# Validate early with schemas
# Use RDF shapes for data validation
# Test templates with golden tests
# Use --dry before --allow-sh

This comprehensive DX system provides fast feedback, predictable outputs, clear error messages, and zero ceremony—exactly the developer experience lift that covers 80% of use cases while maintaining the power and flexibility needed for complex scenarios.