0
# C Library API
1

2
The C library provides the core low-level interface to Jsonnet, offering direct access to the virtual machine, evaluation functions, and extension capabilities. This API serves as the foundation for all higher-level language bindings.
3

4
## Capabilities
5

6
### VM Management
7

8
Functions for creating, configuring, and destroying Jsonnet virtual machine instances.
9

10
```c { .api }
11
/**
12
 * Create a new Jsonnet virtual machine.
13
 * @returns Pointer to new VM instance, must be freed with jsonnet_destroy()
14
 */
15
struct JsonnetVm *jsonnet_make(void);
16

17
/**
18
 * Destroy VM and free all associated resources.
19
 * @param vm VM instance to destroy
20
 */
21
void jsonnet_destroy(struct JsonnetVm *vm);
22

23
/**
24
 * Get the version string of the Jsonnet interpreter.
25
 * @returns Version string conforming to semantic versioning
26
 */
27
const char *jsonnet_version(void);
28

29
/**
30
 * Allocate, resize, or free memory managed by the VM.
31
 * @param vm VM instance
32
 * @param buf Buffer to resize, or NULL to allocate new
33
 * @param sz New size, or 0 to free
34
 * @returns Allocated buffer or NULL if sz was 0
35
 */
36
char *jsonnet_realloc(struct JsonnetVm *vm, char *buf, size_t sz);
37
```
38

39
### VM Configuration
40

41
Functions for configuring VM behavior including stack limits, garbage collection, and output modes.
42

43
```c { .api }
44
/**
45
 * Set the maximum stack depth.
46
 * @param vm VM instance
47
 * @param v Maximum stack depth
48
 */
49
void jsonnet_max_stack(struct JsonnetVm *vm, unsigned v);
50

51
/**
52
 * Set the number of objects required before a garbage collection cycle is allowed.
53
 * @param vm VM instance
54
 * @param v Minimum objects threshold
55
 */
56
void jsonnet_gc_min_objects(struct JsonnetVm *vm, unsigned v);
57

58
/**
59
 * Run the garbage collector after this amount of growth in the number of objects.
60
 * @param vm VM instance
61
 * @param v Growth trigger ratio
62
 */
63
void jsonnet_gc_growth_trigger(struct JsonnetVm *vm, double v);
64

65
/**
66
 * Expect a string as output and don't JSON encode it.
67
 * @param vm VM instance
68
 * @param v 1 to enable string output, 0 for JSON output
69
 */
70
void jsonnet_string_output(struct JsonnetVm *vm, int v);
71

72
/**
73
 * Set the number of lines of stack trace to display (0 for all of them).
74
 * @param vm VM instance
75
 * @param v Maximum trace lines
76
 */
77
void jsonnet_max_trace(struct JsonnetVm *vm, unsigned v);
78
```
79

80
### Variable and Parameter Binding
81

82
Functions for binding external variables and top-level arguments that can be accessed from Jsonnet code.
83

84
```c { .api }
85
/**
86
 * Bind a Jsonnet external var to the given string.
87
 * @param vm VM instance
88
 * @param key Variable name
89
 * @param val String value (copied)
90
 */
91
void jsonnet_ext_var(struct JsonnetVm *vm, const char *key, const char *val);
92

93
/**
94
 * Bind a Jsonnet external var to the given code.
95
 * @param vm VM instance
96
 * @param key Variable name
97
 * @param val Jsonnet code to evaluate (copied)
98
 */
99
void jsonnet_ext_code(struct JsonnetVm *vm, const char *key, const char *val);
100

101
/**
102
 * Bind a string top-level argument for a top-level parameter.
103
 * @param vm VM instance
104
 * @param key Parameter name
105
 * @param val String value (copied)
106
 */
107
void jsonnet_tla_var(struct JsonnetVm *vm, const char *key, const char *val);
108

109
/**
110
 * Bind a code top-level argument for a top-level parameter.
111
 * @param vm VM instance
112
 * @param key Parameter name
113
 * @param val Jsonnet code to evaluate (copied)
114
 */
115
void jsonnet_tla_code(struct JsonnetVm *vm, const char *key, const char *val);
116

117
/**
118
 * Add to the default import callback's library search path.
119
 * @param vm VM instance
120
 * @param v Path to add (last to first search order)
121
 */
122
void jsonnet_jpath_add(struct JsonnetVm *vm, const char *v);
123
```
124

125
### Core Evaluation Functions
126

127
Primary functions for evaluating Jsonnet code from files or strings with various output modes.
128

