0
# Jsonnet
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: jsonnet
7
- **Package Type**: C++ library with bindings
8
- **Language**: C++ with Python bindings
9
- **Version**: 0.21.0
10
- **License**: Apache License 2.0
11
- **Installation**: 
12
  - Python: `pip install jsonnet`
13
  - Homebrew: `brew install jsonnet`
14
  - Build from source: Make, CMake, or Bazel
15

16
## Core Imports
17

18
For C library:
19
```c
20
#include "libjsonnet.h"
21
```
22

23
For C++ library:
24
```cpp
25
#include "libjsonnet++.h"
26
```
27

28
For Python:
29
```python
30
import _jsonnet
31
```
32

33
## Basic Usage
34

35
### Python Example
36
```python
37
import _jsonnet
38

39
# Evaluate Jsonnet code from string
40
jsonnet_code = '''
41
{
42
  person1: {
43
    name: "Alice",
44
    welcome: "Hello " + self.name + "!",
45
  },
46
  person2: self.person1 { name: "Bob" },
47
}
48
'''
49

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

53
# Evaluate Jsonnet file
54
result = _jsonnet.evaluate_file("config.jsonnet")
55
```
56

57
### C Example
58
```c
59
#include "libjsonnet.h"
60

61
int main() {
62
    struct JsonnetVm *vm = jsonnet_make();
63
    int error;
64
    
65
    char *result = jsonnet_evaluate_snippet(vm, "example.jsonnet", 
66
        "{ greeting: \"Hello World!\" }", &error);
67
    
68
    if (error) {
69
        fprintf(stderr, "Error: %s\n", result);
70
    } else {
71
        printf("Result: %s\n", result);
72
    }
73
    
74
    jsonnet_realloc(vm, result, 0);  // Free result
75
    jsonnet_destroy(vm);
76
    return error;
77
}
78
```
79

80
### Command Line Example
81
```bash
82
# Evaluate Jsonnet file
83
jsonnet config.jsonnet
84

85
# With output file
86
jsonnet -o output.json config.jsonnet
87

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

91
# Format Jsonnet code
92
jsonnetfmt --in-place config.jsonnet
93
```
94

95
## Architecture
96

97
Jsonnet is built around several key components:
98

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

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

109
## Capabilities
110

111
### C Library API
112

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

115
```c { .api }
116
struct JsonnetVm *jsonnet_make(void);
117
void jsonnet_destroy(struct JsonnetVm *vm);
118
char *jsonnet_evaluate_file(struct JsonnetVm *vm, const char *filename, int *error);
119
char *jsonnet_evaluate_snippet(struct JsonnetVm *vm, const char *filename, const char *snippet, int *error);
120
```
121

122
[C Library](./c-library.md)
123

124
### C++ Wrapper API
125

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

128
```cpp { .api }
129
class Jsonnet {
130
public:
131
    Jsonnet();
132
    ~Jsonnet();
133
    bool init();
134
    bool evaluateFile(const std::string& filename, std::string* output);
135
    bool evaluateSnippet(const std::string& filename, const std::string& snippet, std::string* output);
136
    std::string lastError() const;
137
};
138
```
139

140
[C++ Wrapper](./cpp-wrapper.md)
141

142
### Python Bindings
143

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

146
```python { .api }
147
def evaluate_file(filename, **kwargs):
148
    """Evaluate Jsonnet file and return JSON string"""
149

150
def evaluate_snippet(filename, src, **kwargs):
151
    """Evaluate Jsonnet code string and return JSON string"""
152
```
153

154
[Python Bindings](./python-bindings.md)
155

156
### Command Line Tools
157

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

160
```bash { .api }
161
jsonnet [options] <filename>
162
jsonnetfmt [options] [filename...]
163
```
164

165
[Command Line Tools](./cli-tools.md)
166

167
### Standard Library
168

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

171
```jsonnet { .api }
172
std.map(func, arr)
173
std.filter(func, arr)
174
std.join(sep, arr)
175
std.manifestJson(obj)
176
std.length(x)
177
```
178

179
[Standard Library](./standard-library.md)
180

181
### Code Formatting
182

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

185
```c { .api }
186
void jsonnet_fmt_indent(struct JsonnetVm *vm, int n);
187
char *jsonnet_fmt_file(struct JsonnetVm *vm, const char *filename, int *error);
188
char *jsonnet_fmt_snippet(struct JsonnetVm *vm, const char *filename, const char *snippet, int *error);
189
```
190

191
[Code Formatting](./formatting.md)
192

193
## Types
194

195
Core types used across all APIs:
196

197
```c { .api }
198
struct JsonnetVm;
199
struct JsonnetJsonValue;
200

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

204
typedef struct JsonnetJsonValue *JsonnetNativeCallback(void *ctx,
205
                                                       const struct JsonnetJsonValue *const *argv,
206
                                                       int *success);
207
```
208

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