0
# C++ Wrapper API
1

2
The C++ wrapper provides a modern, object-oriented interface to Jsonnet with RAII memory management, exception safety, and STL integration. It wraps the C library with a convenient class-based API.
3

4
## Capabilities
5

6
### Jsonnet Class
7

8
Main class providing high-level access to Jsonnet functionality with automatic resource management.
9

10
```cpp { .api }
11
/**
12
 * Main Jsonnet class providing object-oriented access to Jsonnet functionality
13
 */
14
class Jsonnet {
15
public:
16
    /**
17
     * Constructor - creates uninitialized Jsonnet instance
18
     */
19
    Jsonnet();
20
    
21
    /**
22
     * Destructor - automatically cleans up VM and resources
23
     */
24
    ~Jsonnet();
25
    
26
    /**
27
     * Return the version string of the Jsonnet interpreter
28
     * @returns Version string conforming to semantic versioning
29
     */
30
    static std::string version();
31
    
32
    /**
33
     * Initialize the Jsonnet VM - must be called before other methods
34
     * @returns true if VM was successfully initialized, false otherwise
35
     */
36
    bool init();
37
};
38
```
39

40
### Configuration Methods
41

42
Methods for configuring VM behavior and performance characteristics.
43

44
```cpp { .api }
45
/**
46
 * Set the maximum stack depth
47
 * @param depth Maximum stack depth
48
 */
49
void setMaxStack(uint32_t depth);
50

51
/**
52
 * Set the number of objects required before a garbage collection cycle is allowed
53
 * @param objects Minimum objects threshold
54
 */
55
void setGcMinObjects(uint32_t objects);
56

57
/**
58
 * Run the garbage collector after this amount of growth in the number of objects
59
 * @param growth Growth trigger ratio
60
 */
61
void setGcGrowthTrigger(double growth);
62

63
/**
64
 * Set whether to expect a string as output and don't JSON encode it
65
 * @param string_output true to enable string output, false for JSON output
66
 */
67
void setStringOutput(bool string_output);
68

69
/**
70
 * Set the number of lines of stack trace to display (0 to display all)
71
 * @param lines Maximum trace lines
72
 */
73
void setMaxTrace(uint32_t lines);
74

75
/**
76
 * Add to the default import callback's library search path
77
 * @param path Import search path to add
78
 */
79
void addImportPath(const std::string& path);
80
```
81

82
### Variable Binding Methods
83

84
Methods for binding external variables and top-level arguments accessible from Jsonnet code.
85

86
```cpp { .api }
87
/**
88
 * Bind a string top-level argument for a top-level parameter
89
 * @param key Parameter name
90
 * @param value String value (copied)
91
 */
92
void bindTlaVar(const std::string& key, const std::string& value);
93

94
/**
95
 * Bind a code top-level argument for a top-level parameter
96
 * @param key Parameter name
97
 * @param value Jsonnet code to evaluate (copied)
98
 */
99
void bindTlaCodeVar(const std::string& key, const std::string& value);
100

101
/**
102
 * Bind a Jsonnet external variable to the given string value
103
 * @param key Variable name
104
 * @param value String value (copied)
105
 */
106
void bindExtVar(const std::string& key, const std::string& value);
107

108
/**
109
 * Bind a Jsonnet external code variable to the given value
110
 * @param key Variable name
111
 * @param value Jsonnet code to evaluate (copied)
112
 */
113
void bindExtCodeVar(const std::string& key, const std::string& value);
114
```
115

116
### Evaluation Methods
117

118
Core methods for evaluating Jsonnet code with different output modes.
119

120
```cpp { .api }
121
/**
122
 * Evaluate a file containing Jsonnet code to return a JSON string
123
 * @param filename Path to file containing Jsonnet code
124
 * @param output Pointer to string to contain the output
125
 * @returns true if successfully evaluated, false on error (check lastError())
126
 */
127
bool evaluateFile(const std::string& filename, std::string* output);
128

129
/**
130
 * Evaluate a string containing Jsonnet code to return a JSON string
131
 * @param filename Path to file (used in error messages)
132
 * @param snippet Jsonnet code to execute
133
 * @param output Pointer to string to contain the output
134
 * @returns true if successfully evaluated, false on error (check lastError())
135
 */
136
bool evaluateSnippet(const std::string& filename, const std::string& snippet, std::string* output);
137

138
/**
139
 * Evaluate a file containing Jsonnet code, return multiple JSON files
140
 * @param filename Path to file containing Jsonnet code
141
 * @param outputs Pointer to map which will store filename to JSON string mapping
142
 * @returns true if successfully evaluated, false on error (check lastError())
143
 */
144
bool evaluateFileMulti(const std::string& filename, std::map<std::string, std::string>* outputs);
145

146
/**
147
 * Evaluate a string containing Jsonnet code, return multiple JSON files
148
 * @param filename Path to file (used in error messages)
149
 * @param snippet Jsonnet code to execute
150
 * @param outputs Pointer to map which will store filename to JSON string mapping
151
 * @returns true if successfully evaluated, false on error (check lastError())
152
 */
153
bool evaluateSnippetMulti(const std::string& filename, const std::string& snippet, std::map<std::string, std::string>* outputs);
154
```
155

