From d03a900583a8482293f56bb32fc20066edc4ee24 Mon Sep 17 00:00:00 2001 From: Gabriel Gonzalez Date: Fri, 9 Sep 2016 19:02:13 -0700 Subject: [PATCH] Update documentation --- src/Dhall.hs | 71 ++++++++++++++++++++++++++++------------------------ 1 file changed, 38 insertions(+), 33 deletions(-) diff --git a/src/Dhall.hs b/src/Dhall.hs index 2119a59..6fdb466 100644 --- a/src/Dhall.hs +++ b/src/Dhall.hs @@ -17,9 +17,10 @@ -- > { foo = 1 -- > , bar = [ 3.0, 4.0, 5.0 : Double ] -- > } --- > +-- > -- --- You can read in the entire file using the following Haskell code: +-- You can read the above configuration file into Haskell using the following +-- code: -- -- > {-# LANGUAGE DeriveGeneric #-} -- > {-# LANGUAGE OverloadedStrings #-} @@ -41,9 +42,9 @@ -- > $ ./example -- > Example {foo = 1, bar = [3.0,4.0,5.0]} -- --- In the above example, the `Example` Haskell type represents the schema for --- our configuration file. Suppose that we modify our configuration file to --- no longer match the schema, like this: +-- In the above code, the `Example` Haskell type represents the schema for our +-- configuration file. Suppose that we modify our configuration file to no +-- longer match the schema, like this: -- -- > $ echo "1" > example.dhall -- @@ -64,9 +65,9 @@ -- two fields: a field named @bar@ that is a `Vector` of `Double`s, and a -- field named @foo@ that is an `Integer`. This is the \"Annotated type\". -- However, the type-checker found an expression whose inferred type was an --- `Integer`. Since an `Integer` is not the same thing as a record the --- type-checking step fails and Dhall does not bother to marshal the --- configuration into Haskell. +-- `Integer`. This is the \"Expected type\". Since an `Integer` is not the +-- same thing as a record the type-checking step fails and Dhall does not bother +-- to marshal the configuration into Haskell. -- -- Dhall is also a heavily restricted programming language. For example, we can -- define a configuration file that is an anonymous function: @@ -110,7 +111,8 @@ -- -- Notice how we can decode into some types \"out-of-the-box\" without declaring -- a Haskell record to store the output. In the above example we marshalled --- the result directly into a `Vector` of `Bool`s. +-- the result directly into a `Vector` of `Bool`s. The instances for the +-- `Interpret` class list all types that are automatically supported. -- -- We can also test functions directly on the command line using the @dhall@ -- compiler. For example: @@ -130,8 +132,8 @@ -- In the above example the type of the result is a `Vector` of `Bool`s and the -- normal form of the expression just evaluates all functions. -- --- You can use the Dhall compiler as a (very basic) expression evaluator. For --- example: +-- You can also use the Dhall compiler to evaluate expressions which have no +-- file references. For example: -- -- > $ dhall -- > "Hello, " ++ "world!" @@ -146,12 +148,12 @@ -- > -- > +100 -- --- Dhall is a very restricted programming language that only supports very --- simple operations. For example, Dhall only support addition and subtraction --- on `Natural` numbers (i.e. non-negative numbers), which are not the same type --- of number as `Integer`s (which can be negative). A `Natural` number is a --- number prefixed with the @+@ symbol. If you try to add or multiply two --- `Integer`s (without the @+@ prefix) you will get a type error: +-- Dhall is a very restricted programming language that only supports simple +-- operations. For example, Dhall only support addition and subtraction on +-- `Natural` numbers (i.e. non-negative numbers), which are not the same type of +-- number as `Integer`s (which can be negative). A `Natural` number is a number +-- prefixed with the @+@ symbol. If you try to add or multiply two `Integer`s +-- (without the @+@ prefix) you will get a type error: -- -- > $ dhall -- > 2 + 2 @@ -184,15 +186,14 @@ -- We get a type error saying that our function expects a `Bool` argument, but -- we supplied an argument of type `Text` instead. -- --- We also don't have to use files at all. Our `input` function accepts any --- Dhall expression: +-- Our `input` function also doesn't need to reference any files at all: -- -- >>> input auto "True && False" :: IO Bool -- False -- -- Reading from an external configuration file is just a special case of Dhall's -- support for embedding files as expressions. There's no limit to how many --- files as expressions that you can nest this way. For example, we can define +-- files-as-expressions that you can nest this way. For example, we can define -- one file that is a Dhall expression that in turn depends on another file -- which is also a Dhall expression: -- @@ -218,15 +219,15 @@ -- > Cyclic import: ./bar -- -- Dhall is a total programming language, which means that Dhall is not --- Turing-complete. Evaluation of every Dhall program is guaranteed to --- eventually halt There is no upper bound on how long the program might take +-- Turing-complete and evaluation of every Dhall program is guaranteed to +-- eventually halt. There is no upper bound on how long the program might take -- to evaluate, but the program is guaranteed to terminate in a finite amount of -- time and not hang forever. -- --- This guarantee means that all Dhall programs can be safely reduced to --- normal form. In fact, Dhall programs can be evaluated even if all function --- arguments haven't been fully applied. For example, the following program is --- an anonymous function: +-- This guarantees that all Dhall programs can be safely reduced to a normal +-- form where all functions have been evaluated. In fact, Dhall expressions can +-- be evaluated even if all function arguments haven't been fully applied. For +-- example, the following program is an anonymous function: -- -- > $ dhall -- > \(n : Bool) -> +10 * +10 @@ -289,16 +290,16 @@ throws (Right r) = return r The first argument determines the type of value that you decode: -> input integer "2" :: IO Integer -> input (vector double) "[ 1.0, 2.0 : Double ]" : IO (Vector Double) +>>> input integer "2" +2 +>>> input (vector double) "[ 1.0, 2.0 : Double ]" +[1.0,2.0] Use `auto` to automatically select which type to decode based on the inferred return type: -> example :: IO () -> example = do -> x <- input auto "True" -> putStrLn (if x then "Hello!" else "Goodbye!") +>>> input auto "True" :: IO Bool +True -} input :: Type a @@ -315,7 +316,7 @@ input (Type {..}) t = do Just x -> return x Nothing -> fail "input: malformed `Type`" -{-| A @(Type a)@ represents a way to marshal a value of type @a@ from Dhall +{-| A @(Type a)@ represents a way to marshal a value of type @\'a\'@ from Dhall into Haskell You can produce `Type`s either explicitly: @@ -474,6 +475,10 @@ pair3 >>> input auto "[1, 2, 3 : Integer]" :: IO (Vector Integer) [1,2,3] + + This class auto-generates a default implementation for records that + implement `Generic`. This does auto-generate an instance for sum types or + recursive types. -} class Interpret a where auto :: Type a