dhall-lang / dhall-text Goto Github PK

View Code? Open in Web Editor NEW

21.0 8.0 3.0 38 KB

This repository has moved to https://github.com/dhall-lang/dhall-haskell/tree/master/dhall-text

License: BSD 3-Clause "New" or "Revised" License

Haskell 24.78% Nix 75.22%

dhall template-engine configuration-language

dhall-text's Introduction

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 try the language live in your browser by visiting the official website:

https://dhall-lang.org

Getting started

The easiest way to get started experimenting with Dhall is to install the dhall-to-json and/or dhall-to-yaml executables, which enable you to generate JSON and YAML, respectively, on the command line. Platform- and runtime-specific installation instructions can be found in the Dhall documentation.

For other ways to integrate Dhall in your project, read:

How to integrate Dhall

Tutorials

For a short introduction, read:

Learn Dhall in Y minutes

To learn more about core language features, read:

Core language features

For an even longer hands-on tutorial, read:

Getting started: Generate JSON or YAML

... and for an even longer tutorial, read:

Language Tour

Finally, we have a cheatsheet for a very condensed overview and quick lookup:

Dhall Cheatsheet

What is this repository?

The Dhall configuration language has multiple implementations so that Dhall configuration files can be understood natively by several programming languages. You can find the latest list of the language bindings and their respective repositories here:

How to integrate Dhall - Language support

This repository contains language-independent functionality, such as:

The grammar and formal semantics

Dhall is a formally-specified language standard, and language bindings follow the specification in order to ensure portability of Dhall configuration files across language bindings.
The standard test suite

This repository contains a test suite that language bindings can use to check compliance against the standard.
The Prelude

One Dhall package named the Prelude is versioned with and distributed alongside the language standard. This package contains general-purpose utilities.
Shared infrastructure for the Dhall ecosystem

Several services support Dhall developers and this repository contains a NixOps specification of that infrastructure that automatically deploys changes merged to that configuration.

Development status

The current version and versioning policy is detailed in the Versioning document, and you can see the latest changes in the Changelog.

The Dhall configuration language slowly evolves in response to user feedback and if you would like to participate in the language evolution process then you should read:

CONTRIBUTING.md - How do I change the language

Design philosophy

Programming languages are all about design tradeoffs and the Dhall language uses the following guiding principles (in order of descending priority) that help navigate those tradeoffs:

Polish

The language should delight users. Error messages should be fantastic, execution should be snappy, documentation should be excellent, and everything should "just work".
Simplicity

When in doubt, cut it out. Every configuration language needs bindings to multiple programming languages, and the more complex the configuration language the more difficult to create new bindings. Let the host language that you bind to compensate for any missing features from Dhall.
Beginner-friendliness

Dhall needs to be a language that anybody can learn in a day and debug with little to no assistance from others. Otherwise people can't recommend Dhall to their team with confidence.
Robustness

A configuration language needs to be rock solid. The last thing a person wants to debug is their configuration file. The language should never hang or crash. Ever.
Consistency

There should only be one way to do something. Users should be able to instantly discern whether or not something is possible within the Dhall language or not.

The Dhall configuration language is also designed to negate many of the common objections to programmable configuration files, such as:

"Config files shouldn't be Turing complete"

Dhall is not Turing-complete. Evaluation always terminates, no exceptions

"Configuration languages become unreadable due to abstraction and indirection"

Every Dhall configuration file can be reduced to a normal form which eliminates all abstraction and indirection

"Users will go crazy with syntax and user-defined constructs"

Dhall is a very minimal programming language. For example: you cannot even compare strings for equality. The language also forbids many other common operations in order to force users to keep things simple

Name

The language is named after a Dustman from the game Planescape: Torment who belongs to a faction obsessed with death (termination). The fountain pen in the logo is the modern analog of Dhall's quill.

The name rhymes with "tall"/"call"/"hall" (i.e. "dɔl" for a US speaker or "dɔːl" for a UK speaker using the International Phonetic Alphabet).

Contributors

Code Contributors

