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++ Wrapper API

Name: tessl/pypi-jsonnet
Author: tessl

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.

Capabilities

Jsonnet Class

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

/**
 * Main Jsonnet class providing object-oriented access to Jsonnet functionality
 */
class Jsonnet {
public:
    /**
     * Constructor - creates uninitialized Jsonnet instance
     */
    Jsonnet();
    
    /**
     * Destructor - automatically cleans up VM and resources
     */
    ~Jsonnet();
    
    /**
     * Return the version string of the Jsonnet interpreter
     * @returns Version string conforming to semantic versioning
     */
    static std::string version();
    
    /**
     * Initialize the Jsonnet VM - must be called before other methods
     * @returns true if VM was successfully initialized, false otherwise
     */
    bool init();
};

Configuration Methods

Methods for configuring VM behavior and performance characteristics.

/**
 * Set the maximum stack depth
 * @param depth Maximum stack depth
 */
void setMaxStack(uint32_t depth);

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

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

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

/**
 * Set the number of lines of stack trace to display (0 to display all)
 * @param lines Maximum trace lines
 */
void setMaxTrace(uint32_t lines);

/**
 * Add to the default import callback's library search path
 * @param path Import search path to add
 */
void addImportPath(const std::string& path);

Variable Binding Methods

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

/**
 * Bind a string top-level argument for a top-level parameter
 * @param key Parameter name
 * @param value String value (copied)
 */
void bindTlaVar(const std::string& key, const std::string& value);

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

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

/**
 * Bind a Jsonnet external code variable to the given value
 * @param key Variable name
 * @param value Jsonnet code to evaluate (copied)
 */
void bindExtCodeVar(const std::string& key, const std::string& value);

Evaluation Methods

Core methods for evaluating Jsonnet code with different output modes.

/**
 * Evaluate a file containing Jsonnet code to return a JSON string
 * @param filename Path to file containing Jsonnet code
 * @param output Pointer to string to contain the output
 * @returns true if successfully evaluated, false on error (check lastError())
 */
bool evaluateFile(const std::string& filename, std::string* output);

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

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

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

Error Handling

Method for retrieving detailed error information.

/**
 * Return the last error message from Jsonnet evaluation
 * @returns Error message string, empty if no error
 */
std::string lastError() const;

Usage Examples

Basic usage:

#include "libjsonnet++.h"
#include <iostream>

int main() {
    jsonnet::Jsonnet jsonnet;
    if (!jsonnet.init()) {
        std::cerr << "Failed to initialize Jsonnet" << std::endl;
        return 1;
    }
    
    std::string result;
    bool success = jsonnet.evaluateSnippet("example.jsonnet", 
        "{ greeting: 'Hello World!' }", &result);
    
    if (success) {
        std::cout << result << std::endl;
    } else {
        std::cerr << "Error: " << jsonnet.lastError() << std::endl;
    }
    
    return success ? 0 : 1;
}

With configuration and variables:

jsonnet::Jsonnet jsonnet;
jsonnet.init();

// Configure VM
jsonnet.setMaxStack(1000);
jsonnet.setStringOutput(false);
jsonnet.addImportPath("/usr/local/lib/jsonnet");

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

std::string result;
bool success = jsonnet.evaluateFile("config.jsonnet", &result);

Multi-file evaluation:

jsonnet::Jsonnet jsonnet;
jsonnet.init();

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

if (success) {
    for (const auto& pair : outputs) {
        std::cout << "File: " << pair.first << std::endl;
        std::cout << "Content: " << pair.second << std::endl;
    }
}

Error handling:

jsonnet::Jsonnet jsonnet;
jsonnet.init();

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

if (!success) {
    std::cerr << "Evaluation failed: " << jsonnet.lastError() << std::endl;
    // Error message includes line numbers and context
}

Version checking:

std::string version = jsonnet::Jsonnet::version();
std::cout << "Jsonnet version: " << version << std::endl;
// Output: Jsonnet version: v0.21.0

Integration Examples

With CMake:

find_package(jsonnet REQUIRED)
target_link_libraries(myapp jsonnet)

Exception safety:

void processConfig(const std::string& filename) {
    jsonnet::Jsonnet jsonnet;
    if (!jsonnet.init()) {
        throw std::runtime_error("Failed to initialize Jsonnet");
    }
    
    std::string result;
    if (!jsonnet.evaluateFile(filename, &result)) {
        throw std::runtime_error("Evaluation failed: " + jsonnet.lastError());
    }
    
    // Process result...
    // Destructor automatically cleans up VM
}

Install with Tessl CLI