Skip to content

Core language features

Gabriel Gonzalez edited this page Feb 26, 2019 · 3 revisions

Let's motivate the Dhall configuration language by considering the following JSON configuration representing Haskell package metadata (wrapped to 80 columns):

[
    {
        "name": "dhall",
        "author": "Gabriel Gonzalez",
        "license": "Copyright 2017 Gabriel Gonzalez\n\nRedistribution and use in
 source and binary forms, with or without\nmodification, are permitted provided
that the following conditions are met:\n\n1. Redistributions of source code must
 retain the above copyright notice, this\n   list of conditions and the followin
g disclaimer.\n\n2. Redistributions in binary form must reproduce the above copy
right notice,\n   this list of conditions and the following disclaimer in the do
cumentation\n   and/or other materials provided with the distribution.\n\n3. Nei
ther the name of the copyright holder nor the names of its contributors\n   may
be used to endorse or promote products derived from this software without\n   sp
ecific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT H
OLDERS AND CONTRIBUTORS \"AS IS\" AND\nANY EXPRESS OR IMPLIED WARRANTIES, INCLUD
ING, BUT NOT LIMITED TO, THE IMPLIED\nWARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
 OR CONTRIBUTORS BE LIABLE\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMP
LARY, OR CONSEQUENTIAL\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF S
UBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRU
PTION) HOWEVER\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRI
CT LIABILITY,\nOR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OU
T OF THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAG
E.\n"
    },
    {
        "name": "conduit",
        "author": "Michael Snoyman",
        "license": "Copyright 2012 Michael Snoyman\n\nPermission is hereby grant
ed, free of charge, to any person obtaining a copy of this software and associat
ed documentation files (the \"Software\"), to deal in the Software without restr
iction, including without limitation the rights to use, copy, modify, merge, pub
lish, distribute, sublicense, and/or sell copies of the Software, and to permit
persons to whom the Software is furnished to do so, subject to the following con
ditions:\n\nThe above copyright notice and this permission notice shall be inclu
ded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PR
OVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BU
T NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PUR
POSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRA
CT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE O
R THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n"
    },
    {
        "name": "async",
        "author": "Simon Marlow",
        "license": "Copyright 2012 Simon Marlow\n\nRedistribution and use in sou
rce and binary forms, with or without\nmodification, are permitted provided that
 the following conditions are met:\n\n1. Redistributions of source code must ret
ain the above copyright notice, this\n   list of conditions and the following di
sclaimer.\n\n2. Redistributions in binary form must reproduce the above copyrigh
t notice,\n   this list of conditions and the following disclaimer in the docume
ntation\n   and/or other materials provided with the distribution.\n\n3. Neither
 the name of the copyright holder nor the names of its contributors\n   may be u
sed to endorse or promote products derived from this software without\n   specif
ic prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDE
RS AND CONTRIBUTORS \"AS IS\" AND\nANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
 BUT NOT LIMITED TO, THE IMPLIED\nWARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY
, OR CONSEQUENTIAL\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBST
ITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTIO
N) HOWEVER\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT L
IABILITY,\nOR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
 THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n
"
    },
    {
        "name": "system-filepath",
        "author": "John Milikin",
        "license": "Copyright 2010 John Milikin\n\nPermission is hereby granted,
 free of charge, to any person obtaining a copy of this software and associated
documentation files (the \"Software\"), to deal in the Software without restrict
ion, including without limitation the rights to use, copy, modify, merge, publis
h, distribute, sublicense, and/or sell copies of the Software, and to permit per
sons to whom the Software is furnished to do so, subject to the following condit
ions:\n\nThe above copyright notice and this permission notice shall be included
 in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVI
DED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT N
OT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOS
E AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIA
BLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR T
HE USE OR OTHER DEALINGS IN THE SOFTWARE.\n"
    }
]

User: "How can I make the above configuration file easier to read and edit?"

The above configuration file is difficult to read because of the large license texts formatted as long uninterrupted lines. We can make the configuration more readable by converting the JSON configuration file to a Dhall configuration file, which supports multi-line string literals (like YAML):

-- example0.dhall