This project exists thanks to all the people who contribute. [Contribute].

Financial Contributors

Become a financial contributor and help us sustain our community. [Contribute]

Individuals

Organizations

Support this project with your organization. Your logo will show up here with a link to your website. [Contribute]

dhall-text's People

Contributors

Stargazers

Watchers

Forkers

f-f nicklawls vsund

dhall-text's Issues

Use within Haskell ?

How to use library within Haskell as a html or json templating engine ?
Note: I can't access ipfs functions, the host takes to long to respond.

Where to find releases?

I noticed (while wanting to use the pre-built binaries), that there aren't any pre-built binaries here. Where should we download them?

In particular, I'm looking for a binary that is compatible with dhall version 1.15.1. I guess that would be 1.0.11. Is that right?

Timeout for Prelude (on IPFS)

Hey,

I'd like to play a little bit around with this, but get a timeout from IPFS. I think this is related to the switch from IPFS to GitHub for Prelude (as @Gabriel439 said in #8 (comment)).

I guess this needs a little update due to the IPFS->GitHub switch? :)

For reference the error I'm getting:

$ dhall-to-text <<< './make-items ./people'
dhall-to-text: 
↳ ./make-items
  ↳ https://ipfs.io/ipfs/Qmbh2ifwcpX9a384vJMehySbV7rdvYhzVbL5ySs84k8BgY/Prelude/List/map
HttpExceptionRequest Request {
  host                 = "ipfs.io"
  port                 = 443
  secure               = True
  requestHeaders       = []
  path                 = "/ipfs/Qmbh2ifwcpX9a384vJMehySbV7rdvYhzVbL5ySs84k8BgY/Prelude/List/map"
  queryString          = ""
  method               = "GET"
  proxy                = Nothing
  rawBody              = False
  redirectCount        = 10
  responseTimeout      = ResponseTimeoutDefault
  requestVersion       = HTTP/1.1
}
 ResponseTimeout

$ dhall-to-text version
1.0.11

`version` option

Hi, I just ran into a bit of trouble with dhall-to-text. The problem was in fact that I was on an old version, trying to type-check the dhall prelude.

Here was the massive error:

dhall-to-text: 
↳ ./foo 
  ↳ ./package.dhall 
    ↳ ./List/package.dhall 
      ↳ ./List/shifted 

a : Type
kvss : List (List { index : Natural, value : a })
list : Type
cons : { index : Natural, value : a } → list → list
nil : list

Error: Wrong type of function argument

List/fold
                          (List { index : Natural, value : a })
                          kvss
                          { count : Natural, diff : Natural → list }
                          (   λ(kvs : List { index : Natural, value : a })
                            → λ(y : { count : Natural, diff : Natural → list })
                            →     let length =
                                        List/length
                                        { index : Natural, value : a }
                                        kvs
                              
                              in  { count = y.count + length
                                  , diff  =
                                        λ(n : Natural)
                                      → List/fold
                                        { index : Natural, value : a }
                                        kvs
                                        list
                                        (   λ ( kvOld
                                              : { index : Natural, value : a }
                                              )
                                          → λ(z : list)
                                          →     let kvNew =
                                                      { index = kvOld.index + n
                                                      , value = kvOld.value
                                                      }
                                            
                                            in  cons kvNew z
                                        )
                                        (y.diff (n + length))
                                  }
                          )
                          { count = 0, diff = λ(_ : Natural) → nil }

List/shifted:50:27

I totally understand what the problem was now, but it took a while for me to figure out, and I think I would have found the problem sooner if I could have run dhall-text --version. It doesn't have a version output, so I incorrectly assumed that dhall-to-text was calling the dhall executable.

As always thanks for this amazing tool! I'm hooked.

cabal installing dhall-text from hackage fails for me

cabal --dry-run install -fj | highlight-versions
Resolving dependencies...
In order, the following would be installed (use -v for more details):
Diff-0.3.4
insert-ordered-containers-0.2.1.0
lens-family-core-1.2.2
managed-1.0.6
optional-args-1.0.2
prettyprinter-1.2.1
raw-strings-qq-1.1
repline-0.1.7.0
turtle-1.5.10
prettyprinter-ansi-terminal-1.1.1.2
dhall-1.16.1
dhall-text-1.0.11
mystuff-0.1
Build completed in 0:04m

