25 releases
0.12.1 | Feb 1, 2023 |
---|---|
0.12.0 | Aug 15, 2022 |
0.11.2 | Jun 24, 2022 |
0.11.0 | Jan 1, 2022 |
0.2.0 | Dec 24, 2019 |
#544 in Encoding
13,718 downloads per month
Used in 12 crates
(10 directly)
400KB
9K
SLoC
Dhall is a programmable configuration language optimized for maintainability.
You can think of Dhall as: JSON + functions + types + imports
Note that while Dhall is programmable, Dhall is not Turing-complete. Many of Dhall's features take advantage of this restriction to provide stronger safety guarantees and more powerful tooling.
You can find more details about the language by visiting the official website:
dhall-rust
This is the Rust implementation of the Dhall configuration language. It is meant to be used to integrate Dhall in your application.
If you only want to convert Dhall to/from JSON or YAML, you should use the official tooling instead; instructions can be found here.
Usage
For now, the only supported way of integrating Dhall in your application is via
the serde_dhall
crate, and only parsing is supported.
Add this to your Cargo.toml
:
[dependencies]
serde_dhall = "0.12.1"
Reading Dhall files is easy and leverages the wonderful serde
library.
use std::collections::BTreeMap;
// Some Dhall data
let data = "{ x = 1, y = 1 + 1 } : { x: Natural, y: Natural }";
// Deserialize it to a Rust type.
let deserialized_map: BTreeMap<String, u64> = serde_dhall::from_str(data).parse().unwrap();
let mut expected_map = BTreeMap::new();
expected_map.insert("x".to_string(), 1);
expected_map.insert("y".to_string(), 2);
assert_eq!(deserialized_map, expected_map);
dhall
requires Rust >= 1.60.0
Standard-compliance
This implementation currently supports most of the Dhall
standard version 20.0.0
.
The main missing feature is import headers. See here for a list of the other missing features.
Contributing
This section will cover how we can get started on contributing this project.
Setting up the repository
To get a copy of this repository we can run:
$ git clone https://github.com/Nadrieril/dhall-rust.git
But we also might note that it's better practice to fork the repository to your own workspace. There you can make changes and submit pull requests against this repository.
After the repositry has been cloned we need to update the git submodule
in the project, i.e. dhall-lang
. We can do this by running:
$ git submodule update --init --recursive
Building and Testing
A preferred method among the Rust community for developing is to use rustup
.
It can be installed by running:
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
or if nix is your tool of choice:
$ nix-shell -p rustup
Once rustup
is installed we can get it to manage our toolchain by running:
$ rustup toolchain install stable
Then we can manage our building and testing with the cargo
dependency manager:
$ cargo build
$ cargo test -- -q
You can also run tests individually by their name:
$ cargo test tests::spec::name_of_test
Now we can have fun and happy contributing!
Test suite
The test suite uses tests from the dhall-lang submodule as well as from the
local dhall/tests
directory.
The various tests are run according to the instructions present in
dhall-lang/tests/README.md
.
If an output test file (a fooB.dhall
file) is missing, we will generate it automatically.
This is useful when writing new tests. Don't forget to commit it to git !
If one of the specification tests fails but you prefer the new output, you can
run the test(s) with --bless
to overwrite the result file with the new
output. This happens often with ui tests (see below), since we may want to
change the phrasing of errors for example. Note that the --bless
argument is
only accepted by the spec
tests and will not be recognized if you also run
other test.
$ cargo test --test spec -- -q --bless
In addition to the usual dhall tests, we additionally run "ui tests", that
ensure that the output of the various errors stays good.
The output of the ui tests is stored in the local dhall/tests
directory, even
for the tests coming from dhall-lang. They are stored in a .txt
file with the
same name as the corresponding test.
Commit messages
I try to keep commit messages somewhat in the style of Conventional
Commits. That means the commit
message should start with feat:
, test:
, spec:
, doc:
, fix:
, style:
,
refactor:
, chore:
, perf:
or similar prefixes.
A breaking change should be indicated with !
before the :
.
Changelog
License
Licensed under the terms of the 2-Clause BSD License (LICENSE or https://opensource.org/licenses/BSD-2-Clause)
Dependencies
~7–20MB
~281K SLoC