Update `README`s (#732)
This updates all of the `README`s to: * centralize all of the build/install/develop information in the top-level `README` * get the nested `README`s to use a consistent style
This commit is contained in:
Gabriel Gonzalez
GitHub
parent
10a781534d
commit
7dd6b76d04
56
README.md
56
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) - [](https://hackage.haskell.org/package/dhall-bash)
|
||||
* [`dhall-bash`](./dhall-bash) - [](https://hackage.haskell.org/package/dhall-bash)
|
||||
* [`dhall-json`](./dhall-json) - [](https://hackage.haskell.org/package/dhall-json)
|
||||
* [`dhall-text`](./dhall-text) - [](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 <package-name>`, for example:
|
|||
$ stack build dhall-json
|
||||
```
|
||||
|
||||
|
||||
## Development status
|
||||
|
||||
[](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:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,5 @@
|
|||
# `dhall-bash 1.0.17`
|
||||
|
||||
[](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
|
||||
<Ctrl-D>
|
||||
declare -r -a BAR=(1 1 1 1 1 1 1 1 1 1)
|
||||
|
|
|
|||
|
|
@ -1,23 +1,18 @@
|
|||
# `dhall-json 1.2.5`
|
||||
|
||||
[](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
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
# `dhall-text 1.0.14`
|
||||
|
||||
[](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
|
||||
-}
|
||||
-> ''
|
||||
<li class="list-group-item">
|
||||
<span class="badge">${Natural/show person.upvotes}</span>
|
||||
${person.name}
|
||||
</li>
|
||||
''
|
||||
|
||||
-- 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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,18 +1,9 @@
|
|||
# `dhall 1.19.1`
|
||||
|
||||
[](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
|
||||
|
|
|
|||
Loading…
Reference in New Issue