Improved to-directory-tree

.gitignore

@@ -28,3 +28,4 @@ docs
 result
 result-*
 report.html
+/dhall/tests/to-directory-tree/*.out/

dhall/dhall.cabal

@@ -250,6 +250,7 @@ Common common
         th-lift-instances           >= 0.1.13   && < 0.2 ,
         time                        >= 1.1.4    && < 1.13,
         transformers                >= 0.5.2.0  && < 0.6 ,
+        unix-compat                 >= 0.4.2    && < 0.7 ,
         unordered-containers        >= 0.1.3.0  && < 0.3 ,
         uri-encode                                 < 1.6 ,
         vector                      >= 0.11.0.0 && < 0.14
@@ -411,6 +412,7 @@ Test-Suite tasty
     Other-Modules:
         Dhall.Test.Dhall
         Dhall.Test.Diff
+        Dhall.Test.DirectoryTree
         Dhall.Test.Tags
         Dhall.Test.Format
         Dhall.Test.Freeze

dhall/examples/to-directory-tree.dhall

@@ -0,0 +1,119 @@
+-- This is an example on how to build a directory tree using the so-called
+-- fixpointed method. See the documenatation of the `Dhall.DirectoryTree` module
+-- for further information on it.
+
+-- First, define some types recognized by the `dhall to-directory-tree` command.
+
+-- A user, either identified by its numeric user id or its name.
+let User = < UserId : Natural | UserName : Text >
+
+-- Similarly, a group.
+let Group = < GroupId : Natural | GroupName : Text >
+
+-- The following two type aliases are a well-typed represenation of the bitmask
+-- for permissions used by the DAC access control found on Unix systems. See for
+-- example the chmod(5) manual entry.
+
+-- How much access we do grant...
+let Access =
+      { execute : Optional Bool, read : Optional Bool, write : Optional Bool }
+
+-- ... for whom.
+let Mode =
+      { user : Optional Access
+      , group : Optional Access
+      , other : Optional Access
+      }
+
+-- A generic file system entry. It consists of a name, an abstract content and
+-- some metadata which might be set (Some) or not (None).
+let Entry =
+      \(content : Type) ->
+        { name : Text
+        , content : content
+        , user : Optional User
+        , group : Optional Group
+        , mode : Optional Mode
+        }
+
+-- This is the main program constructing our directory tree. It is a fixpoint
+-- definition similar to how we deal with recursive types in arbitrary Dhall
+-- programs but specialised to our use case. The first argument is the type of a
+-- directory tree and the second one is a record where each field is a
+-- constructor for a specific filesystem entry.
+in  \(tree : Type) ->
+    \ ( make
+      : { directory : Entry (List tree) -> tree, file : Entry Text -> tree }
+      ) ->
+
+      -- Before we define the actual directory tree we define some Dhall schemas
+      -- and shortcuts for convenience.
+
+      -- A schema suitable for a directory...
+      let Directory =
+            { Type =
+                { name : Text
+                , content : List tree
+                , user : Optional User
+                , group : Optional Group
+                , mode : Optional Mode
+                }
+            , default =
+              { content = [] : List tree
+              , user = None User
+              , group = None Group
+              , mode = None Mode
+              }
+            }
+
+      -- ... and one for a file.
+      let File =
+            { Type =
+                { name : Text
+                , content : Text
+                , user : Optional User
+                , group : Optional Group
+                , mode : Optional Mode
+                }
+            , default =
+              { content = ""
+              , user = None User
+              , group = None Group
+              , mode = None Mode
+              }
+            }
+
+      -- Give someone full access to an filesystem entry.
+      let full_access
+          : Access
+          = { execute = Some True, read = Some True, write = Some True }
+
+      -- Give someone no access at all to an filesystem entry.
+      let no_access
+          : Access
+          = { execute = Some False, read = Some False, write = Some False }
+
+      -- These permissions
+      --  * grant full access to the user.
+      --  * retain the permissions of the primary group of the user.
+      --  * deny access to everyone else.
+      let semi_private
+          : Mode
+          = { user = Some full_access, group = None Access, other = Some no_access }
+
+      -- Now let's start with the directory tree ...
+      in    [ -- Some file with a gentle greeting. No metadata is set explicitly.
+              make.file File::{ name = "some file", content = "Hello world!" }
+              -- A directory with some metadata set explicitely.
+            , make.directory
+                Directory::{
+                , name = "my private directory"
+                  -- How owns the new directory: just_me
+                , user = Some (User.UserName "just_me")
+                  -- We stick with the user's default group here.
+                , group = None Group
+                , mode = Some semi_private
+                , content = [] : List tree
+                }
+            ]
+          : List tree