Skip to content

Latest commit

 

History

History
180 lines (117 loc) · 5.58 KB

README.md

File metadata and controls

180 lines (117 loc) · 5.58 KB
Raw

The RCL Configuration Language

RCL is a domain-specific language optimized for specifying human-written data with just enough abstraction features to avoid repetition. It is a superset of json that extends it into a simple functional programming language that resembles Python and Nix. Use cases include:

  • Querying json documents, like jq, but with a more familiar language.
  • Generating repetitive configuration files, such as GitHub Actions workflows or Terraform configuration.
  • Enabling large repositories to split configuration into small reusable pieces that can be referenced from a single consistent entry point, in the same way that Nix enables this for Nixpkgs.
  • Sharing configuration between tools that do not natively share data. For example, import the same user account definitions into Terraform, Tailscale, Kubernetes, and Ansible.

RCL can be used through the rcl command-line tool that can export documents to json and other formats. It can also be used through a native Python module, with an interface similar to the json module.

Warning

While RCL is usable, it is still in an early exploratory stage with frequent breaking changes. This is a hobby project without stability promise.

Getting started

There are examples and a browser-based interactive demo at rcl-lang.org. For more detailed information, the manual is the best resource. The most useful chapters to get started:

You may also find the examples in the examples directory instructive.

Rationale

Why another config language?

  • HCL is too ad-hoc to be suitable for any serious abstraction (setunion is variadic so it only works with a statically known number of sets; flatten recursively flattens so it can’t be typed properly and breaks generic code, for comprehensions can’t do nested loops, for_each syntax is bolted on, etc.)

  • Nix-the-language is great but forces the entire Nix store on you when all I want is to evaluate expressions.

  • Python is great but requires some boilerplate for doing the IO if you want to use it as a configuration language. Also the syntactic order of list comprehensions prevents autocomplete in editors.

  • Dhall has the right ideas but the syntax and heavy use of Unicode symbols make it look ugly.

  • CUE and Nickel were not invented here.

  • For more background, see the blog post: A reasonable configuration language.

Classification

  • Purely functional: RCL documents are expressions that evaluate to values, rather than sequences of statements that have side effects. Values are immutable, there are no mutable objects. Functions are values.

  • Gradually typed: Optional type annotations can be used to prevent bugs and to make code more self-documenting. All type annotations are enforced.

  • Json superset: Vaporware, this is not fully implemented; floats are not yet supported.

Usage

Build:

cargo build --release

Print usage:

target/release/rcl
target/release/rcl eval --help

Evaluate an RCL expression to json:

target/release/rcl eval --format=json examples/tags.rcl

Query an RCL or json document:

target/release/rcl query examples/tags.rcl input.tags.ams01

Autoformat an RCL expression (non-destructive, prints to stdout):

target/release/rcl fmt examples/tags.rcl

Highlight an RCL expression in your terminal:

target/release/rcl highlight examples/tags.rcl

Development

Run all tests and checks below in one command:

nix flake check

Run golden tests:

cargo build
golden/run.py

Check the grammar for ambiguities:

bison -Werror=all grammar/bison/grammar.y

Run unit tests and lints:

cargo test
cargo clippy

Typecheck Python sources

mypy --strict --exclude pyrcl .
mypy --strict pyrcl

Check formatting:

cargo fmt
black .

View coverage of the golden tests:

nix build .#coverage --out-link result
xdg-open result/index.html

For how to run the fuzzers, see docs/testing.md.

Building the Python module

Build the shared object:

cargo build --manifest-path pyrcl/Cargo.toml

Give the shared object the appropriate name for the Python interpreter to discover it:

mv target/debug/{libpyrcl,rcl}.so

Tell Python where to find the shared object, run the interpreter:

PYTHONPATH=target/debug python3
>>> import rcl
>>> help(rcl.loads)
>>> rcl.load_file("examples/buckets.rcl")

Building WASM

See the readme in the wasm directory.

License

RCL is licensed under the Apache 2.0 license. It may be used in free software as well as closed-source applications, both for commercial and non-commercial use under the conditions given in the license. If you want to use RCL in your GPLv2-licensed software, you can add an exception to your copyright notice. Please do not open an issue if you disagree with the choice of license.