[ { name =
      "dhall"
  , author =
      "Gabriel Gonzalez"
  , license =
      ''
      Copyright 2017 Gabriel Gonzalez
      
      Redistribution and use in source and binary forms, with or without
      modification, are permitted provided that the following conditions are met:
      
      1. Redistributions of source code must retain the above copyright notice, this
         list of conditions and the following disclaimer.
      
      2. Redistributions in binary form must reproduce the above copyright notice,
         this list of conditions and the following disclaimer in the documentation
         and/or other materials provided with the distribution.
      
      3. Neither the name of the copyright holder nor the names of its contributors
         may be used to endorse or promote products derived from this software without
         specific prior written permission.
      
      THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
      ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
      WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
      FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
      DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
      CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
      OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
      OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
      ''
  }
, { name =
      "conduit"
  , author =
      "Michael Snoyman"
  , license =
      ''
      Copyright 2012 Michael Snoyman
      
      Permission is hereby granted, free of charge, to any person obtaining a copy of
      this software and associated documentation files (the "Software"), to deal in
      the Software without restriction, including without limitation the rights to
      use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
      of the Software, and to permit persons to whom the Software is furnished to do
      so, subject to the following conditions:
      
      The above copyright notice and this permission notice shall be included in all
      copies or substantial portions of the Software.
      
      THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
      IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
      FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
      AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
      LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
      OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
      SOFTWARE.
      ''
  }
, { name =
      "async"
  , author =
      "Simon Marlow"
  , license =
      ''
      Copyright 2012 Simon Marlow
      
      Redistribution and use in source and binary forms, with or without
      modification, are permitted provided that the following conditions are met:
      
      1. Redistributions of source code must retain the above copyright notice, this
         list of conditions and the following disclaimer.
      
      2. Redistributions in binary form must reproduce the above copyright notice,
         this list of conditions and the following disclaimer in the documentation
         and/or other materials provided with the distribution.
      
      3. Neither the name of the copyright holder nor the names of its contributors
         may be used to endorse or promote products derived from this software without
         specific prior written permission.
      
      THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
      ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
      WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
      FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
      DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
      CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
      OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
      OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
      ''
  }
, { name =
      "system-filepath"
  , author =
      "John Milikin"
  , license =
      ''
      Copyright 2010 John Milikin
      
      Permission is hereby granted, free of charge, to any person obtaining a copy of
      this software and associated documentation files (the "Software"), to deal in
      the Software without restriction, including without limitation the rights to
      use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
      of the Software, and to permit persons to whom the Software is furnished to do
      so, subject to the following conditions:
      
      The above copyright notice and this permission notice shall be included in all
      copies or substantial portions of the Software.
      
      THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
      IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
      FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
      AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
      LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
      OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
      SOFTWARE.
      ''
  }
]

... which we can always convert back to the original JSON configuration by running:

$ dhall-to-json --pretty <<< 'example0.dhall'
[
    {
        "name": "dhall",
        "author": "Gabriel Gonzalez",
        "license": "Copyright 2017 Gabriel Gonzalez\n\nRedistribution and us..."
    },
    {
        "name": "conduit",
        "author": "Michael Snoyman",
        "license": "Copyright 2012 Michael Snoyman\n\nPermission is hereby g..."
    },
    {
        "name": "async",
        "author": "Simon Marlow",
        "license": "Copyright 2012 Simon Marlow\n\nRedistribution and use in..."
    },
    {
        "name": "system-filepath",
        "author": "John Milikin",
        "license": "Copyright 2010 John Milikin\n\nPermission is hereby gran..."
    }
]

User: "I still can't tell at a glance which license is which"

We could add comments with the name of each license (since Dhall, unlike JSON, supports comments):

[ { name =
      "dhall"
  , author =
      "Gabriel Gonzalez"

    -- BSD 3-Clause
  , license =
      ''
      Copyright 2017 Gabriel Gonzalez

      Redistribution and use in source and binary forms, with or without
      ...
      OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
      ''
  }
, { name =
      "conduit"
  , author =
      "Michael Snoyman"

    -- MIT
  , license =
      ''
      Copyright 2012 Michael Snoyman

      Permission is hereby granted, free of charge, to any person obtaining a copy of
      ...
      SOFTWARE.
      ''
  }
, { name =
      "async"
  , author =
      "Simon Marlow"

    -- BSD 3-Clause
  , license =
      ''
      Copyright 2012 Simon Marlow

      Redistribution and use in source and binary forms, with or without
      ...
      OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
      ''
  }
, { name =
      "system-filepath"
  , author =
      "John Milikin"

    -- MIT
  , license =
      ''
      Copyright 2010 John Milikin

      Permission is hereby granted, free of charge, to any person obtaining a copy of
      ...
      SOFTWARE.
      ''
  }
]

... or we could define named functions to build each type of license, like this:

-- example1.dhall

