difftreelog
docs refactor README.md
in: master
2 files changed
README.mddiffbeforeafterboth--- a/README.md
+++ b/README.md
@@ -1,39 +1,108 @@
# 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): 
+- 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 <mod> call
+ |
+ --> /home/lach/jsonnet-rs/a.jsonnet:6:6
+ |
+ 6 | a: a,
+ | ^ variable <a>
+ |
+ --> /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 <a>
+ /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 <a> from <$>
+ <std>:237:21-22 thunk from <function <anonymous>>
+ <std>:754:20-24 thunk from <function <anonymous>>
+ <std>:32:25-26 thunk from <function <anonymous>>
+ <std>:32:16-27 function <anonymous>
+ <std>:754:8-25 function <anonymous>
+ <std>:237:7-23 function <anonymous>
+
+ a.jsonnet:6:6-7 object <d>
+ a.jsonnet:3:6-12 object <c>
+ 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
traces.pngdiffbeforeafterbothbinary blob — no preview