156
### Error Handling
157

158
Method for retrieving detailed error information.
159

160
```cpp { .api }
161
/**
162
 * Return the last error message from Jsonnet evaluation
163
 * @returns Error message string, empty if no error
164
 */
165
std::string lastError() const;
166
```
167

168
## Usage Examples
169

170
**Basic usage:**
171
```cpp
172
#include "libjsonnet++.h"
173
#include <iostream>
174

175
int main() {
176
    jsonnet::Jsonnet jsonnet;
177
    if (!jsonnet.init()) {
178
        std::cerr << "Failed to initialize Jsonnet" << std::endl;
179
        return 1;
180
    }
181
    
182
    std::string result;
183
    bool success = jsonnet.evaluateSnippet("example.jsonnet", 
184
        "{ greeting: 'Hello World!' }", &result);
185
    
186
    if (success) {
187
        std::cout << result << std::endl;
188
    } else {
189
        std::cerr << "Error: " << jsonnet.lastError() << std::endl;
190
    }
191
    
192
    return success ? 0 : 1;
193
}
194
```
195

196
**With configuration and variables:**
197
```cpp
198
jsonnet::Jsonnet jsonnet;
199
jsonnet.init();
200

201
// Configure VM
202
jsonnet.setMaxStack(1000);
203
jsonnet.setStringOutput(false);
204
jsonnet.addImportPath("/usr/local/lib/jsonnet");
205

206
// Bind variables
207
jsonnet.bindExtVar("environment", "production");
208
jsonnet.bindExtVar("version", "1.2.3");
209
jsonnet.bindTlaVar("cluster", "us-west-1");
210

211
std::string result;
212
bool success = jsonnet.evaluateFile("config.jsonnet", &result);
213
```
214

215
**Multi-file evaluation:**
216
```cpp
217
jsonnet::Jsonnet jsonnet;
218
jsonnet.init();
219

220
std::map<std::string, std::string> outputs;
221
bool success = jsonnet.evaluateSnippet("multi.jsonnet",
222
    R"({
223
        "config.json": { port: 8080 },
224
        "secrets.json": { api_key: "secret123" }
225
    })", &outputs);
226

227
if (success) {
228
    for (const auto& pair : outputs) {
229
        std::cout << "File: " << pair.first << std::endl;
230
        std::cout << "Content: " << pair.second << std::endl;
231
    }
232
}
233
```
234

235
**Error handling:**
236
```cpp
237
jsonnet::Jsonnet jsonnet;
238
jsonnet.init();
239

240
std::string result;
241
bool success = jsonnet.evaluateSnippet("invalid.jsonnet", 
242
    "{ invalid: syntax error }", &result);
243

244
if (!success) {
245
    std::cerr << "Evaluation failed: " << jsonnet.lastError() << std::endl;
246
    // Error message includes line numbers and context
247
}
248
```
249

250
**Version checking:**
251
```cpp
252
std::string version = jsonnet::Jsonnet::version();
253
std::cout << "Jsonnet version: " << version << std::endl;
254
// Output: Jsonnet version: v0.21.0
255
```
256

257
## Integration Examples
258

259
**With CMake:**
260
```cmake
261
find_package(jsonnet REQUIRED)
262
target_link_libraries(myapp jsonnet)
263
```
264

265
**Exception safety:**
266
```cpp
267
void processConfig(const std::string& filename) {
268
    jsonnet::Jsonnet jsonnet;
269
    if (!jsonnet.init()) {
270
        throw std::runtime_error("Failed to initialize Jsonnet");
271
    }
272
    
273
    std::string result;
274
    if (!jsonnet.evaluateFile(filename, &result)) {
275
        throw std::runtime_error("Evaluation failed: " + jsonnet.lastError());
276
    }
277
    
278
    // Process result...
279
    // Destructor automatically cleans up VM
280
}
281
```