let BSD-3-Clause =
          \(args : { year : Natural, author : Text })
      ->  ''
          Copyright ${Natural/show args.year} ${args.author}
          
          Redistribution and use in source and binary forms, with or without
          modification, are permitted provided that the following conditions are met:
          
          1. Redistributions of source code must retain the above copyright notice, this
             list of conditions and the following disclaimer.
          
          2. Redistributions in binary form must reproduce the above copyright notice,
             this list of conditions and the following disclaimer in the documentation
             and/or other materials provided with the distribution.
          
          3. Neither the name of the copyright holder nor the names of its contributors
             may be used to endorse or promote products derived from this software without
             specific prior written permission.
          
          THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
          ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
          WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
          DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
          FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
          DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
          SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
          CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
          OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
          OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
          ''

let MIT =
          \(args : { year : Natural, author : Text })
      ->  ''
          Copyright ${Natural/show args.year} ${args.author}
          
          Permission is hereby granted, free of charge, to any person obtaining a copy of
          this software and associated documentation files (the "Software"), to deal in
          the Software without restriction, including without limitation the rights to
          use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
          of the Software, and to permit persons to whom the Software is furnished to do
          so, subject to the following conditions:
          
          The above copyright notice and this permission notice shall be included in all
          copies or substantial portions of the Software.
          
          THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
          IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
          FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
          AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
          LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
          OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
          SOFTWARE.
          ''

in  [ { name =
          "dhall"
      , author =
          "Gabriel Gonzalez"
      , license =
          BSD-3-Clause { year = 2017, author = "Gabriel Gonzalez" }
      }
    , { name =
          "conduit"
      , author =
          "Michael Snoyman"
      , license =
          MIT { year = 2012, author = "Michael Snoyman" }
      }
    , { name =
          "async"
      , author =
          "Simon Marlow"
      , license =
          BSD-3-Clause { year = 2012, author = "Simon Marlow" }
      }
    , { name =
          "system-filepath"
      , author =
          "John Milikin"
      , license =
          MIT { year = 2010, author = "John Milikin" }
      }
    ]

Now we can easily tell at a glance which license each package uses without the use of comments

Dhall supports anonymous functions using the following syntax:

\(inputName : inputType) -> output

... or using Unicode syntax:

λ(inputName : inputType)  output

For example:

  The name of the function input is "args", short for "arguments"
  ↓
\(args : { year : Natural, author : Text }) -> ...
         ↑
         "args" is a record with two fields named "year" and "author"

User: "The license text is still too distracting. Could we move it out of this configuration into another file?"

We can move anything in Dhall (values, functions, types) into separate files and they can refer to each other by their relative or absolute paths. For example, we can factor out the MIT and BSD-3-Clause functions out into separate files, like this:

-- BSD-3-Clause.dhall

    \(args : { year : Natural, author : Text })
->  ''
    Copyright ${Natural/show args.year} ${args.author}
    
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
    
    1. Redistributions of source code must retain the above copyright notice, this
       list of conditions and the following disclaimer.
    
    2. Redistributions in binary form must reproduce the above copyright notice,
       this list of conditions and the following disclaimer in the documentation
       and/or other materials provided with the distribution.
    
    3. Neither the name of the copyright holder nor the names of its contributors
       may be used to endorse or promote products derived from this software without
       specific prior written permission.
    
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    ''
-- MIT.dhall

    \(args : { year : Natural, author : Text })
->  ''
    Copyright ${Natural/show args.year} ${args.author}
    
    Permission is hereby granted, free of charge, to any person obtaining a copy of
    this software and associated documentation files (the "Software"), to deal in
    the Software without restriction, including without limitation the rights to
    use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
    of the Software, and to permit persons to whom the Software is furnished to do
    so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
    ''

... and then refer to these files within our original configuration:

-- example2.dhall

[ { name =
      "dhall"
  , author =
      "Gabriel Gonzalez"
  , license =
      ./BSD-3-Clause.dhall { year = 2017, author = "Gabriel Gonzalez" }
  }
, { name =
      "conduit"
  , author =
      "Michael Snoyman"
  , license =
      ./MIT.dhall { year = 2012, author = "Michael Snoyman" }
  }
, { name =
      "async"
  , author =
      "Simon Marlow"
  , license =
      ./BSD-3-Clause.dhall { year = 2012, author = "Simon Marlow" }
  }
, { name =
      "system-filepath"
  , author =
      "John Milikin"
  , license =
      ./MIT.dhall { year = 2010, author = "John Milikin" }
  }
]

Files containing Dhall expressions don't have to end with a .dhall file extension. This is purely a convention


User: "There's still some duplication: there is an unspoken invariant that the package author has to match the license author"

We can automate that away, too:

-- example3.dhall

