Add the `--preserveNull` flag and omit null fields by default on `dhall-to-yaml` (#1365)

* Add the `--preserveNull` flag and omit null fields by default on `dhall-to-yaml`

fixes #1354

* Restore the `--omitNull` flag and apply `--preserveNull` to `dhall-to-json`

* Adjust examples that return null fields

* Mention the default behaviour regarding nulls

* Null -> null

dhall-json/dhall-to-json/Main.hs

@@ -41,7 +41,7 @@ parseOptions =
         (   Options
         <$> parseExplain
         <*> parsePretty
-        <*> Dhall.JSON.parseOmission
+        <*> Dhall.JSON.parsePreservationAndOmission
         <*> Dhall.JSON.parseConversion
         <*> parseApproximateSpecialDoubles
         <*> optional parseFile

dhall-json/dhall-to-yaml/Main.hs

@@ -5,7 +5,7 @@ module Main where
 import Control.Applicative (optional, (<|>))
 import Control.Exception (SomeException)
 import Data.Monoid ((<>))
-import Dhall.JSON (parseOmission, parseConversion)
+import Dhall.JSON (parsePreservationAndOmission, parseConversion)
 import Dhall.Yaml (Options(..), dhallToYaml, parseDocuments, parseQuoted)
 import Options.Applicative (Parser, ParserInfo)
 
@@ -24,7 +24,7 @@ parseOptions =
             Just
         <$> (   Options
             <$> parseExplain
-            <*> Dhall.JSON.parseOmission
+            <*> Dhall.JSON.parsePreservationAndOmission
             <*> parseDocuments
             <*> parseQuoted
             <*> Dhall.JSON.parseConversion

dhall-json/src/Dhall/JSON.hs

@@ -175,7 +175,10 @@
 >       }
 >     ]
 
-> $ dhall-to-json <<< './example.dhall'
+    By default, the fields that are evaluated to @null@ will be removed,
+    but here we're preserving them with the @--preserveNull@ flag.
+
+> $ dhall-to-json --preserveNull <<< './example.dhall'
 > {
 >   "bar": [
 >     1,
@@ -197,6 +200,7 @@ module Dhall.JSON (
     , omitNull
     , omitEmpty
     , parseOmission
+    , parsePreservationAndOmission
     , Conversion(..)
     , convertToHomogeneousMaps
     , parseConversion
@@ -630,6 +634,20 @@ parseOmission =
             )
     <|> pure id
 
+-- | Parser for command-line options related to preserving null fields.
+parseNullPreservation :: Parser (Value -> Value)
+parseNullPreservation =
+        Options.Applicative.flag
+            omitNull
+            id
+            (   Options.Applicative.long "preserveNull"
+            <>  Options.Applicative.help "Preserve record fields that are null"
+            )
+
+-- | Combines parsers for command-line options related to preserving & omitting null fields.
+parsePreservationAndOmission :: Parser (Value -> Value)
+parsePreservationAndOmission = parseNullPreservation <|> parseOmission <|> pure id
+
 {-| Specify whether or not to convert association lists of type
     @List { mapKey: Text, mapValue : v }@ to records
 -}