git.delta.rocks / jrsonnet / refs/commits / 656c8fd8cae2

1# jrsonnet1# jrsonnet
22
3![Crates.io](https://img.shields.io/crates/v/jrsonnet)
4
3## What is it5## What is it
46
5[Jsonnet](https://jsonnet.org/) is a json templating language7[Jsonnet](https://jsonnet.org/) is a data templating language
68
7This crate implements both jsonnet library, and alternative jsonnet executable9This Rust crate implements both jsonnet library and an alternative `jsonnet` executable based on it. For more information see [bindings](#Bindings).
810
9## Why11## Why?
1012
11There is already 3 implementations of this standard: in [C++](https://github.com/google/jsonnet), in [Go](https://github.com/google/go-jsonnet/) and in [Scala](https://github.com/databricks/sjsonnet)13There already are multiple implementations of this standard implemented in different languages: [C++](https://github.com/google/jsonnet), [Go](https://github.com/google/go-jsonnet/), [Scala](https://github.com/databricks/sjsonnet).
1214
13It is fun to write one in Rust :D15This implementation shows performance better than all existing implementations. For more information see [benchmarks](#Benchmarks).
1416
15## Spec support17In the end, it's always fun to implement something in Rust.
1618
17- Can pass all of original `examples` tests19## Compliance with the [specification](https://jsonnet.org/ref/spec.html)
18- Can pass all of original `test_suite` tests, expect those, which checks golden output for stacktraces (vanilla-like stacktraces are implemented, but look is not 100% identical): ![Example output](./traces.png)
1920
21- Passes all the original `examples` tests
22
23- Passes all the original `test_suite` tests except for those which require stacktraces identical to the default implementation (while also being available, vanilla-like stacktraces are not 100% identical):
24
25  ```jsonnet
26  ## Explaining format
27  ​```
28  RuntimeError("3")
29   --> /home/lach/jsonnet-rs/a.jsonnet:1:25
30    |
31  1 | local a = "%0 10.20d" % error "3";
32    |                         ^^^^^^^^^ error statement
33    |
34   --> /home/lach/jsonnet-rs/a.jsonnet:1:11
35    |
36  1 | local a = "%0 10.20d" % error "3";
37    |           ^^^^^^^^^^^^^^^^^^^^^^^ function <mod> call
38    |
39   --> /home/lach/jsonnet-rs/a.jsonnet:6:6
40    |
41  6 |   a: a,
42    |      ^ variable <a>
43    |
44   --> /home/lach/jsonnet-rs/a.jsonnet:3:6
45    |
46  3 |   b: self.a,
47    |      ^^^^^^ field access
48    |
49   --> /home/lach/jsonnet-rs/a.jsonnet:9:1
50    |
51  9 | e.b
52    | ^^^ field access
53    |
54  ​```
55
56  ## Compact format (default)
57  ​```
58  RuntimeError("3")
59      /home/lach/jsonnet-rs/a.jsonnet:1:25-35: error statement
60      /home/lach/jsonnet-rs/a.jsonnet:6:6-8  : variable <a>
61      /home/lach/jsonnet-rs/a.jsonnet:3:6-13 : field access
62      /home/lach/jsonnet-rs/a.jsonnet:9:1-5  : field access
63  ​```
64
65  ## Vanilla format
66  ​```
67  RUNTIME ERROR: 3
68          a.jsonnet:1:25-34       thunk <a> from <$>
69          <std>:237:21-22 thunk from <function <anonymous>>
70          <std>:754:20-24 thunk from <function <anonymous>>
71          <std>:32:25-26  thunk from <function <anonymous>>
72          <std>:32:16-27  function <anonymous>
73          <std>:754:8-25  function <anonymous>
74          <std>:237:7-23  function <anonymous>
75
76          a.jsonnet:6:6-7 object <d>
77          a.jsonnet:3:6-12        object <c>
78          a.jsonnet:9:1-4 $
79          During evaluation
80  ​```
81  ```
82
20## Bindings83## Bindings
84
85Jrsonnet provides a standard `libjsonnet.so` shared library and should work as drop-in replacement for it
86
87WASM bingings are also available, Java bindings (Both JNI and WASM compiled to .class) are in progress
2188
22Jrsonnet implements standard `libjsonnet.so` shared library, and should work as drop-in replacement for it89See [bindings](./bindings/) for more information.
2390
24WASM bindings are also available, Java bindings (Both JNI and WASM to .class compiled) are in progress91## Benchmarks
2592
26See `./bindings/`93This is the fastest implementation of jsonnet both according to official benchmarks and real-life cluster configuration templating speed.
2794
28## Benchmark95Official benchmark results are available [in this gist](https://gist.github.com/CertainLach/5770d7ad4836066f8e0bd91e823e451b) which may get updated sometimes. It shows tests against Golang, C++ and Scala implementations showing the best performance in most cases.
2996
30This is fastest implementation of jsonnet, according to both official benchmarks97You can generate this report via
31and mine cluster configuration templating speed
3298
99```bash
33Official benchmark report are available [in this gist](https://gist.github.com/CertainLach/5770d7ad4836066f8e0bd91e823e451b), and updated sometimes. Here it tested against golang, C++, and scala impl. As you can see, it is a lot faster100$ make benchmarks
101```
34102
35TODO: Create docker container for easier benchmarking and/or benchmark in CI103 However it may not work until you link golang jsonnet implementation to `gojsonnet` and C++ implementation to `jsonnet`.
36104
37Also, there is some ideas to improve performance even further, by i.e:105## TO-DO list
38106
39- Mutating strings/arrays/objects instead of cloning on some operations (I.e concat), it should be possible by checking strong reference count, and mutating if there is only one reference107- [ ] Create docker container for easier benchmarking and/or benchmark in CI
108- [ ] Implement and utilize mutable strings, arrays and objects instead of COWing when possible
40109