1#ifndef LIB_JSONNET_H2#define LIB_JSONNET_H34#include <stddef.h>56/** \file This file is a library interface for evaluating Jsonnet. It is written in Rust but exposes7 * a C interface for easier wrapping by other languages. See \see jsonnet_lib_test.c for an example8 * of using the library.9 */1011/** The version string of th Jsonnet interpreter.12 *13 * This is currently grepped out of this file by setup.py, Makefile, and CMakeLists.txt so be aware14 * of that when making changes.15 *16 * If this isn't the sae as jsonnet_version() then you've got a mismatched binary / header.17 */18#define LIB_JSONNET_VERSION "v0.20.0"1920/** Return the version string of the Jsonnet interpreter. Conforms to semantic versioning21 * https://semver.org/ If this does not match LIB_JSONNET_VERSION then there is a mismatch between22 * header and compiled library.23 */24const char *jsonnet_version(void);2526/** Jsonnet virtual machine context. */27struct JsonnetVm;2829/** Create a new Jsonnet virtual machine. */30struct JsonnetVm *jsonnet_make(void);3132/** Set the maximum stack depth. */33void jsonnet_max_stack(struct JsonnetVm *vm, unsigned v);3435/** Set the number of objects required before a garbage collection cycle is allowed. */36void jsonnet_gc_min_objects(struct JsonnetVm *vm, unsigned v);3738/** Run the garbage collector after this amount of growth in the number of objects. */39void jsonnet_gc_growth_trigger(struct JsonnetVm *vm, double v);4041/** Expect a string as output and don't JSON encode it. */42void jsonnet_string_output(struct JsonnetVm *vm, int v);4344/** Callback used to load imports.45 *46 * The returned char* should be allocated with jsonnet_realloc. It will be cleaned up by47 * libjsonnet when no-longer needed.48 *49 * \param ctx User pointer, given in jsonnet_import_callback.50 * \param base The directory containing the code that did the import.51 * \param rel The path imported by the code.52 * \param found_here Set this byref param to path to the file, absolute or relative to the53 * process's CWD. This is necessary so that imports from the content of the imported file can54 * be resolved correctly. Allocate memory with jsonnet_realloc. Only use when *success = 1.55 * \param success Set this byref param to 1 to indicate success and 0 for failure.56 * \param buf Set this byref param to the content of the imported file, or an error message. Allocate memory with jsonnet_realloc. Do not include a null terminator byte.57 * \param buflen Set this byref param to the length of the data returned in buf.58 * \returns 0 to indicate success and 1 for failure. On success, the content is in *buf. On failure, an error message is in *buf.59 */60typedef int JsonnetImportCallback(void *ctx, const char *base, const char *rel,61 char **found_here, char **buf, size_t *buflen);6263/** An opaque type which can only be utilized via the jsonnet_json_* family of functions.64 */65struct JsonnetJsonValue;6667/** If the value is a string, return it as UTF8 otherwise return NULL.68 */69const char *jsonnet_json_extract_string(struct JsonnetVm *vm, const struct JsonnetJsonValue *v);7071/** If the value is a number, return 1 and store the number in out, otherwise return 0.72 */73int jsonnet_json_extract_number(struct JsonnetVm *vm, const struct JsonnetJsonValue *v,74 double *out);7576/** Return 0 if the value is false, 1 if it is true, and 2 if it is not a bool.77 */78int jsonnet_json_extract_bool(struct JsonnetVm *vm, const struct JsonnetJsonValue *v);7980/** Return 1 if the value is null, else 0.81 */82int jsonnet_json_extract_null(struct JsonnetVm *vm, const struct JsonnetJsonValue *v);8384/** Convert the given UTF8 string to a JsonnetJsonValue.85 */86struct JsonnetJsonValue *jsonnet_json_make_string(struct JsonnetVm *vm, const char *v);8788/** Convert the given double to a JsonnetJsonValue.89 */90struct JsonnetJsonValue *jsonnet_json_make_number(struct JsonnetVm *vm, double v);9192/** Convert the given bool (1 or 0) to a JsonnetJsonValue.93 */94struct JsonnetJsonValue *jsonnet_json_make_bool(struct JsonnetVm *vm, int v);9596/** Make a JsonnetJsonValue representing null.97 */98struct JsonnetJsonValue *jsonnet_json_make_null(struct JsonnetVm *vm);99100/** Make a JsonnetJsonValue representing an array.101 *102 * Assign elements with jsonnet_json_array_append.103 */104struct JsonnetJsonValue *jsonnet_json_make_array(struct JsonnetVm *vm);105106/** Add v to the end of the array.107 */108void jsonnet_json_array_append(struct JsonnetVm *vm, struct JsonnetJsonValue *arr,109 struct JsonnetJsonValue *v);110111/** Make a JsonnetJsonValue representing an object with the given number of fields.112 *113 * Every index of the array must have a unique value assigned with jsonnet_json_array_element.114 */115struct JsonnetJsonValue *jsonnet_json_make_object(struct JsonnetVm *vm);116117/** Add the field f to the object, bound to v.118 *119 * This replaces any previous binding of the field.120 */121void jsonnet_json_object_append(struct JsonnetVm *vm, struct JsonnetJsonValue *obj, const char *f,122 struct JsonnetJsonValue *v);123124/** Clean up a JSON subtree.125 *126 * This is useful if you want to abort with an error mid-way through building a complex value.127 */128void jsonnet_json_destroy(struct JsonnetVm *vm, struct JsonnetJsonValue *v);129130/** Callback to provide native extensions to Jsonnet.131 *132 * The returned JsonnetJsonValue* should be allocated with jsonnet_realloc. It will be cleaned up133 * along with the objects rooted at argv by libjsonnet when no-longer needed. Return a string upon134 * failure, which will appear in Jsonnet as an error. The argv pointer is an array whose size135 * matches the array of parameters supplied when the native callback was originally registered.136 *137 * \param ctx User pointer, given in jsonnet_native_callback.138 * \param argv Array of arguments from Jsonnet code.139 * \param success Set this byref param to 1 to indicate success and 0 for failure.140 * \returns The content of the imported file, or an error message.141 */142typedef struct JsonnetJsonValue *JsonnetNativeCallback(void *ctx,143 const struct JsonnetJsonValue *const *argv,144 int *success);145146/** Allocate, resize, or free a buffer. This will abort if the memory cannot be allocated. It will147 * only return NULL if sz was zero.148 *149 * \param buf If NULL, allocate a new buffer. If an previously allocated buffer, resize it.150 * \param sz The size of the buffer to return. If zero, frees the buffer.151 * \returns The new buffer.152 */153char *jsonnet_realloc(struct JsonnetVm *vm, char *buf, size_t sz);154155/** Override the callback used to locate imports.156 */157void jsonnet_import_callback(struct JsonnetVm *vm, JsonnetImportCallback *cb, void *ctx);158159/** Register a native extension.160 *161 * This will appear in Jsonnet as a function type and can be accessed from std.nativeExt("foo").162 *163 * DO NOT register native callbacks with side-effects! Jsonnet is a lazy functional language and164 * will call your function when you least expect it, more times than you expect, or not at all.165 *166 * \param vm The vm.167 * \param name The name of the function as visible to Jsonnet code, e.g. "foo".168 * \param cb The PURE function that implements the behavior you want.169 * \param ctx User pointer, stash non-global state you need here.170 * \param params NULL-terminated array of the names of the params. Must be valid identifiers.171 */172void jsonnet_native_callback(struct JsonnetVm *vm, const char *name, JsonnetNativeCallback *cb,173 void *ctx, const char *const *params);174175/** Bind a Jsonnet external var to the given string.176 *177 * Argument values are copied so memory should be managed by caller.178 */179void jsonnet_ext_var(struct JsonnetVm *vm, const char *key, const char *val);180181/** Bind a Jsonnet external var to the given code.182 *183 * Argument values are copied so memory should be managed by caller.184 */185void jsonnet_ext_code(struct JsonnetVm *vm, const char *key, const char *val);186187/** Bind a string top-level argument for a top-level parameter.188 *189 * Argument values are copied so memory should be managed by caller.190 */191void jsonnet_tla_var(struct JsonnetVm *vm, const char *key, const char *val);192193/** Bind a code top-level argument for a top-level parameter.194 *195 * Argument values are copied so memory should be managed by caller.196 */197void jsonnet_tla_code(struct JsonnetVm *vm, const char *key, const char *val);198199/** Set the number of lines of stack trace to display (0 for all of them). */200void jsonnet_max_trace(struct JsonnetVm *vm, unsigned v);201202/** Add to the default import callback's library search path.203 *204 * The search order is last to first, so more recently appended paths take precedence.205 */206void jsonnet_jpath_add(struct JsonnetVm *vm, const char *v);207208/** Evaluate a file containing Jsonnet code, return a JSON string.209 *210 * The returned string should be cleaned up with jsonnet_realloc.211 *212 * \param filename Path to a file containing Jsonnet code.213 * \param error Return by reference whether or not there was an error.214 * \returns Either JSON or the error message.215 */216char *jsonnet_evaluate_file(struct JsonnetVm *vm, const char *filename, int *error);217218/** Evaluate a string containing Jsonnet code, return a JSON string.219 *220 * The returned string should be cleaned up with jsonnet_realloc.221 *222 * \param filename Path to a file (used in error messages).223 * \param snippet Jsonnet code to execute.224 * \param error Return by reference whether or not there was an error.225 * \returns Either JSON or the error message.226 */227char *jsonnet_evaluate_snippet(struct JsonnetVm *vm, const char *filename, const char *snippet,228 int *error);229230/** Evaluate a file containing Jsonnet code, return a number of named JSON files.231 *232 * The returned character buffer contains an even number of strings, the filename and JSON for each233 * JSON file interleaved. It should be cleaned up with jsonnet_realloc.234 *235 * \param filename Path to a file containing Jsonnet code.236 * \param error Return by reference whether or not there was an error.237 * \returns Either the error, or a sequence of strings separated by \0, terminated with \0\0.238 */239char *jsonnet_evaluate_file_multi(struct JsonnetVm *vm, const char *filename, int *error);240241/** Evaluate a string containing Jsonnet code, return a number of named JSON files.242 *243 * The returned character buffer contains an even number of strings, the filename and JSON for each244 * JSON file interleaved. It should be cleaned up with jsonnet_realloc.245 *246 * \param filename Path to a file containing Jsonnet code.247 * \param snippet Jsonnet code to execute.248 * \param error Return by reference whether or not there was an error.249 * \returns Either the error, or a sequence of strings separated by \0, terminated with \0\0.250 */251char *jsonnet_evaluate_snippet_multi(struct JsonnetVm *vm, const char *filename,252 const char *snippet, int *error);253254/** Evaluate a file containing Jsonnet code, return a number of JSON files.255 *256 * The returned character buffer contains several strings. It should be cleaned up with257 * jsonnet_realloc.258 *259 * \param filename Path to a file containing Jsonnet code.260 * \param error Return by reference whether or not there was an error.261 * \returns Either the error, or a sequence of strings separated by \0, terminated with \0\0.262 */263char *jsonnet_evaluate_file_stream(struct JsonnetVm *vm, const char *filename, int *error);264265/** Evaluate a string containing Jsonnet code, return a number of JSON files.266 *267 * The returned character buffer contains several strings. It should be cleaned up with268 * jsonnet_realloc.269 *270 * \param filename Path to a file containing Jsonnet code.271 * \param snippet Jsonnet code to execute.272 * \param error Return by reference whether or not there was an error.273 * \returns Either the error, or a sequence of strings separated by \0, terminated with \0\0.274 */275char *jsonnet_evaluate_snippet_stream(struct JsonnetVm *vm, const char *filename,276 const char *snippet, int *error);277278/** Complement of \see jsonnet_vm_make. */279void jsonnet_destroy(struct JsonnetVm *vm);280281/** Jrsonnet addition.282 *283 * In jrsonnet, vm state is bound to the thread, because interpreter284 * also uses thread_local storage for some things (I.e GC).285 *286 * It makes it impossible to correctly use those bindings in golang,287 * where developer has little control over goroutine scheduler.288 *289 * To make it work, jrsonnet provides methods to dump and restore thread290 * state manually, making it possible to wire it with golang.291 */292struct JrThreadCTX;293294/** Dump current thread state, to be restored with295 * jrsonnet_reenter_thread.296 */297struct JrThreadCTX *jrsonnet_exit_thread();298/** Restore thread state, freeing JrThreadCTX.299 */300void jrsonnet_reenter_thread(struct JrThreadCTX *ctx);301302struct JrThreadId;303304/** Get current thread id (opaque pointer).305 */306struct JrThreadId* jrsonnet_thread_id();307308/** Compare two thread ids, it is not the same as a == b.309 *310 * \returns 1 if the same thread, 0 otherwise311 */312int jrsonnet_thread_id_compare(struct JrThreadId *a, struct JrThreadId *b);313314/** Free thread id value.315 */316void jrsonnet_thread_id_free(struct JrThreadId *id);317318#endif // LIB_JSONNET_H