1/*2Copyright 2015 Google Inc. All rights reserved.3Licensed under the Apache License, Version 2.0 (the "License");4you may not use this file except in compliance with the License.5You may obtain a copy of the License at6 http://www.apache.org/licenses/LICENSE-2.07Unless required by applicable law or agreed to in writing, software8distributed under the License is distributed on an "AS IS" BASIS,9WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.10See the License for the specific language governing permissions and11limitations under the License.12*/1314#ifndef LIB_JSONNET_H15#define LIB_JSONNET_H1617#include <stddef.h>1819/** \file This file is a library interface for evaluating Jsonnet. It is written in C++ but exposes20 * a C interface for easier wrapping by other languages. See \see jsonnet_lib_test.c for an example21 * of using the library.22 */2324/** The version string of th Jsonnet interpreter.25 *26 * This is currently grepped out of this file by setup.py, Makefile, and CMakeLists.txt so be aware27 * of that when making changes.28 *29 * If this isn't the sae as jsonnet_version() then you've got a mismatched binary / header.30 */31#define LIB_JSONNET_VERSION "v0.16.0"3233/** Return the version string of the Jsonnet interpreter. Conforms to semantic versioning34 * http://semver.org/ If this does not match LIB_JSONNET_VERSION then there is a mismatch between35 * header and compiled library.36 */37const char *jsonnet_version(void);3839/** Jsonnet virtual machine context. */40struct JsonnetVm;4142/** Create a new Jsonnet virtual machine. */43struct JsonnetVm *jsonnet_make(void);4445/** Set the maximum stack depth. */46void jsonnet_max_stack(struct JsonnetVm *vm, unsigned v);4748/** Set the number of objects required before a garbage collection cycle is allowed. */49void jsonnet_gc_min_objects(struct JsonnetVm *vm, unsigned v);5051/** Run the garbage collector after this amount of growth in the number of objects. */52void jsonnet_gc_growth_trigger(struct JsonnetVm *vm, double v);5354/** Expect a string as output and don't JSON encode it. */55void jsonnet_string_output(struct JsonnetVm *vm, int v);5657/** Callback used to load imports.58 *59 * The returned char* should be allocated with jsonnet_realloc. It will be cleaned up by60 * libjsonnet when no-longer needed.61 *62 * \param ctx User pointer, given in jsonnet_import_callback.63 * \param base The directory containing the code that did the import.64 * \param rel The path imported by the code.65 * \param found_here Set this byref param to path to the file, absolute or relative to the66 * process's CWD. This is necessary so that imports from the content of the imported file can67 * be resolved correctly. Allocate memory with jsonnet_realloc. Only use when *success = 1.68 * \param success Set this byref param to 1 to indicate success and 0 for failure.69 * \returns The content of the imported file, or an error message.70 */71typedef char *JsonnetImportCallback(void *ctx, const char *base, const char *rel, char **found_here,72 int *success);7374/** An opaque type which can only be utilized via the jsonnet_json_* family of functions.75 */76struct JsonnetJsonValue;7778/** If the value is a string, return it as UTF8 otherwise return NULL.79 */80const char *jsonnet_json_extract_string(struct JsonnetVm *vm, const struct JsonnetJsonValue *v);8182/** If the value is a number, return 1 and store the number in out, otherwise return 0.83 */84int jsonnet_json_extract_number(struct JsonnetVm *vm, const struct JsonnetJsonValue *v,85 double *out);8687/** Return 0 if the value is false, 1 if it is true, and 2 if it is not a bool.88 */89int jsonnet_json_extract_bool(struct JsonnetVm *vm, const struct JsonnetJsonValue *v);9091/** Return 1 if the value is null, else 0.92 */93int jsonnet_json_extract_null(struct JsonnetVm *vm, const struct JsonnetJsonValue *v);9495/** Convert the given UTF8 string to a JsonnetJsonValue.96 */97struct JsonnetJsonValue *jsonnet_json_make_string(struct JsonnetVm *vm, const char *v);9899/** Convert the given double to a JsonnetJsonValue.100 */101struct JsonnetJsonValue *jsonnet_json_make_number(struct JsonnetVm *vm, double v);102103/** Convert the given bool (1 or 0) to a JsonnetJsonValue.104 */105struct JsonnetJsonValue *jsonnet_json_make_bool(struct JsonnetVm *vm, int v);106107/** Make a JsonnetJsonValue representing null.108 */109struct JsonnetJsonValue *jsonnet_json_make_null(struct JsonnetVm *vm);110111/** Make a JsonnetJsonValue representing an array.112 *113 * Assign elements with jsonnet_json_array_append.114 */115struct JsonnetJsonValue *jsonnet_json_make_array(struct JsonnetVm *vm);116117/** Add v to the end of the array.118 */119void jsonnet_json_array_append(struct JsonnetVm *vm, struct JsonnetJsonValue *arr,120 struct JsonnetJsonValue *v);121122/** Make a JsonnetJsonValue representing an object with the given number of fields.123 *124 * Every index of the array must have a unique value assigned with jsonnet_json_array_element.125 */126struct JsonnetJsonValue *jsonnet_json_make_object(struct JsonnetVm *vm);127128/** Add the field f to the object, bound to v.129 *130 * This replaces any previous binding of the field.131 */132void jsonnet_json_object_append(struct JsonnetVm *vm, struct JsonnetJsonValue *obj, const char *f,133 struct JsonnetJsonValue *v);134135/** Clean up a JSON subtree.136 *137 * This is useful if you want to abort with an error mid-way through building a complex value.138 */139void jsonnet_json_destroy(struct JsonnetVm *vm, struct JsonnetJsonValue *v);140141/** Callback to provide native extensions to Jsonnet.142 *143 * The returned JsonnetJsonValue* should be allocated with jsonnet_realloc. It will be cleaned up144 * along with the objects rooted at argv by libjsonnet when no-longer needed. Return a string upon145 * failure, which will appear in Jsonnet as an error. The argv pointer is an array whose size146 * matches the array of parameters supplied when the native callback was originally registered.147 *148 * \param ctx User pointer, given in jsonnet_native_callback.149 * \param argv Array of arguments from Jsonnet code.150 * \param success Set this byref param to 1 to indicate success and 0 for failure.151 * \returns The content of the imported file, or an error message.152 */153typedef struct JsonnetJsonValue *JsonnetNativeCallback(void *ctx,154 const struct JsonnetJsonValue *const *argv,155 int *success);156157/** Allocate, resize, or free a buffer. This will abort if the memory cannot be allocated. It will158 * only return NULL if sz was zero.159 *160 * \param buf If NULL, allocate a new buffer. If an previously allocated buffer, resize it.161 * \param sz The size of the buffer to return. If zero, frees the buffer.162 * \returns The new buffer.163 */164char *jsonnet_realloc(struct JsonnetVm *vm, char *buf, size_t sz);165166/** Override the callback used to locate imports.167 */168void jsonnet_import_callback(struct JsonnetVm *vm, JsonnetImportCallback *cb, void *ctx);169170/** Register a native extension.171 *172 * This will appear in Jsonnet as a function type and can be accessed from std.nativeExt("foo").173 *174 * DO NOT register native callbacks with side-effects! Jsonnet is a lazy functional language and175 * will call your function when you least expect it, more times than you expect, or not at all.176 *177 * \param vm The vm.178 * \param name The name of the function as visible to Jsonnet code, e.g. "foo".179 * \param cb The PURE function that implements the behavior you want.180 * \param ctx User pointer, stash non-global state you need here.181 * \param params NULL-terminated array of the names of the params. Must be valid identifiers.182 */183void jsonnet_native_callback(struct JsonnetVm *vm, const char *name, JsonnetNativeCallback *cb,184 void *ctx, const char *const *params);185186/** Bind a Jsonnet external var to the given string.187 *188 * Argument values are copied so memory should be managed by caller.189 */190void jsonnet_ext_var(struct JsonnetVm *vm, const char *key, const char *val);191192/** Bind a Jsonnet external var to the given code.193 *194 * Argument values are copied so memory should be managed by caller.195 */196void jsonnet_ext_code(struct JsonnetVm *vm, const char *key, const char *val);197198/** Bind a string top-level argument for a top-level parameter.199 *200 * Argument values are copied so memory should be managed by caller.201 */202void jsonnet_tla_var(struct JsonnetVm *vm, const char *key, const char *val);203204/** Bind a code top-level argument for a top-level parameter.205 *206 * Argument values are copied so memory should be managed by caller.207 */208void jsonnet_tla_code(struct JsonnetVm *vm, const char *key, const char *val);209210/** Set the number of lines of stack trace to display (0 for all of them). */211void jsonnet_max_trace(struct JsonnetVm *vm, unsigned v);212213/** Add to the default import callback's library search path.214 *215 * The search order is last to first, so more recently appended paths take precedence.216 */217void jsonnet_jpath_add(struct JsonnetVm *vm, const char *v);218219/** Evaluate a file containing Jsonnet code, return a JSON string.220 *221 * The returned string should be cleaned up with jsonnet_realloc.222 *223 * \param filename Path to a file containing Jsonnet code.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_file(struct JsonnetVm *vm, const char *filename, int *error);228229/** Evaluate a string containing Jsonnet code, return a JSON string.230 *231 * The returned string should be cleaned up with jsonnet_realloc.232 *233 * \param filename Path to a file (used in error messages).234 * \param snippet Jsonnet code to execute.235 * \param error Return by reference whether or not there was an error.236 * \returns Either JSON or the error message.237 */238char *jsonnet_evaluate_snippet(struct JsonnetVm *vm, const char *filename, const char *snippet,239 int *error);240241/** Evaluate a file 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 error Return by reference whether or not there was an error.248 * \returns Either the error, or a sequence of strings separated by \0, terminated with \0\0.249 */250char *jsonnet_evaluate_file_multi(struct JsonnetVm *vm, const char *filename, int *error);251252/** Evaluate a string containing Jsonnet code, return a number of named JSON files.253 *254 * The returned character buffer contains an even number of strings, the filename and JSON for each255 * JSON file interleaved. It should be cleaned up with jsonnet_realloc.256 *257 * \param filename Path to a file containing Jsonnet code.258 * \param snippet Jsonnet code to execute.259 * \param error Return by reference whether or not there was an error.260 * \returns Either the error, or a sequence of strings separated by \0, terminated with \0\0.261 */262char *jsonnet_evaluate_snippet_multi(struct JsonnetVm *vm, const char *filename,263 const char *snippet, int *error);264265/** Evaluate a file 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 error Return by reference whether or not there was an error.272 * \returns Either the error, or a sequence of strings separated by \0, terminated with \0\0.273 */274char *jsonnet_evaluate_file_stream(struct JsonnetVm *vm, const char *filename, int *error);275276/** Evaluate a string containing Jsonnet code, return a number of JSON files.277 *278 * The returned character buffer contains several strings. It should be cleaned up with279 * jsonnet_realloc.280 *281 * \param filename Path to a file containing Jsonnet code.282 * \param snippet Jsonnet code to execute.283 * \param error Return by reference whether or not there was an error.284 * \returns Either the error, or a sequence of strings separated by \0, terminated with \0\0.285 */286char *jsonnet_evaluate_snippet_stream(struct JsonnetVm *vm, const char *filename,287 const char *snippet, int *error);288289/** Complement of \see jsonnet_vm_make. */290void jsonnet_destroy(struct JsonnetVm *vm);291292#endif // LIB_JSONNET_H