diff --git a/README.adoc b/README.adoc new file mode 100644 index 00000000..1779b051 --- /dev/null +++ b/README.adoc @@ -0,0 +1,87 @@ += jrsonnet + +image:https://img.shields.io/github/v/tag/CertainLach/jrsonnet?color=%23fb4934&label=latest%20release&style=for-the-badge[alt=release, link=https://github.com/CertainLach/jrsonnet/releases] +image:https://img.shields.io/github/license/CertainLach/jrsonnet?color=%2383a598&label=license&style=for-the-badge[alt=license, ./LICENSE] +image:https://img.shields.io/opencollective/all/jrsonnet?color=%238ec07c&style=for-the-badge[alt=opencollective, link=https://opencollective.com/jrsonnet] + +== What is it + +https://jsonnet.org/[Jsonnet] is a data templating language + +This Rust crate implements both jsonnet library and an alternative `jsonnet` executable based on it. +For more information see [bindings](#Bindings). + +== Install + +=== NixOS + +jrsonnet is packaged in nixpkgs and maintained by @CertainLach + +[source,sh] +---- +nix-env -iA nixpkgs.jrsonnet +---- + +=== MacOS + +jrsonnet is packaged to brew and maintained by @messense + +[source,sh] +---- +brew install jrsonnet +---- + +=== Windows/other linux distributions + +You can get latest build of jrsonnet in https://github.com/CertainLach/jrsonnet/releases[releases]. + +=== Build from sources + +jrsonnet should build on latest stable Rust version (probally on olders, but there is no MSRV policy provided) + +Debug build will work too, but it is much slower than release + +[source] +---- +cargo build --release +---- + +== Why? + +There already are multiple implementations of this standard implemented in different languages: + +* https://github.com/google/jsonnet[C++]; +* https://github.com/google/go-jsonnet/[Go]; +* https://github.com/databricks/sjsonnet[Scala]. + +This implementation shows performance better than all existing implementations. +For more information see link:./docs/benchmarks.md[benchmarks] + +Also, I wanted to experiment on new syntax features, and jrsonnet implements some of them. For more information see [features](./docs/features.md) + +In the end, it's always fun to implement something in Rust. + +== Bindings + +=== Rust + +image:https://img.shields.io/crates/v/jrsonnet-evaluator[alt=crates.io, link=https://crates.io/crates/jrsonnet-evaluator] +image:https://docs.rs/jrsonnet-evaluator/badge.svg[alt=docs.rs, link=https://docs.rs/jrsonnet-evaluator] + +Jrsonnet is written in rust itself, so just add it as dependency + +=== Python + +image:https://img.shields.io/pypi/v/rjsonnet[alt=crates.io, link=https://pypi.org/project/rjsonnet/] + +Bindings are created and maintained by @messense + +=== C/C++ + +Jrsonnet provides a standard `libjsonnet.so` shared library and should work as drop-in replacement for it + +=== Other + +WASM bingings are also available, Java bindings (Both JNI and WASM compiled to .class) are in progress + +See link:./bindings/[bindings] for more information. diff --git a/README.md b/README.md deleted file mode 100644 index 532e1a7c..00000000 --- a/README.md +++ /dev/null @@ -1,78 +0,0 @@ -# jrsonnet - -[![release](https://img.shields.io/github/v/tag/CertainLach/jrsonnet?color=%23fb4934&label=latest%20release&style=for-the-badge)](https://github.com/CertainLach/jrsonnet/releases) -[![license](https://img.shields.io/github/license/CertainLach/jrsonnet?color=%2383a598&label=license&style=for-the-badge)](/LICENSE) -[![opencollective](https://img.shields.io/opencollective/all/jrsonnet?color=%238ec07c&style=for-the-badge)](https://opencollective.com/jrsonnet) - -## What is it - -[Jsonnet](https://jsonnet.org/) is a data templating language - -This Rust crate implements both jsonnet library and an alternative `jsonnet` executable based on it. For more information see [bindings](#Bindings). - -## Install - -### NixOS - -jrsonnet is packaged in nixpkgs and maintained by @CertainLach - -```sh -nix-env -iA nixpkgs.jrsonnet -``` - -### MacOS - -jrsonnet is packaged to brew and maintained by @messense - -```sh -brew install jrsonnet -``` - -### Windows/other linux distributions - -You can get latest build of jrsonnet in [releases](https://github.com/CertainLach/jrsonnet/releases) - -### Build from sources - -jrsonnet should build on latest stable Rust version (probally on olders, but there is no MSRV policy provided) - -Debug build will work too, but it is much slower than release - -``` -cargo build --release -``` - -## Why? - -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). - -This implementation shows performance better than all existing implementations. For more information see [benchmarks](./docs/benchmarks.md). - -Also, I wanted to experiment on new syntax features, and jrsonnet implements some of them. For more information see [features](./docs/features.md) - -In the end, it's always fun to implement something in Rust. - -## Bindings - -### Rust - -[![crates.io](https://img.shields.io/crates/v/jrsonnet-evaluator)](https://crates.io/crates/jrsonnet-evaluator) -[![docs.rs](https://docs.rs/jrsonnet-evaluator/badge.svg)](https://docs.rs/jrsonnet-evaluator) - -Jrsonnet is written in rust itself, so just add it as dependency - -### Python - -[![crates.io](https://img.shields.io/pypi/v/rjsonnet)](https://pypi.org/project/rjsonnet/) - -Bindings are created and maintained by @messense - -### C/C++ - -Jrsonnet provides a standard `libjsonnet.so` shared library and should work as drop-in replacement for it - -### Other - -WASM bingings are also available, Java bindings (Both JNI and WASM compiled to .class) are in progress - -See [bindings](./bindings/) for more information. diff --git a/bindings/README.md b/bindings/README.adoc similarity index 55% rename from bindings/README.md rename to bindings/README.adoc index d510bf70..9ddd35c4 100644 --- a/bindings/README.md +++ b/bindings/README.adoc @@ -1,16 +1,18 @@ -# Native bindings += Native bindings -Bindings are implemented in form of standard libjsonnet.so implementation +Bindings are implemented in form of standard libjsonnet.so implementation. -Headers are described in `c/libjsonnet.h`, this file is exact copy from `C` implementation of jsonnet, plus additional jrsonnet-specific methods +Headers are described in `c/libjsonnet.h`, this file is exact copy from `C` implementation of jsonnet, +plus additional jrsonnet-specific methods. -Bindings should work as drop-in replacement for standard impl +Bindings should work as drop-in replacement for standard impl. -## Building Linux .so library on MacOS +== Building Linux .so library on MacOS You can use `cross-rs` to do so: -```console +[source,console] +---- cargo install cross --git https://github.com/cross-rs/cross cross build --release -p libjsonnet --target x86_64-unknown-linux-gnu -``` +---- diff --git a/bindings/jsonnet/README.adoc b/bindings/jsonnet/README.adoc new file mode 100644 index 00000000..8c572e7e --- /dev/null +++ b/bindings/jsonnet/README.adoc @@ -0,0 +1 @@ += libjsonnet.so implemented in Rust diff --git a/bindings/jsonnet/README.md b/bindings/jsonnet/README.md deleted file mode 100644 index 25c2ade6..00000000 --- a/bindings/jsonnet/README.md +++ /dev/null @@ -1 +0,0 @@ -# libjsonnet.so implemented in Rust diff --git a/crates/jrsonnet-evaluator/README.md b/crates/jrsonnet-evaluator/README.adoc similarity index 63% rename from crates/jrsonnet-evaluator/README.md rename to crates/jrsonnet-evaluator/README.adoc index 723dd6bf..a9e3ea4a 100644 --- a/crates/jrsonnet-evaluator/README.md +++ b/crates/jrsonnet-evaluator/README.adoc @@ -1,3 +1,3 @@ -# jrsonnet-evaluator += jrsonnet-evaluator Interpreter for parsed jsonnet tree diff --git a/crates/jrsonnet-parser/README.md b/crates/jrsonnet-parser/README.adoc similarity index 61% rename from crates/jrsonnet-parser/README.md rename to crates/jrsonnet-parser/README.adoc index 99e7f491..71bde78d 100644 --- a/crates/jrsonnet-parser/README.md +++ b/crates/jrsonnet-parser/README.adoc @@ -1,3 +1,3 @@ -# jrsonnet-parser += jrsonnet-parser Parser for jsonnet language diff --git a/docs/features.md b/docs/features.adoc similarity index 76% rename from docs/features.md rename to docs/features.adoc index 7ea5db1d..2e2cfbc0 100644 --- a/docs/features.md +++ b/docs/features.adoc @@ -1,109 +1,123 @@ -# Features += Features Some features, which exists in jrsonnet, but not yet in other implementations. Any of those features may be enabled during build time using feature flags, i.e: `--features=exp-destruct`. -## `exp-destruct` +== `exp-destruct` Destructuring assignment, upstream issue: https://github.com/google/jsonnet/issues/307 Destructuring object: -```jsonnet +[source,jsonnet] +---- local {a: b} = obj; ... // Same as local b = obj.a; ... -``` +---- Field name may be omitted: -> However, field name omission looks off here, as currently jsonnet doesn't allows `local a = 1; {a}` as a sugar for `local a = 1; {a: a}`, this causing asymmetry +> However, field name omission looks off here, as currently jsonnet doesn't allows `local a = 1; {a}` +as a sugar for `local a = 1; {a: a}`, this causing asymmetry -```jsonnet +[source,jsonnet] +---- local {a} = obj; ... // Same as local a = obj.a; ... -``` +---- Rest of fields may be collected into another object: -```jsonnet +[source,jsonnet] +---- local {a, ...rest} = obj; ... -``` +---- And it is possible to set field defaults: -```jsonnet +[source,jsonnet] +---- local {a = 1} = {}; a == 1 -``` +---- Destructuring arrays: -```jsonnet +[source,jsonnet] +---- local [a, b, c] = array; ... -``` +---- Rest of fields in any position may be collected into other array: -```jsonnet +[source,jsonnet] +---- local [...rest, a] = array; ... local [a, ...rest] = array; ... local [a, ...rest, b] = array; ... -``` +---- In case of not needed fields there is `?` (because `_` is not reserved): -```jsonnet +[source,jsonnet] +---- local [?, b, c] = ["a", "b", "c"]; ... -``` +---- Recursive destructuring also works: -```jsonnet +[source,jsonnet] +---- local {a: [{b: {c: d}}]} = {a:[{b:{c:5}}]}; d == 5 -``` +---- -Also mutually recursive declaration works: +Also, mutually recursive declaration works: -```jsonnet +[source,jsonnet] +---- local {a, b, c} = {a: y, b: c, c: x}, {x, y, z} = {x: a, y: 2, z: b}; z == 2 -``` +---- This feature also works in function arguments: > It is impossible to reference those parameters using named argument syntax -```jsonnet +[source,jsonnet] +---- local myFun({a, b, c}) = a + b + c; myFun({a: 1, b: 2, c: 3}) -``` +---- -## `exp-preserve-order` +== `exp-preserve-order` Object field order preservation during manifestification, upstream issue: https://github.com/google/jsonnet/issues/903 -This feature adds a new CLI argument: `--preserve-order`, as well as additional `std.manifest*/std.objectFields*` standard library functions argument `preserve_order`. +This feature adds a new CLI argument: `--preserve-order`, +as well as additional `std.manifest*/std.objectFields*` standard library functions argument `preserve_order`. Using this argument, it is possible to have same field order in manifestification, as in declaration: -```jsonnet +[source,jsonnet] +---- std.objectFields({c: 1, b: 2, a: 3}, preserve_order = false) == ['a', 'b', 'c'] # Fields were sorted std.manifestJson({c: 1, b: 2, a: 3}, preserve_order = true) == ['c', 'b', 'a'] # Fields were serialized in declaration order -``` +---- -## `exp-object-iteration` +== `exp-object-iteration` Iteration over object fields in comprehensions, upstream issue: https://github.com/google/jsonnet/issues/543 This feature is not implemented as proposed in upstream, it only yields `[key, value]` arrays per element: -```jsonnet +[source,jsonnet] +---- { [i[0] + '!']: i[1] + '!' for i in { @@ -116,11 +130,12 @@ This feature is not implemented as proposed in upstream, it only yields `[key, v 'b!': '2!', 'c!': '3!', } -``` +---- However, it may be combined with `exp-destruct`, to implement syntax close to proposed: -```jsonnet +[source,jsonnet] +---- { [k + '!']: v + '!' for [k, v] in { @@ -133,11 +148,13 @@ However, it may be combined with `exp-destruct`, to implement syntax close to pr 'b!': '2!', 'c!': '3!', } -``` +---- -Unfortunately, there is no integration with the `exp-preserve-order` feature, fields will be still iterated in sorted order, and using old syntax is required: +Unfortunately, there is no integration with the `exp-preserve-order` feature, +fields will still be iterated in sorted order, and using old syntax is required: -```jsonnet +[source,jsonnet] +---- local obj = { c: 3, b: 2, @@ -152,9 +169,9 @@ local obj = { 'b!': '2!', 'a!': '1!', } -``` +---- -## `exp-null-coalescing` +== `exp-null-coalescing` Provides a new operator and new indexing syntax sugar: