:: a typeCtrl KGHC 9.10.3 · lts/ghc-9.10.x · 248f8f0 · 2026-10-05
Moduledhall-1.42.3Haskell2010
Newtypes for writing customizable FromDhall and ToDhall instances through the DerivingVia strategy.
Inspired by Matt Parson's blog post Mirror Mirror: Reflection and Encoding Via, but applied to Dhall instead of JSON.
This module is intended to be used with DerivingVia so it's only available for GHC >= v8.6.1.
Check the section Letting DerivingVia do the work if you want to see this module in action. (Click Dhall.Deriving#derivingVia to jump there)
Let's take the following Haskell data types:
:set -XDerivingStrategies:{newtype Name = Name { getName :: Text } deriving stock (Show):}
:{data Font = Arial | ComicSans | Helvetica | TimesNewRoman deriving stock (Show):}
:{data Person = Person { personName :: Name , personFavoriteFont :: Font } deriving stock (Show):}
And assume we want to read the following Dhall file as a Person:
-- ./simon.dhall
let Name = Text
let Font = < Arial | `Comic Sans` | Helvetica | `Times New Roman` >
let Person = { name : Name, favoriteFont : Font }
in { name = "Simon", favoriteFont = Font.`Comic Sans` } : Person
Usually, you would build a Decoder by hand, like this
:{font :: Decoder Fontfont = union ( (Arial <$ constructor "Arial" unit) <> (ComicSans <$ constructor "Comic Sans" unit) <> (Helvetica <$ constructor "Helvetica" unit) <> (TimesNewRoman <$ constructor "Times New Roman" unit) ):}
:{name :: Decoder Namename = Name <$> strictText:}
:{person :: Decoder Personperson = record ( Person <$> field "name" name <*> field "favoriteFont" font ):}
and then you use it like this
input person "./simon.dhall"Person {personName = Name {getName = "Simon"}, personFavoriteFont = ComicSans}
So, it works! However, this is quite mechanic, and the compiler has pretty
much all the information it needs to do it for you. Besides, you'd like to
provide an instance of FromDhall so you can use the polymorphic Decoder
auto instead of explicitly calling person.
"Aha!," you think, "I'll write an empty instance FromDhall Person".
That in turn requires you to add two other instances for Font and for Name,
plus Generic instances for each of those, but that's okay.
:set -XStandaloneDeriving:set -XDeriveGeneric
:{deriving stock instance Generic Namederiving stock instance Generic Fontderiving stock instance Generic Person:}
:{instance FromDhall Nameinstance FromDhall Fontinstance FromDhall Person:}
However, when you try to read the same file with auto, you get this:
input auto "./simon.dhall" :: IO Person*** Exception:...Error...: Expression doesn't match annotation...{ - personFavoriteFont : …, - personName : …, + favoriteFont : …, + name : …}...1│ ./simon.dhall : { personName : { getName : Text }2│ , personFavoriteFont : < Arial | ComicSans | Helvetica | TimesNewRoman >3│ }...
What happened? The field names don't quite match, since we're using prefixed
field names in Haskell but no prefixes in Dhall. "Okay," you think,
"I can write a custom instance which builds on Generic thanks to
genericAutoWith, I only need to supply a function to drop the prefixes
and camelCase the rest". So, using toCamel:
import Data.Text.Manipulate (toCamel)import qualified Data.Text as Text:{instance FromDhall Person where autoWith _ = genericAutoWith defaultInterpretOptions { fieldModifier = toCamel . Text.drop (Text.length "person") }:}
Let's try to read that again:
input auto "./simon.dhall":: IO Person*** Exception:...Error...: Expression doesn't match annotation...{ favoriteFont : < - ComicSans : … | - TimesNewRoman : … | + `Comic Sans` : … | + `Times New Roman` : … | … >, name : - { … : … } (a record type) + Text}...1│ ./simon.dhall : { name : { getName : Text }2│ , favoriteFont : < Arial | ComicSans | Helvetica | TimesNewRoman >3│ }...
Okay, we're almost there. We have two things to solve now.
First, the Font constructors are PascalCased in Haskell,
but Title Cased in Dhall. We can communicate this to our
FromDhall instance using toTitle:
import Data.Text.Manipulate (toTitle):{instance FromDhall Font where autoWith _ = genericAutoWith defaultInterpretOptions { constructorModifier = toTitle }:}
Second, we defined the Name type in Haskell as a newtype over Text, with a
getName field for unwrapping. In Dhall, however, Name is a synonym of
Text, which is why input above was expecting a record.
The Bare option for singletonConstructors is a perfect fit here:
it translates Haskell singleton constructors into the Dhall version of the
nested type, without wrapping it into a record.
We can then tweak our FromDhall instance like this:
:{instance FromDhall Name where autoWith _ = genericAutoWith defaultInterpretOptions { singletonConstructors = Bare }:}
Since we're running this interactively, we also need to update the
instance for Person, but it's the same as before.
:{instance FromDhall Person where autoWith _ = genericAutoWith defaultInterpretOptions { fieldModifier = toCamel . Text.drop (Text.length "person") }:}
Now, for the moment of truth:
input auto "./simon.dhall":: IO PersonPerson {personName = Name {getName = "Simon"}, personFavoriteFont = ComicSans}
That took a bit more work than we wanted, though, and a lot of it was just boilerplate for defining the instances through genericAutoWith, tweaking a single parameter at a time. Even worse, if we also wanted to provide ToDhall instances we would need to keep the options in sync between both instances, since otherwise the values wouldn't be able to round-trip from Dhall to Dhall through Haskell.
Starting with this dhall file:
-- ./simon.dhall
let Name = Text
let Font = < Arial | `Comic Sans` | Helvetica | `Times New Roman` >
let Person = { name : Name, favoriteFont : Font }
in { name = "Simon", favoriteFont = Font.`Comic Sans` } : Person
We can define the equivalent Haskell types as follows. Note that we
derive the FromDhall and ToDhall instances via Codec tag TheType,
using a different tag depending on the transformations we need to apply to
the Haskell type to get the Dhall equivalent:
:set -XDataKinds:set -XDeriveGeneric:set -XDerivingVia:set -XTypeOperators
:{newtype Name = Name { getName :: Text } deriving stock (Generic, Show) deriving (FromDhall, ToDhall) via Codec (SetSingletonConstructors Bare) Name:}
:{data Font = Arial | ComicSans | Helvetica | TimesNewRoman deriving stock (Generic, Show) deriving (FromDhall, ToDhall) via Codec (Constructor TitleCase) Font:}
:{data Person = Person { personName :: Name , personFavoriteFont :: Font } deriving stock (Generic, Show) deriving (FromDhall, ToDhall) via Codec (Field (CamelCase <<< DropPrefix "person")) Person:}
we can then read the file using auto:
simon <- input auto "./simon.dhall":: IO Personprint simonPerson {personName = Name {getName = "Simon"}, personFavoriteFont = ComicSans}
And using inject we can get simon back as a Dhall value:
import qualified Data.Text.IO as Textimport Dhall.Core (pretty)Text.putStrLn . pretty . embed inject $ simon{ name = "Simon", favoriteFont = < Arial | `Comic Sans` | Helvetica | `Times New Roman` >.`Comic Sans`}
Codec tag a is really just a newtype over a, equipped with a
phantom tag. The FromDhall instance for Codec uses the generic
representation of a, together with the InterpretOptions defined by tag as
a series of modifications to be applied on defaultInterpretOptions.
For the default behavior, using AsIs (a synonym for ()) as the tag
leaves the interpret options alone, so it's equivalent to the empty instance
we first tried to use.
Field a and Constructor a can be used to modify, respectively, the
fieldModifier and constructorModifier options of InterpretOptions, by
post-composing the modifier with textFunction @a, that is, the value-level
equivalent of a, obtained through the TextFunction class.
In the case of Person, we used
Codec (Field (CamelCase <<< DropPrefix "person")) Person
which means that the Text -> Text version of
CamelCase <<< DropPrefix "person"
was used to modify the fieldModifier option.
In the value level, this translates to composing (<<<)
toCamel (CamelCase) with dropPrefix "person"
(DropPrefix "person").
Finally, SetSingletonConstructors a can be used to set the
singletonConstructors option of InterpretOptions, by replacing the option
with the value-level equivalent of a.
Intended for use on deriving via clauses for types with a
Generic instance. The tag argument is used to construct an
InterpretOptions value which is used as the first argument
to genericAutoWith.
(Generic a, GenericFromDhall a (Rep a), ModifyOptions tag) => FromDhall (Codec tag a)Defined in dhall-1.42.3 · Dhall.Deriving(Generic a, GenericToDhall (Rep a), ModifyOptions tag) => ToDhall (Codec tag a)Defined in dhall-1.42.3 · Dhall.DerivingConvert a type into a InterpretOptions -> InterpretOptions function
ModifyOptions AsIsDefined in dhall-1.42.3 · Dhall.DerivingTextFunction a => ModifyOptions (Constructor a)Defined in dhall-1.42.3 · Dhall.DerivingTextFunction a => ModifyOptions (Field a)Defined in dhall-1.42.3 · Dhall.DerivingToSingletonConstructors a => ModifyOptions (SetSingletonConstructors a)Defined in dhall-1.42.3 · Dhall.Deriving(ModifyOptions a, ModifyOptions b) => ModifyOptions (a <<< b)Defined in dhall-1.42.3 · Dhall.DerivingField t post-composes the fieldModifier from options with the
value-level version of t, obtained with TextFunction
TextFunction a => ModifyOptions (Field a)Defined in dhall-1.42.3 · Dhall.DerivingConstructor t post-composes the constructorModifier from options
with the value-level version of t, obtained with TextFunction
TextFunction a => ModifyOptions (Constructor a)Defined in dhall-1.42.3 · Dhall.DerivingSetSingletonConstructors t replaces the singletonConstructors
from options with the value-level version of t.
ToSingletonConstructors a => ModifyOptions (SetSingletonConstructors a)Defined in dhall-1.42.3 · Dhall.DerivingConvert a type into a Text -> Text function
textFunction :: Text -> TextTextFunction AsIsDefined in dhall-1.42.3 · Dhall.DerivingTextFunction CamelCaseDefined in dhall-1.42.3 · Dhall.DerivingTextFunction PascalCaseDefined in dhall-1.42.3 · Dhall.DerivingTextFunction SnakeCaseDefined in dhall-1.42.3 · Dhall.DerivingTextFunction SpinalCaseDefined in dhall-1.42.3 · Dhall.DerivingTextFunction TitleCaseDefined in dhall-1.42.3 · Dhall.DerivingTextFunction TrainCaseDefined in dhall-1.42.3 · Dhall.DerivingKnownSymbol s => TextFunction (DropPrefix s)Defined in dhall-1.42.3 · Dhall.Deriving(TextFunction a, TextFunction b) => TextFunction (a <<< b)Defined in dhall-1.42.3 · Dhall.DerivingDropPrefix prefix corresponds to the value level
function dropPrefix prefix
KnownSymbol s => TextFunction (DropPrefix s)Defined in dhall-1.42.3 · Dhall.DerivingConvert casing to Title Cased Phrase
TextFunction TitleCaseDefined in dhall-1.42.3 · Dhall.DerivingConvert casing to camelCasedPhrase
TextFunction CamelCaseDefined in dhall-1.42.3 · Dhall.DerivingConvert casing to PascalCasedPhrase
TextFunction PascalCaseDefined in dhall-1.42.3 · Dhall.DerivingConvert casing to snake_cased_phrase
TextFunction SnakeCaseDefined in dhall-1.42.3 · Dhall.DerivingConvert casing to spinal-cased-phrase
TextFunction SpinalCaseDefined in dhall-1.42.3 · Dhall.DerivingConvert casing to Train-Cased-Phrase
TextFunction TrainCaseDefined in dhall-1.42.3 · Dhall.DerivingConvert a type of kind SingletonConstructors
into a value of type SingletonConstructors
ToSingletonConstructors BareDefined in dhall-1.42.3 · Dhall.DerivingToSingletonConstructors SmartDefined in dhall-1.42.3 · Dhall.DerivingToSingletonConstructors WrappedDefined in dhall-1.42.3 · Dhall.DerivingType-level version of Bare. Never wrap the field of a singleton constructor in a record
Type-level version of Wrapped Always wrap the field of a singleton constructor in a record
Type-level version of Smart Wrap the field of a singleton constructor in a record only if the field is named
The identity for functions on InterpretOptions and on Text.
Useful for deriving FromDhall and ToDhall with the default options.
Composition for functions on InterpretOptions and on Text.
We use <<< since . isn't a valid type operator yet
(it will be valid starting from ghc-8.8.1)
(ModifyOptions a, ModifyOptions b) => ModifyOptions (a <<< b)Defined in dhall-1.42.3 · Dhall.Deriving(TextFunction a, TextFunction b) => TextFunction (a <<< b)Defined in dhall-1.42.3 · Dhall.DerivingdropPrefix prefix text returns the suffix of text if its prefix
matches prefix, or the entire text otherwise
addFieldModifier f options post-composes the fieldModifier
from options with f.
addConstructorModifier f options post-composes the constructorModifier
from options with f.
setSingletonConstructors v options replaces the singletonConstructors
from options with v.