let makePackage =
          \ ( args
            : { name :
                  Text
              , author :
                  Text
              , year :
                  Natural
              , makeLicense :
                  { year : Natural, author : Text } -> Text
              }
            )
      ->  { name =
              args.name
          , author =
              args.author
          , license =
              args.makeLicense { year = args.year, author = args.author }
          }

in  [ makePackage
      { name =
          "dhall"
      , author =
          "Gabriel Gonzalez"
      , year =
          2017
      , makeLicense =
          ./BSD-3-Clause.dhall
      }
    , makePackage
      { name =
          "conduit"
      , author =
          "Michael Snoyman"
      , year =
          2012
      , makeLicense =
          ./MIT.dhall
      }
    , makePackage
      { name =
          "async"
      , author =
          "Simon Marlow"
      , year =
          2012
      , makeLicense =
          ./BSD-3-Clause.dhall
      }
    , makePackage
      { name =
          "system-filepath"
      , author =
          "John Milikin"
      , year =
          2010
      , makeLicense =
          ./MIT.dhall
      }
    ]

User: "Still too much duplication. I plan on adding a lot more entries and I don't want to type makePackage for every entry in the list"

Dhall provides a Prelude of utilities to automate common tasks. For example, the Prelude provides a map function that transforms every element of the list with the same function (such as makePackage):

-- example4.dhall

let map = https://prelude.dhall-lang.org/List/map

let makePackage =
          \ ( args
            : { name :
                  Text
              , author :
                  Text
              , year :
                  Natural
              , makeLicense :
                  { year : Natural, author : Text } -> Text
              }
            )
      ->  { name =
              args.name
          , author =
              args.author
          , license =
              args.makeLicense { year = args.year, author = args.author }
          }

in  map
    { name :
        Text
    , author :
        Text
    , year :
        Natural
    , makeLicense :
        { year : Natural, author : Text } -> Text
    }
    { name : Text, author : Text, license : Text }
    makePackage
    [ { name =
          "dhall"
      , author =
          "Gabriel Gonzalez"
      , year =
          2017
      , makeLicense =
          ./BSD-3-Clause.dhall
      }
    , { name =
          "conduit"
      , author =
          "Michael Snoyman"
      , year =
          2012
      , makeLicense =
          ./MIT.dhall
      }
    , { name =
          "async"
      , author =
          "Simon Marlow"
      , year =
          2012
      , makeLicense =
          ./BSD-3-Clause.dhall
      }
    , { name =
          "system-filepath"
      , author =
          "John Milikin"
      , year =
          2010
      , makeLicense =
          ./MIT.dhall
      }
    ]

You can import functions, values, and types from URLs the same way that you import them from paths and this is how Dhall distributes the Prelude

Every function from the Prelude has documentation, examples, and a type signature:

$ curl --location https://prelude.dhall-lang.org/List/map
{-
Transform a list by applying a function to each element

Examples:


./map Natural Bool Natural/even [ 2, 3, 5 ]
= [ True, False, False ]

./map Natural Bool Natural/even ([] : List Natural)
= [] : List Bool

-}
    let map
        : ∀(a : Type) → ∀(b : Type) → (a → b) → List a → List b
        =   λ(a : Type)
          → λ(b : Type)
          → λ(f : a → b)
          → λ(xs : List a)
          → List/build
            b
            (   λ(list : Type)
              → λ(cons : b → list → list)
              → List/fold a xs list (λ(x : a) → cons (f x))
            )

in  map

The type signature for map:

let map : (a : Type)  (b : Type)  (a  b)  List a  List b

... says that map takes four arguments:

  • The first argument is the element type of the input list
  • The second argument is the element type of the output list
  • The third argument is the function to apply to each element of the list
  • The fourth argument is the input list

... and the result is the output list

Note: The ASCII analog of is forall, so we could also have written the type of map as:

forall (a : Type) -> forall (b : Type) -> (a -> b) -> List a -> List b

You can browse the latest version of the Prelude online by visiting:

You can also import functions from the latest version of the Prelude using the same domain:

    let map = http://prelude.dhall-lang.org/List/map

in  ...

... although be cautious when doing so since this URL is mutable and you can't guarantee that you get the same result every time.


User: "These types are still long and repetitive. One type shows up twice in the source code"

You can use let expressions to define "type synonyms":

-- example5.dhall

let map = https://prelude.dhall-lang.org/List/map

let Input =
      { name :
          Text
      , author :
          Text
      , year :
          Natural
      , makeLicense :
          { year : Natural, author : Text } -> Text
      }

let Output = { name : Text, author : Text, license : Text }

