tessl/pypi-jsonnet

Jsonnet is a data templating language that extends JSON with variables, conditionals, functions, and imports for configuration management

—

Pending

Overview

Eval results

Files

C Library API

Name: tessl/pypi-jsonnet
Author: tessl

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.

Capabilities

VM Management

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

/**
 * Create a new Jsonnet virtual machine.
 * @returns Pointer to new VM instance, must be freed with jsonnet_destroy()
 */
struct JsonnetVm *jsonnet_make(void);

/**
 * Destroy VM and free all associated resources.
 * @param vm VM instance to destroy
 */
void jsonnet_destroy(struct JsonnetVm *vm);

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

/**
 * Allocate, resize, or free memory managed by the VM.
 * @param vm VM instance
 * @param buf Buffer to resize, or NULL to allocate new
 * @param sz New size, or 0 to free
 * @returns Allocated buffer or NULL if sz was 0
 */
char *jsonnet_realloc(struct JsonnetVm *vm, char *buf, size_t sz);

VM Configuration

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

/**
 * Set the maximum stack depth.
 * @param vm VM instance
 * @param v Maximum stack depth
 */
void jsonnet_max_stack(struct JsonnetVm *vm, unsigned v);

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

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

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

/**
 * Set the number of lines of stack trace to display (0 for all of them).
 * @param vm VM instance
 * @param v Maximum trace lines
 */
void jsonnet_max_trace(struct JsonnetVm *vm, unsigned v);

Variable and Parameter Binding

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

/**
 * Bind a Jsonnet external var to the given string.
 * @param vm VM instance
 * @param key Variable name
 * @param val String value (copied)
 */
void jsonnet_ext_var(struct JsonnetVm *vm, const char *key, const char *val);

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

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

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

/**
 * Add to the default import callback's library search path.
 * @param vm VM instance
 * @param v Path to add (last to first search order)
 */
void jsonnet_jpath_add(struct JsonnetVm *vm, const char *v);

Core Evaluation Functions

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

/**
 * Evaluate a file containing Jsonnet code, return a JSON string.
 * @param vm VM instance
 * @param filename Path to file containing Jsonnet code
 * @param error Output parameter set to 1 on error, 0 on success
 * @returns JSON string on success, error message on failure (use jsonnet_realloc to free)
 */
char *jsonnet_evaluate_file(struct JsonnetVm *vm, const char *filename, int *error);

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

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

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

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

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

JSON Value Manipulation

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

/**
 * Extract string from JSON value.
 * @param vm VM instance
 * @param v JSON value
 * @returns UTF8 string or NULL if not a string
 */
const char *jsonnet_json_extract_string(struct JsonnetVm *vm, const struct JsonnetJsonValue *v);

/**
 * Extract number from JSON value.
 * @param vm VM instance
 * @param v JSON value
 * @param out Output parameter for number value
 * @returns 1 if value is number, 0 otherwise
 */
int jsonnet_json_extract_number(struct JsonnetVm *vm, const struct JsonnetJsonValue *v, double *out);

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

/**
 * Check if JSON value is null.
 * @param vm VM instance
 * @param v JSON value
 * @returns 1 if null, 0 otherwise
 */
int jsonnet_json_extract_null(struct JsonnetVm *vm, const struct JsonnetJsonValue *v);

/**
 * Create JSON string value.
 * @param vm VM instance
 * @param v UTF8 string
 * @returns JSON string value
 */
struct JsonnetJsonValue *jsonnet_json_make_string(struct JsonnetVm *vm, const char *v);

/**
 * Create JSON number value.
 * @param vm VM instance
 * @param v Number value
 * @returns JSON number value
 */
struct JsonnetJsonValue *jsonnet_json_make_number(struct JsonnetVm *vm, double v);

/**
 * Create JSON boolean value.
 * @param vm VM instance
 * @param v Boolean value (1 or 0)
 * @returns JSON boolean value
 */
