Dhall for Rails

This is Rails bindings for the Dhall configuration language. Dhall is a powerful, but safe and non-Turing-complete configuration language. For more information, see: https://dhall-lang.org

Versioning

This project follows semantic versioning. For the purposes of considering what is a "breaking change" only the API as documented in this README is considered, regardless of any other exposed parts of the library. Anything not documented here may change at any time, but backward-incompatible changes to anything documented here will be accompanied by a major-version increment.

Installation

Add this line to your application's Gemfile:

gem "dhall-rails"

And then execute:

bundle

Or install it yourself as:

gem install dhall-rails

Include in Your Application

To fully enable this gem in your Rails application, add the following line to your class Application in config/application.rb:

include Dhall::Rails::Application

Once you have done this, you must change your config/database.yml for a config/database.dhall. Other configuration can remain in YAML and be converted as desired.

Any YAML file in config/ should be able to be converted to Dhall. Any case where this is not true is considered a bug.

Credentials and Encrypted Config

Files such as config/credentials.dhall.enc will work with Rails' encrypted configuration system, including:

Rails.application.credentials
bin/rails credentials:edit
Rails.application.encrypted(Rails.root.join("config/thing.dhall.enc"))

Custom Configuration

If you have your own custom configuration files for your application that you wish to maintain in Dhall, you can load them using the normal config_for facility:

Rails.application.config_for("something") # loads config/something.dhall at the key for current Rails.env

I18n

If you are still using the YAML-based simple translation framework for Rails, you may use Dhall files here as well. This allows using real functions and string interpolations in your translation files, like so:

en = {
  ducks = \(translation_name: < ducks >) -> \(args: { count: Natural }) ->
    "${Natural/show args.count} ducks"
}

Which can be invoked via:

I18n.t(:ducks, count: 5)

Caching

Integrity-protected Dhall imports will have their normalized contents cached using the normal Rails.cache mechanism.

Reading Rails Configuration

All Dhall files handled by dhall-rails can access any field on the Rails constant like so:

env:"Rails.env"
env:"Rails.root"

Using Dhall for ActiveRecord Serialization

To serialize your columns using Dhall instead of YAML, you may do this:

serialize :column, Dhall::Coder

If you need to serialize more complex objects, you may whitelist classes like so:

serialize :column, Dhall::Coder.new(safe: [NilClass, String, MyClass])

Manually Loading Dhall Expressions

If you wish to manually load a Dhall expression from some source, using the ability to read from properties of Rails, the caching, and other features provided by this library, you may like so:

Dhall::Rails.load("1 + 1") # => #<Dhall::Natural value=2>

Getting Help

If you have any questions about this library, or wish to report a bug, please send email to: dev@singpolyma.net

Contributing

Tests can be run with:

make test

If you have code or patches you wish to contribute, the maintainer's preferred mechanism is a git pull request. Push your changes to a git repository somewhere, for example:

git remote rename origin upstream
git remote add origin git@git.sr.ht:~yourname/dhall-rails
git push -u origin master

Then generate the pull request:

git fetch upstream master
git request-pull -p upstream/master origin

And copy-paste the result into a plain-text email to: dev@singpolyma.net

You may alternately use a patch-based approach as described on https://git-send-email.io

Contributions follow an inbound=outbound model -- you (or your employer) keep all copyright on your patches, but agree to license them according to this project's COPYING file.