From 656c8fd8cae24749a5948a21375a719086d77e8d Mon Sep 17 00:00:00 2001 From: progrm_jarvis Date: Tue, 21 Jul 2020 15:50:51 +0000 Subject: [PATCH] docs: refactor README.md --- --- a/README.md +++ b/README.md @@ -1,39 +1,108 @@ # jrsonnet +![Crates.io](https://img.shields.io/crates/v/jrsonnet) + ## What is it -[Jsonnet](https://jsonnet.org/) is a json templating language +[Jsonnet](https://jsonnet.org/) is a data templating language -This crate implements both jsonnet library, and alternative jsonnet executable +This Rust crate implements both jsonnet library and an alternative `jsonnet` executable based on it. For more information see [bindings](#Bindings). -## Why +## Why? -There 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) +There 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). -It is fun to write one in Rust :D +This implementation shows performance better than all existing implementations. For more information see [benchmarks](#Benchmarks). -## Spec support +In the end, it's always fun to implement something in Rust. + +## Compliance with the [specification](https://jsonnet.org/ref/spec.html) -- Can pass all of original `examples` tests -- 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) +- Passes all the original `examples` tests + +- 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): + ```jsonnet + ## Explaining format + ​``` + RuntimeError("3") + --> /home/lach/jsonnet-rs/a.jsonnet:1:25 + | + 1 | local a = "%0 10.20d" % error "3"; + | ^^^^^^^^^ error statement + | + --> /home/lach/jsonnet-rs/a.jsonnet:1:11 + | + 1 | local a = "%0 10.20d" % error "3"; + | ^^^^^^^^^^^^^^^^^^^^^^^ function call + | + --> /home/lach/jsonnet-rs/a.jsonnet:6:6 + | + 6 | a: a, + | ^ variable + | + --> /home/lach/jsonnet-rs/a.jsonnet:3:6 + | + 3 | b: self.a, + | ^^^^^^ field access + | + --> /home/lach/jsonnet-rs/a.jsonnet:9:1 + | + 9 | e.b + | ^^^ field access + | + ​``` + + ## Compact format (default) + ​``` + RuntimeError("3") + /home/lach/jsonnet-rs/a.jsonnet:1:25-35: error statement + /home/lach/jsonnet-rs/a.jsonnet:6:6-8 : variable + /home/lach/jsonnet-rs/a.jsonnet:3:6-13 : field access + /home/lach/jsonnet-rs/a.jsonnet:9:1-5 : field access + ​``` + + ## Vanilla format + ​``` + RUNTIME ERROR: 3 + a.jsonnet:1:25-34 thunk from <$> + :237:21-22 thunk from > + :754:20-24 thunk from > + :32:25-26 thunk from > + :32:16-27 function + :754:8-25 function + :237:7-23 function + + a.jsonnet:6:6-7 object + a.jsonnet:3:6-12 object + a.jsonnet:9:1-4 $ + During evaluation + ​``` + ``` + ## Bindings -Jrsonnet implements standard `libjsonnet.so` shared library, and should work as drop-in replacement for it +Jrsonnet provides a standard `libjsonnet.so` shared library and should work as drop-in replacement for it -WASM bindings are also available, Java bindings (Both JNI and WASM to .class compiled) are in progress +WASM bingings are also available, Java bindings (Both JNI and WASM compiled to .class) are in progress -See `./bindings/` +See [bindings](./bindings/) for more information. -## Benchmark +## Benchmarks + +This is the fastest implementation of jsonnet both according to official benchmarks and real-life cluster configuration templating speed. -This is fastest implementation of jsonnet, according to both official benchmarks -and mine cluster configuration templating speed +Official 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. + +You can generate this report via -Official 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 faster +```bash +$ make benchmarks +``` -TODO: Create docker container for easier benchmarking and/or benchmark in CI + However it may not work until you link golang jsonnet implementation to `gojsonnet` and C++ implementation to `jsonnet`. -Also, there is some ideas to improve performance even further, by i.e: +## TO-DO list -- 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 reference +- [ ] Create docker container for easier benchmarking and/or benchmark in CI +- [ ] Implement and utilize mutable strings, arrays and objects instead of COWing when possible -- gitstuff