let makePackage =
          \(args : Input)
      ->  { name =
              args.name
          , author =
              args.author
          , license =
              args.makeLicense { year = args.year, author = args.author }
          }

in  map
    Input
    Output
    makePackage
    [ { name =
          "dhall"
      , author =
          "Gabriel Gonzalez"
      , year =
          2017
      , makeLicense =
          ./BSD-3-Clause.dhall
      }
    , { name =
          "conduit"
      , author =
          "Michael Snoyman"
      , year =
          2012
      , makeLicense =
          ./MIT.dhall
      }
    , { name =
          "async"
      , author =
          "Simon Marlow"
      , year =
          2012
      , makeLicense =
          ./BSD-3-Clause.dhall
      }
    , { name =
          "system-filepath"
      , author =
          "John Milikin"
      , year =
          2010
      , makeLicense =
          ./MIT.dhall
      }
    ]

... or you can store the types in files:

-- Input.dhall
{ name :
    Text
, author :
    Text
, year :
    Natural
, makeLicense :
    { year : Natural, author : Text } -> Text
}
-- Output.dhall
{ name : Text, author : Text, license : Text }

... and import those types like any other Dhall expression:

-- example6.dhall

let map = https://prelude.dhall-lang.org/List/map

let makePackage =
          \(args : ./Input.dhall)
      ->  { name =
              args.name
          , author =
              args.author
          , license =
              args.makeLicense { year = args.year, author = args.author }
          }

in  map
    ./Input.dhall
    ./Output.dhall
    makePackage
    [ { name =
          "dhall"
      , author =
          "Gabriel Gonzalez"
      , year =
          2017
      , makeLicense =
          ./BSD-3-Clause.dhall
      }
    , { name =
          "conduit"
      , author =
          "Michael Snoyman"
      , year =
          2012
      , makeLicense =
          ./MIT.dhall
      }
    , { name =
          "async"
      , author =
          "Simon Marlow"
      , year =
          2012
      , makeLicense =
          ./BSD-3-Clause.dhall
      }
    , { name =
          "system-filepath"
      , author =
          "John Milikin"
      , year =
          2010
      , makeLicense =
          ./MIT.dhall
      }
    ]

... whichever you prefer.


User: "Why doesn't Dhall use JSON-like syntax?"

JSON isn't the only file format that Dhall supports. For example, we can convert our Dhall configuration to YAML:

$ dhall-to-yaml <<< './example6.dhall' 
- name: dhall
  author: Gabriel Gonzalez
  license: |
    Copyright 2017 Gabriel Gonzalez

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:

    1. Redistributions of source code must retain the above copyright notice, this
       list of conditions and the following disclaimer.

    2. Redistributions in binary form must reproduce the above copyright notice,
       this list of conditions and the following disclaimer in the documentation
       and/or other materials provided with the distribution.

    3. Neither the name of the copyright holder nor the names of its contributors
       may be used to endorse or promote products derived from this software without
       specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- name: conduit
  author: Michael Snoyman
  license: |
    Copyright 2012 Michael Snoyman

    Permission is hereby granted, free of charge, to any person obtaining a copy of
    …
    SOFTWARE.
- name: async
  author: Simon Marlow
  license: |
    Copyright 2012 Simon Marlow

    Redistribution and use in source and binary forms, with or without
    …
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- name: system-filepath
  author: John Milikin
  license: |
    Copyright 2010 John Milikin

    Permission is hereby granted, free of charge, to any person obtaining a copy of
    …
    SOFTWARE.

... or read our Dhall configuration directly into some programming languages (like Haskell) without going through a JSON intermediate:

{-# LANGUAGE DeriveAnyClass    #-}
{-# LANGUAGE DeriveGeneric     #-}
{-# LANGUAGE OverloadedStrings #-}

import Dhall

data Package = Package
    { name    :: Text
    , author  :: Text
    , license :: Text
    } deriving (Generic, Interpret, Show)

main :: IO ()
main = do
    packages <- input auto "./example.dhall"
    print (packages :: Vector Package)

User: "Why not just always go through a JSON intermediate? Every language already supports JSON"

You can load more exotic things into the language (like functions) if the language integrates directly with Dhall:

{-# LANGUAGE OverloadedStrings #-}

import Dhall

main :: IO ()
main = do
    twice <- input auto "\\(x : Integer) -> [x, x]" :: IO (Integer -> Vector Integer)
    print (twice 5) -- prints: "[5,5]"

... and other features, too, like unions


User: "What's a union?"

At this point if you are still curious you should read the longer JSON tutorial

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.