ggen 1.2.0

ggen is a deterministic, language-agnostic code generation framework that treats software artifacts as projections of knowledge graphs.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**

- [Multi-language CLI subcommand](#multi-language-cli-subcommand)
  - [Using Marketplace Gpacks (Recommended)](#using-marketplace-gpacks-recommended)
    - [1. Install Language-Specific Gpacks](#1-install-language-specific-gpacks)
    - [2. Generate Across Languages](#2-generate-across-languages)
    - [3. Verify Deterministic Output](#3-verify-deterministic-output)
  - [Using Local Templates (Advanced)](#using-local-templates-advanced)
  - [Determinism Verification](#determinism-verification)
    - [Gpack Version Locking](#gpack-version-locking)
    - [Lockfile Management](#lockfile-management)
  - [Cross-Language Consistency](#cross-language-consistency)
  - [Best Practices](#best-practices)
    - [Gpack Selection](#gpack-selection)
    - [Version Management](#version-management)
    - [Testing Multi-Language Output](#testing-multi-language-output)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# Multi-language CLI subcommand

## Using Marketplace Gpacks (Recommended)

Generate the same CLI subcommand across multiple languages using curated gpacks.

### 1. Install Language-Specific Gpacks

```bash
# Install gpacks for different languages
ggen add io.ggen.rust.cli-subcommand
ggen add io.ggen.python.cli-subcommand
ggen add io.ggen.bash.cli-subcommand
ggen add io.ggen.go.cli-subcommand
```

### 2. Generate Across Languages

```bash
# Generate Rust CLI subcommand
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello description="Print a greeting"

# Generate Python CLI subcommand
ggen gen io.ggen.python.cli-subcommand:cli/subcommand/python.tmpl name=hello description="Print a greeting"

# Generate Bash CLI subcommand
ggen gen io.ggen.bash.cli-subcommand:cli/subcommand/bash.tmpl name=hello description="Print a greeting"

# Generate Go CLI subcommand
ggen gen io.ggen.go.cli-subcommand:cli/subcommand/go.tmpl name=hello description="Print a greeting"
```

### 3. Verify Deterministic Output

```bash
# Check that all outputs are consistent
ls -la src/cmds/hello.rs commands/hello.py commands/hello.sh cmd/hello.go

# Verify determinism by regenerating
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello description="Print a greeting"
# Should produce identical output
```

Produces:
```
src/cmds/hello.rs
commands/hello.py
commands/hello.sh
cmd/hello.go
```

## Using Local Templates (Advanced)

For custom multi-language generation using local templates:

```bash
ggen gen cli subcommand --vars cmd=hello summary="Print a greeting"
```

Produces, if templates exist:
```
src/cmds/hello.rs
commands/hello.py
commands/hello.sh
```

## Determinism Verification

### Gpack Version Locking

Gpacks ensure determinism through version locking:

```bash
# Check installed versions
ggen packs

# Output:
# ID                                    VERSION    KIND       TAGS
# io.ggen.rust.cli-subcommand           0.2.1      template   rust, cli, clap
# io.ggen.python.cli-subcommand         0.1.8      template   python, cli, click
# io.ggen.bash.cli-subcommand            0.1.2      template   bash, cli, getopts
```

### Lockfile Management

```bash
# View lockfile
cat ggen.lock

# Update to latest compatible versions
ggen update

# Verify determinism
ggen gen io.ggen.rust.cli-subcommand:cli/subcommand/rust.tmpl name=hello description="Print a greeting" --dry
```

## Cross-Language Consistency

All generated subcommands share the same semantic model:

- **Same RDF ontology** across all languages
- **Consistent variable binding** via SPARQL queries
- **Identical frontmatter** structure
- **Deterministic output** through version locking

## Best Practices

### Gpack Selection

```bash
# Search for multi-language gpacks
ggen search cli subcommand

# Look for gpacks with multiple language support
ggen show io.ggen.rust.cli-subcommand
```

### Version Management

```bash
# Pin specific versions for production
ggen add io.ggen.rust.cli-subcommand@0.2.1
ggen add io.ggen.python.cli-subcommand@0.1.8

# Update carefully
ggen update --dry  # Preview updates
ggen update        # Apply updates
```

### Testing Multi-Language Output

```bash
# Test all languages
for lang in rust python bash go; do
  ggen gen io.ggen.${lang}.cli-subcommand:cli/subcommand/${lang}.tmpl name=test description="Test command"
done

# Verify consistency
diff <(grep -o 'name.*test' src/cmds/test.rs) <(grep -o 'name.*test' commands/test.py)
```

Same RDF + seed + gpack versions ⇒ byte-identical outputs across all languages.