struct JsonnetJsonValue *jsonnet_json_make_bool(struct JsonnetVm *vm, int v);

/**
 * Create JSON null value.
 * @param vm VM instance
 * @returns JSON null value
 */
struct JsonnetJsonValue *jsonnet_json_make_null(struct JsonnetVm *vm);

/**
 * Create empty JSON array.
 * @param vm VM instance
 * @returns JSON array value
 */
struct JsonnetJsonValue *jsonnet_json_make_array(struct JsonnetVm *vm);

/**
 * Create empty JSON object.
 * @param vm VM instance
 * @returns JSON object value
 */
struct JsonnetJsonValue *jsonnet_json_make_object(struct JsonnetVm *vm);

/**
 * Add element to JSON array.
 * @param vm VM instance
 * @param arr JSON array
 * @param v Value to append
 */
void jsonnet_json_array_append(struct JsonnetVm *vm, struct JsonnetJsonValue *arr, struct JsonnetJsonValue *v);

/**
 * Add field to JSON object.
 * @param vm VM instance
 * @param obj JSON object
 * @param f Field name
 * @param v Field value
 */
void jsonnet_json_object_append(struct JsonnetVm *vm, struct JsonnetJsonValue *obj, const char *f, struct JsonnetJsonValue *v);

/**
 * Clean up JSON value and all nested values.
 * @param vm VM instance
 * @param v JSON value to destroy
 */
void jsonnet_json_destroy(struct JsonnetVm *vm, struct JsonnetJsonValue *v);

Callback Registration

Functions for registering custom import handlers and native function extensions.

/**
 * Override the callback used to locate imports.
 * @param vm VM instance
 * @param cb Import callback function
 * @param ctx User context pointer passed to callback
 */
void jsonnet_import_callback(struct JsonnetVm *vm, JsonnetImportCallback *cb, void *ctx);

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

Types

Core types and callback function pointers:

/**
 * Jsonnet virtual machine context (opaque)
 */
struct JsonnetVm;

/**
 * Opaque JSON value type for native callbacks
 */
struct JsonnetJsonValue;

/**
 * Callback for custom import handling.
 * @param ctx User context pointer
 * @param base Directory containing importing code
 * @param rel Relative import path
 * @param found_here Output parameter for resolved absolute path
 * @param buf Output parameter for file content
 * @param buflen Output parameter for content length
 * @returns 0 on success, 1 on failure
 */
typedef int JsonnetImportCallback(void *ctx, const char *base, const char *rel,
                                  char **found_here, char **buf, size_t *buflen);

/**
 * Callback for native function extensions.
 * @param ctx User context pointer
 * @param argv Array of argument values
 * @param success Output parameter: 1 for success, 0 for failure
 * @returns Function result on success, error message on failure
 */
typedef struct JsonnetJsonValue *JsonnetNativeCallback(void *ctx,
                                                       const struct JsonnetJsonValue *const *argv,
                                                       int *success);

Usage Examples

Basic evaluation:

struct JsonnetVm *vm = jsonnet_make();
int error;
char *result = jsonnet_evaluate_snippet(vm, "test.jsonnet", "{ hello: 'world' }", &error);
if (!error) {
    printf("%s\\n", result);
}
jsonnet_realloc(vm, result, 0);
jsonnet_destroy(vm);

With external variables:

struct JsonnetVm *vm = jsonnet_make();
jsonnet_ext_var(vm, "name", "Alice");
jsonnet_ext_var(vm, "env", "production");
int error;
char *result = jsonnet_evaluate_snippet(vm, "config.jsonnet", 
    "{ greeting: 'Hello ' + std.extVar('name'), environment: std.extVar('env') }", &error);

Multi-file output:

struct JsonnetVm *vm = jsonnet_make();
int error;
char *result = jsonnet_evaluate_snippet(vm, "multi.jsonnet",
    "{ 'file1.json': { a: 1 }, 'file2.json': { b: 2 } }", &error);
// Parse null-separated filename/content pairs

Install with Tessl CLI