with a fairly simple cabal file, requiring dhall-text, among others (no particular versions):

...
library
  default-language: Haskell2010
  ghc-options: -Wall -fno-warn-tabs -O0
  hs-source-dirs: .
  

  build-depends:


    base
    , dhall
    , dhall-text
    , text
    , foldl
    , MissingH
    , containers
    , turtle
    , interpolate
    , raw-strings-qq
    , lens

then, when installing:

cabal install

I get this

...
[21 of 25] Compiling Dhall.Tutorial   ( src/Dhall/Tutorial.hs, dist/dist-sandbox-64233c2c/build/Dhall/Tutorial.o )
[22 of 25] Compiling Dhall.TH         ( src/Dhall/TH.hs, dist/dist-sandbox-64233c2c/build/Dhall/TH.o )
[23 of 25] Compiling Dhall.Repl       ( src/Dhall/Repl.hs, dist/dist-sandbox-64233c2c/build/Dhall/Repl.o )
[24 of 25] Compiling Paths_dhall      ( dist/dist-sandbox-64233c2c/build/autogen/Paths_dhall.hs, dist/dist-sandbox-64233c2c/build/Paths_dhall.o )
[25 of 25] Compiling Dhall.Main       ( src/Dhall/Main.hs, dist/dist-sandbox-64233c2c/build/Dhall/Main.o )
Preprocessing executable 'dhall' for dhall-1.16.1..
Building executable 'dhall' for dhall-1.16.1..
[1 of 1] Compiling Main             ( dhall/Main.hs, dist/dist-sandbox-64233c2c/build/dhall/dhall-tmp/Main.o )
Linking dist/dist-sandbox-64233c2c/build/dhall/dhall ...
Installing library in /home/rx/work/shsite/.cabal-sandbox/lib/x86_64-linux-ghc-8.2.2/dhall-1.16.1-J3XTMAVgfGyGaQGFfReRJH
Installing executable dhall in /home/rx/work/shsite/.cabal-sandbox/bin
Installed dhall-1.16.1
Configuring dhall-text-1.0.11...
Preprocessing executable 'dhall-to-text' for dhall-text-1.0.11..
Building executable 'dhall-to-text' for dhall-text-1.0.11..
[1 of 2] Compiling Paths_dhall_text ( dist/dist-sandbox-64233c2c/build/dhall-to-text/autogen/Paths_dhall_text.hs, dist/dist-sandbox-64233c2c/build/dhall-to-text/dhall-to-text-tmp/Paths_dhall_text.o )
[2 of 2] Compiling Main             ( exec/Main.hs, dist/dist-sandbox-64233c2c/build/dhall-to-text/dhall-to-text-tmp/Main.o )
Linking dist/dist-sandbox-64233c2c/build/dhall-to-text/dhall-to-text ...
Installing executable dhall-to-text in /home/rx/work/shsite/.cabal-sandbox/bin
Installed dhall-text-1.0.11
Configuring mystuff-0.1...
cabal: The following package dependencies were requested
--dependency='dhall-text=dhall-text-1.0.11-7IBad3DhNDICxBoVKbrQcM'
however the given installed package instance does not exist.
Failed to install mystuff-0.1
cabal: Error: some packages failed to install:
mystuff-0.1-HZ4xFhaEFzuCzaZ0OYXhSU failed during the configure step. The
exception was:
ExitFailure 1

not sure, what's going on ?

dhall-lang / dhall-text Goto Github PK

dhall-text's Introduction

Getting started

Tutorials

What is this repository?

Development status

Design philosophy

Name

Contributors

Code Contributors

Financial Contributors

Individuals

Organizations

dhall-text's People

Contributors

Stargazers

Watchers

Forkers

dhall-text's Issues

Recommend Projects

Recommend Topics

Recommend Org