129
```c { .api }
130
/**
131
 * Evaluate a file containing Jsonnet code, return a JSON string.
132
 * @param vm VM instance
133
 * @param filename Path to file containing Jsonnet code
134
 * @param error Output parameter set to 1 on error, 0 on success
135
 * @returns JSON string on success, error message on failure (use jsonnet_realloc to free)
136
 */
137
char *jsonnet_evaluate_file(struct JsonnetVm *vm, const char *filename, int *error);
138

139
/**
140
 * Evaluate a string containing Jsonnet code, return a JSON string.
141
 * @param vm VM instance
142
 * @param filename Path to file (used in error messages)
143
 * @param snippet Jsonnet code to execute
144
 * @param error Output parameter set to 1 on error, 0 on success
145
 * @returns JSON string on success, error message on failure (use jsonnet_realloc to free)
146
 */
147
char *jsonnet_evaluate_snippet(struct JsonnetVm *vm, const char *filename, const char *snippet, int *error);
148

149
/**
150
 * Evaluate a file containing Jsonnet code, return multiple named JSON files.
151
 * @param vm VM instance
152
 * @param filename Path to file containing Jsonnet code
153
 * @param error Output parameter set to 1 on error, 0 on success
154
 * @returns Sequence of filename/JSON pairs separated by \\0, terminated with \\0\\0 (use jsonnet_realloc to free)
155
 */
156
char *jsonnet_evaluate_file_multi(struct JsonnetVm *vm, const char *filename, int *error);
157

158
/**
159
 * Evaluate a string containing Jsonnet code, return multiple named JSON files.
160
 * @param vm VM instance
161
 * @param filename Path to file (used in error messages)
162
 * @param snippet Jsonnet code to execute
163
 * @param error Output parameter set to 1 on error, 0 on success
164
 * @returns Sequence of filename/JSON pairs separated by \\0, terminated with \\0\\0 (use jsonnet_realloc to free)
165
 */
166
char *jsonnet_evaluate_snippet_multi(struct JsonnetVm *vm, const char *filename, const char *snippet, int *error);
167

168
/**
169
 * Evaluate a file containing Jsonnet code, return a JSON stream.
170
 * @param vm VM instance
171
 * @param filename Path to file containing Jsonnet code
172
 * @param error Output parameter set to 1 on error, 0 on success
173
 * @returns Sequence of JSON strings separated by \\0, terminated with \\0\\0 (use jsonnet_realloc to free)
174
 */
175
char *jsonnet_evaluate_file_stream(struct JsonnetVm *vm, const char *filename, int *error);
176

177
/**
178
 * Evaluate a string containing Jsonnet code, return a JSON stream.
179
 * @param vm VM instance
180
 * @param filename Path to file (used in error messages)
181
 * @param snippet Jsonnet code to execute
182
 * @param error Output parameter set to 1 on error, 0 on success
183
 * @returns Sequence of JSON strings separated by \\0, terminated with \\0\\0 (use jsonnet_realloc to free)
184
 */
185
char *jsonnet_evaluate_snippet_stream(struct JsonnetVm *vm, const char *filename, const char *snippet, int *error);
186
```
187

188
### JSON Value Manipulation
189

190
Functions for working with JSON values in native callbacks, enabling conversion between C types and Jsonnet values.
191

192
```c { .api }
193
/**
194
 * Extract string from JSON value.
195
 * @param vm VM instance
196
 * @param v JSON value
197
 * @returns UTF8 string or NULL if not a string
198
 */
199
const char *jsonnet_json_extract_string(struct JsonnetVm *vm, const struct JsonnetJsonValue *v);
200

201
/**
202
 * Extract number from JSON value.
203
 * @param vm VM instance
204
 * @param v JSON value
205
 * @param out Output parameter for number value
206
 * @returns 1 if value is number, 0 otherwise
207
 */
208
int jsonnet_json_extract_number(struct JsonnetVm *vm, const struct JsonnetJsonValue *v, double *out);
209

210
/**
211
 * Extract boolean from JSON value.
212
 * @param vm VM instance
213
 * @param v JSON value
214
 * @returns 0 if false, 1 if true, 2 if not a boolean
215
 */
216
int jsonnet_json_extract_bool(struct JsonnetVm *vm, const struct JsonnetJsonValue *v);
217

218
/**
219
 * Check if JSON value is null.
220
 * @param vm VM instance
221
 * @param v JSON value
222
 * @returns 1 if null, 0 otherwise
223
 */
224
int jsonnet_json_extract_null(struct JsonnetVm *vm, const struct JsonnetJsonValue *v);
225

226
/**
227
 * Create JSON string value.
228
 * @param vm VM instance
229
 * @param v UTF8 string
230
 * @returns JSON string value
231
 */
232
struct JsonnetJsonValue *jsonnet_json_make_string(struct JsonnetVm *vm, const char *v);
233

234
/**
235
 * Create JSON number value.
236
 * @param vm VM instance
237
 * @param v Number value
238
 * @returns JSON number value
239
 */
240
struct JsonnetJsonValue *jsonnet_json_make_number(struct JsonnetVm *vm, double v);
241

242
/**
243
 * Create JSON boolean value.
244
 * @param vm VM instance
245
 * @param v Boolean value (1 or 0)
246
 * @returns JSON boolean value
247
 */
248
struct JsonnetJsonValue *jsonnet_json_make_bool(struct JsonnetVm *vm, int v);
249

250
/**
251
 * Create JSON null value.
252
 * @param vm VM instance
253
 * @returns JSON null value
254
 */
255
struct JsonnetJsonValue *jsonnet_json_make_null(struct JsonnetVm *vm);
256

257
/**
258
 * Create empty JSON array.
259
 * @param vm VM instance
260
 * @returns JSON array value
261
 */
262
struct JsonnetJsonValue *jsonnet_json_make_array(struct JsonnetVm *vm);
263

264
/**
265
 * Create empty JSON object.
266
 * @param vm VM instance
267
 * @returns JSON object value
268
 */
269
struct JsonnetJsonValue *jsonnet_json_make_object(struct JsonnetVm *vm);
270

271
/**
272
 * Add element to JSON array.
273
 * @param vm VM instance
274
 * @param arr JSON array
275
 * @param v Value to append
276
 */
277
void jsonnet_json_array_append(struct JsonnetVm *vm, struct JsonnetJsonValue *arr, struct JsonnetJsonValue *v);
278

279
/**
280
 * Add field to JSON object.
281
 * @param vm VM instance
282
 * @param obj JSON object
283
 * @param f Field name
284
 * @param v Field value
285
 */
286
void jsonnet_json_object_append(struct JsonnetVm *vm, struct JsonnetJsonValue *obj, const char *f, struct JsonnetJsonValue *v);
287

288
/**
289
 * Clean up JSON value and all nested values.
290
 * @param vm VM instance
291
 * @param v JSON value to destroy
292
 */
293
void jsonnet_json_destroy(struct JsonnetVm *vm, struct JsonnetJsonValue *v);
294
```
295

