diff --git a/README.md b/README.md index b7b27bc..d5ac280 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,19 @@ # `dhall-haskell` -This repository is a shared repository for all of the `dhall-*` Haskell -packages, including: +You will probably want to read the language-agnostic `README` here: -* [`dhall`](./dhall) -* [`dhall-bash`](./dhall-bash) -* [`dhall-json`](./dhall-json) -* [`dhall-text`](./dhall-text) +* [`dhall-lang` `README`](https://github.com/dhall-lang/dhall-lang/blob/master/README.md) + +This repository focuses on the Haskell bindings to Dhall and contains +the following packages: + +* [`dhall`](./dhall) - [![Hackage](https://img.shields.io/hackage/v/dhall-bash.svg)](https://hackage.haskell.org/package/dhall-bash) +* [`dhall-bash`](./dhall-bash) - [![Hackage](https://img.shields.io/hackage/v/dhall-bash.svg)](https://hackage.haskell.org/package/dhall-bash) +* [`dhall-json`](./dhall-json) - [![Hackage](https://img.shields.io/hackage/v/dhall-json.svg)](https://hackage.haskell.org/package/dhall-json) +* [`dhall-text`](./dhall-text) - [![Hackage](https://img.shields.io/hackage/v/dhall-text.svg)](https://hackage.haskell.org/package/dhall-text) Navigate to each package's directory for their respective `README`s -# Quick start - ## Building from source ### [cabal](https://www.haskell.org/cabal) @@ -41,6 +43,34 @@ $ nix-build ... or you can run `nix-build` within each package's respective directory to build just that one package. +You can install all of the packages by running: + +``` +$ nix-env --install --file default.nix +``` + +... or you can run the same command within each package's respective directory +to install just that one package. + +You can develop any package by navigating to that package's directory and +running: + +```bash +$ nix-shell +[nix-shell]$ cabal configure +[nix-shell]$ cabal build +[nix-shell]$ cabal test +``` + +... or you can add `nix: True` to your `~/.cabal/config` file and then you can +run the same `cabal` commands without an explicit `nix-shell`: + +```bash +$ cabal configure +$ cabal build +$ cabal test +``` + ### [stack](https://docs.haskellstack.org) You can build all of the packages with @@ -55,15 +85,7 @@ And each of them with `stack build `, for example: $ stack build dhall-json ``` - -## Development status - -[![Build Status](https://travis-ci.org/dhall-lang/dhall-haskell.png)](https://travis-ci.org/dhall-lang/dhall-haskell) - -The compiler is built upon a theoretically sound foundation, meaning that if -there are no bugs then the language will never crash and will always halt. -However, in practice the compiler needs to be battle-tested to weed out any -implementation bugs, so please open issues! 🙂 +## Contributing Read the following guide if you would like to contribute: diff --git a/dhall-bash/README.md b/dhall-bash/README.md index 5d47825..e59dd45 100644 --- a/dhall-bash/README.md +++ b/dhall-bash/README.md @@ -1,7 +1,5 @@ # `dhall-bash 1.0.17` -[![Hackage](https://img.shields.io/hackage/v/dhall-bash.svg)](https://hackage.haskell.org/package/dhall-bash) - This `dhall-bash` package provides a Dhall to Bash compiler so that you can easily marshall Dhall values into your Bash scripts @@ -9,12 +7,9 @@ This does not compile all available Dhall language constructs into Bash and only supports extracting primitive values, lists, optional values and records from normalized expressions. -## Quick start - -If you have Nix installed, then you can build and install this package using: +## Example ```bash -$ nix-env --install --file default.nix $ dhall-to-bash <<< '1' 1 $ dhall-to-bash <<< '"ABC" ++ "DEF"' @@ -25,7 +20,7 @@ $ eval $(dhall-to-bash --declare FOO <<< '"ABC" ++ "DEF"') $ echo "${FOO}" ABCDEF $ dhall-to-bash --declare BAR -let replicate = https://ipfs.io/ipfs/QmcTbCdS21pCxXysTzEiucDuwwLWbLUWNSKwkJVfwpy2zK/Prelude/List/replicate +let replicate = https://prelude.dhall-lang.org/List/replicate in replicate 10 Natural 1 declare -r -a BAR=(1 1 1 1 1 1 1 1 1 1) diff --git a/dhall-json/README.md b/dhall-json/README.md index 327d41b..eca519b 100644 --- a/dhall-json/README.md +++ b/dhall-json/README.md @@ -1,23 +1,18 @@ # `dhall-json 1.2.5` -[![Hackage](https://img.shields.io/hackage/v/dhall-json.svg)](https://hackage.haskell.org/package/dhall-json) - This `dhall-json` package provides a Dhall to JSON compiler and a Dhall to YAML compiler. The reason this package is called `dhall-json` is that the Haskell `yaml` library uses the same data structure as Haskell's `aeson` library for JSON -## Quick start - -If you have Nix installed then you can build and run this package using: +## Example ```bash -$ nix-build -$ result/bin/dhall-to-json <<< "{ foo = 1, bar = True }" +$ dhall-to-json <<< "{ foo = 1, bar = True }" {"foo":1,"bar":true} -$ result/bin/dhall-to-json <<< "List/head Integer ([] : List Integer)" +$ dhall-to-json <<< "List/head Natural ([] : List Natural)" null -$ result/bin/dhall-to-yaml <<< "{ foo = [1, 2, 3] : List Integer, bar = { baz = True } }" +$ dhall-to-yaml <<< "{ foo = [1, 2, 3], bar = { baz = True } }" foo: - 1 - 2 diff --git a/dhall-text/README.md b/dhall-text/README.md index ae72048..a9a2778 100644 --- a/dhall-text/README.md +++ b/dhall-text/README.md @@ -1,11 +1,11 @@ # `dhall-text 1.0.14` -[![Hackage](https://img.shields.io/hackage/v/dhall-text.svg)](https://hackage.haskell.org/package/dhall-text) - This `dhall-text` package provides a `dhall-to-text` executable which you can use to template text using the Dhall configuration language. -For example, suppose you save the following files to your current directory: +## Example + +Suppose you save the following files to your current directory: ```haskell $ cat Person @@ -24,13 +24,14 @@ $ cat people , { name = "Pranav", upvotes = 1 } ] --- This file has type: --- --- ./people : List { name : Text, upvotes : Natural } --- --- ... or just: --- --- ./people : List ./Person +{- This file has type: + + ./people : List { name : Text, upvotes : Natural } + + ... or just: + + ./people : List ./Person +-} ``` ```haskell @@ -38,31 +39,36 @@ $ cat make-item -- You can define anonymous functions in Dhall using a backslash (i.e. `\`) \(person : ./Person) -- You can import any type or expression by its path - -- Dhall supports multiline strings that strip leading whitespace and Dhall - -- supports string interpolation, too, using `${...}` syntax --> '' + {- Dhall supports multiline strings that strip leading whitespace and Dhall + supports string interpolation, too, using `${...}` syntax + -} +-> ''
  • ${Natural/show person.upvotes} ${person.name}
    • '' --- This file has type: --- --- ./make-item : ./Person -> Text +{- This file has type: + + ./make-item : ./Person -> Text +-} ``` ```haskell $ cat make-items - -- You can also import any type or expression by its URL - let List/map = https://raw.githubusercontent.com/dhall-lang/Prelude/302881a17491f3c72238975a6c3e7aab603b9a96/List/map -in let Text/concat = https://raw.githubusercontent.com/dhall-lang/Prelude/302881a17491f3c72238975a6c3e7aab603b9a96/Text/concat -in \(people : List ./Person) --> Text/concat (List/map ./Person Text ./make-item people) +-- You can also import any type or expression by its URL +let List/map = https://prelude.dhall-lang.org/List/map --- This file has type: --- --- ./make-items : List ./Person -> Text +let Text/concat = https://prelude.dhall-lang.org/Text/concat + +in \(people : List ./Person) -> + Text/concat (List/map ./Person Text ./make-item people) + +{- This file has type: + + ./make-items : List ./Person -> Text +-} ``` Templating HTML is just ordinary function application: @@ -88,11 +94,3 @@ $ dhall-to-text <<< './make-items ./people' To learn more about the Dhall configuration language, [read the tutorial](https://hackage.haskell.org/package/dhall/docs/Dhall-Tutorial.html) - -## Quick start - -If you have Nix then you can install this package using: - -```bash -$ nix-env --install --file default.nix -``` diff --git a/dhall/README.md b/dhall/README.md index 90311da..0aac543 100644 --- a/dhall/README.md +++ b/dhall/README.md @@ -1,18 +1,9 @@ # `dhall 1.19.1` -[![Hackage](https://img.shields.io/hackage/v/dhall.svg)](https://hackage.haskell.org/package/dhall) - Dhall is a programmable configuration language that is not Turing-complete You can think of Dhall as: JSON + functions + types + imports -You will probably want to read the language-agnostic README here: - -* [`dhall-lang` `README`](https://github.com/dhall-lang/dhall-lang/blob/master/README.md) - -This repository (and this `README`) focuses on the Haskell implementation of -Dhall - ## Motivation *"Why not configure my program using JSON or YAML?"* @@ -33,7 +24,7 @@ You probably don't want to rebuild your program every time you make a configuration change. Recompilation is slow and requires the GHC toolchain to be installed anywhere you want to make configuration changes. -## Quick start +## Example Given this Haskell program saved to `example.hs`: @@ -104,38 +95,6 @@ Bool False ``` -Now go read the -[Dhall tutorial](https://hackage.haskell.org/package/dhall/docs/Dhall-Tutorial.html) -to learn more +Now go read the [Dhall tutorial][haskell-tutorial] to learn more. -## Building this project - -Nix + Cabal is the recommended workflow for project development since continuous -integration uses Nix to build and test the project. Other development tools and -workflows are also supported on a best-effort basis. - -You can build the project using only Nix by running this command from the root -of the repository: - -```bash -$ nix-build -``` - -More commonly, you will want to incrementally build the project using `cabal`. -You can either do so inside of a `nix-shell`: - -```bash -$ nix-shell -[nix-shell]$ cabal configure -[nix-shell]$ cabal build -[nix-shell]$ cabal test -``` - -... or you can add `nix: True` to your `~/.cabal/config` file and then you can -run the same `cabal` commands without an explicit `nix-shell`: - -```bash -$ cabal configure -$ cabal build -$ cabal test -``` +[haskell-tutorial]: https://hackage.haskell.org/package/dhall/docs/Dhall-Tutorial.html