or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

c-library.mdcli-tools.mdcpp-wrapper.mdformatting.mdindex.mdpython-bindings.mdstandard-library.md
tile.json

tessl/pypi-jsonnet

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/jsonnet@0.21.x

To install, run

npx @tessl/cli install tessl/pypi-jsonnet@0.21.0

index.mddocs/

Jsonnet

Jsonnet is a data templating language and configuration management tool that extends JSON with programming language features including variables, conditionals, arithmetic, functions, inheritance, imports, and error propagation. It provides a comprehensive templating system that enables developers to generate JSON configurations dynamically, offering multiple language bindings (C++, Python), command-line tools (jsonnet, jsonnetfmt), and build system integrations.

Package Information

  • Package Name: jsonnet
  • Package Type: C++ library with bindings
  • Language: C++ with Python bindings
  • Version: 0.21.0
  • License: Apache License 2.0
  • Installation:
    • Python: pip install jsonnet
    • Homebrew: brew install jsonnet
    • Build from source: Make, CMake, or Bazel

Core Imports

For C library:

#include "libjsonnet.h"

For C++ library:

#include "libjsonnet++.h"

For Python:

import _jsonnet

Basic Usage

Python Example

import _jsonnet

# Evaluate Jsonnet code from string
jsonnet_code = '''
{
  person1: {
    name: "Alice",
    welcome: "Hello " + self.name + "!",
  },
  person2: self.person1 { name: "Bob" },
}
'''

result = _jsonnet.evaluate_snippet("example.jsonnet", jsonnet_code)
print(result)  # Outputs JSON string

# Evaluate Jsonnet file
result = _jsonnet.evaluate_file("config.jsonnet")

C Example

#include "libjsonnet.h"

int main() {
    struct JsonnetVm *vm = jsonnet_make();
    int error;
    
    char *result = jsonnet_evaluate_snippet(vm, "example.jsonnet", 
        "{ greeting: \"Hello World!\" }", &error);
    
    if (error) {
        fprintf(stderr, "Error: %s\n", result);
    } else {
        printf("Result: %s\n", result);
    }
    
    jsonnet_realloc(vm, result, 0);  // Free result
    jsonnet_destroy(vm);
    return error;
}

Command Line Example

# Evaluate Jsonnet file
jsonnet config.jsonnet

# With output file
jsonnet -o output.json config.jsonnet

# With external variables
jsonnet -V name=Alice --ext-str env=production config.jsonnet

# Format Jsonnet code
jsonnetfmt --in-place config.jsonnet

Architecture

Jsonnet is built around several key components:

  • VM (Virtual Machine): Core evaluation engine that processes Jsonnet code
  • Lexer/Parser: Tokenizes and parses Jsonnet source code into AST
  • Standard Library: 140+ built-in functions for string, array, object, and math operations
  • Import System: Module system supporting file imports and custom import callbacks
  • Native Extensions: Plugin system for registering custom functions from host languages
  • Formatter: Code formatting engine with configurable style options
  • Language Bindings: C API with high-level C++ and Python wrappers

The lazy evaluation model ensures efficient processing of large configurations, while the hermetic evaluation guarantees reproducible results.

Capabilities

C Library API

Core C library providing low-level access to the Jsonnet virtual machine, evaluation functions, and native extension capabilities.

struct JsonnetVm *jsonnet_make(void);
void jsonnet_destroy(struct JsonnetVm *vm);
char *jsonnet_evaluate_file(struct JsonnetVm *vm, const char *filename, int *error);
char *jsonnet_evaluate_snippet(struct JsonnetVm *vm, const char *filename, const char *snippet, int *error);

C Library

C++ Wrapper API

Object-oriented C++ wrapper providing a modern interface to Jsonnet functionality with RAII and exception safety.

class Jsonnet {
public:
    Jsonnet();
    ~Jsonnet();
    bool init();
    bool evaluateFile(const std::string& filename, std::string* output);
    bool evaluateSnippet(const std::string& filename, const std::string& snippet, std::string* output);
    std::string lastError() const;
};

C++ Wrapper

Python Bindings

Python module providing high-level access to Jsonnet evaluation with support for external variables, import callbacks, and native extensions.

def evaluate_file(filename, **kwargs):
    """Evaluate Jsonnet file and return JSON string"""

def evaluate_snippet(filename, src, **kwargs):
    """Evaluate Jsonnet code string and return JSON string"""

Python Bindings

Command Line Tools

Command-line executables for evaluating Jsonnet files and formatting code, with extensive configuration options.

jsonnet [options] <filename>
jsonnetfmt [options] [filename...]

Command Line Tools

Standard Library

Comprehensive built-in function library with 140+ functions for string manipulation, array processing, object operations, mathematical computations, and data format serialization.

std.map(func, arr)
std.filter(func, arr)
std.join(sep, arr)
std.manifestJson(obj)
std.length(x)

Standard Library

Code Formatting

Powerful code formatter with extensive customization options for indentation, spacing, comment styles, and import organization.

void jsonnet_fmt_indent(struct JsonnetVm *vm, int n);
char *jsonnet_fmt_file(struct JsonnetVm *vm, const char *filename, int *error);
char *jsonnet_fmt_snippet(struct JsonnetVm *vm, const char *filename, const char *snippet, int *error);

Code Formatting

Types

Core types used across all APIs:

struct JsonnetVm;
struct JsonnetJsonValue;

typedef int JsonnetImportCallback(void *ctx, const char *base, const char *rel,
                                  char **found_here, char **buf, size_t *buflen);

typedef struct JsonnetJsonValue *JsonnetNativeCallback(void *ctx,
                                                       const struct JsonnetJsonValue *const *argv,
                                                       int *success);

Error handling uses return codes in C, boolean success status in C++, and exceptions in Python. All functions provide detailed error messages for debugging.