296
### Callback Registration
297

298
Functions for registering custom import handlers and native function extensions.
299

300
```c { .api }
301
/**
302
 * Override the callback used to locate imports.
303
 * @param vm VM instance
304
 * @param cb Import callback function
305
 * @param ctx User context pointer passed to callback
306
 */
307
void jsonnet_import_callback(struct JsonnetVm *vm, JsonnetImportCallback *cb, void *ctx);
308

309
/**
310
 * Register a native extension function.
311
 * @param vm VM instance
312
 * @param name Function name as visible to Jsonnet code
313
 * @param cb Native callback function (must be pure)
314
 * @param ctx User context pointer passed to callback
315
 * @param params NULL-terminated array of parameter names
316
 */
317
void jsonnet_native_callback(struct JsonnetVm *vm, const char *name, JsonnetNativeCallback *cb, void *ctx, const char *const *params);
318
```
319

320
## Types
321

322
Core types and callback function pointers:
323

324
```c { .api }
325
/**
326
 * Jsonnet virtual machine context (opaque)
327
 */
328
struct JsonnetVm;
329

330
/**
331
 * Opaque JSON value type for native callbacks
332
 */
333
struct JsonnetJsonValue;
334

335
/**
336
 * Callback for custom import handling.
337
 * @param ctx User context pointer
338
 * @param base Directory containing importing code
339
 * @param rel Relative import path
340
 * @param found_here Output parameter for resolved absolute path
341
 * @param buf Output parameter for file content
342
 * @param buflen Output parameter for content length
343
 * @returns 0 on success, 1 on failure
344
 */
345
typedef int JsonnetImportCallback(void *ctx, const char *base, const char *rel,
346
                                  char **found_here, char **buf, size_t *buflen);
347

348
/**
349
 * Callback for native function extensions.
350
 * @param ctx User context pointer
351
 * @param argv Array of argument values
352
 * @param success Output parameter: 1 for success, 0 for failure
353
 * @returns Function result on success, error message on failure
354
 */
355
typedef struct JsonnetJsonValue *JsonnetNativeCallback(void *ctx,
356
                                                       const struct JsonnetJsonValue *const *argv,
357
                                                       int *success);
358
```
359

360
## Usage Examples
361

362
**Basic evaluation:**
363
```c
364
struct JsonnetVm *vm = jsonnet_make();
365
int error;
366
char *result = jsonnet_evaluate_snippet(vm, "test.jsonnet", "{ hello: 'world' }", &error);
367
if (!error) {
368
    printf("%s\\n", result);
369
}
370
jsonnet_realloc(vm, result, 0);
371
jsonnet_destroy(vm);
372
```
373

374
**With external variables:**
375
```c
376
struct JsonnetVm *vm = jsonnet_make();
377
jsonnet_ext_var(vm, "name", "Alice");
378
jsonnet_ext_var(vm, "env", "production");
379
int error;
380
char *result = jsonnet_evaluate_snippet(vm, "config.jsonnet", 
381
    "{ greeting: 'Hello ' + std.extVar('name'), environment: std.extVar('env') }", &error);
382
```
383

384
**Multi-file output:**
385
```c
386
struct JsonnetVm *vm = jsonnet_make();
387
int error;
388
char *result = jsonnet_evaluate_snippet(vm, "multi.jsonnet",
389
    "{ 'file1.json': { a: 1 }, 'file2.json': { b: 2 } }", &error);
390
// Parse null-separated filename/content pairs
391
```