Encode package:dhall

Please read the Dhall.Tutorial module, which contains a tutorial explaining how to use the language, the compiler, and this library

An (Encoder a) represents a way to marshal a value of type 'a' from Haskell into Dhall.

Encode a Dhall expression as a CBOR-encoded ByteString

Specify how to encode an alternative by using the default ToDhall instance for that type.

Specify how to encode an alternative by providing an explicit Encoder for that alternative.

Specify how to encode one field of a record using the default ToDhall instance for that type.

Specify how to encode one field of a record by supplying an explicit Encoder for that field.

The RecordEncoder divisible (contravariant) functor allows you to build an Encoder for a Dhall record. For example, let's take the following Haskell data type:

>>> :{
data Project = Project
{ projectName :: Text
, projectDescription :: Text
, projectStars :: Natural
}
:}

And assume that we have the following Dhall record that we would like to parse as a Project:

{ name =
"dhall-haskell"
, description =
"A configuration language guaranteed to terminate"
, stars =
289
}

Our encoder has type Encoder Project, but we can't build that out of any smaller encoders, as Encoders cannot be combined (they are only Contravariants). However, we can use an RecordEncoder to build an Encoder for Project:

>>> :{
injectProject :: Encoder Project
injectProject =
recordEncoder
( adapt >$< encodeFieldWith "name" inject
>*< encodeFieldWith "description" inject
>*< encodeFieldWith "stars" inject
)
where
adapt (Project{..}) = (projectName, (projectDescription, projectStars))
:}

Or, since we are simply using the ToDhall instance to inject each field, we could write

>>> :{
injectProject :: Encoder Project
injectProject =
recordEncoder
( adapt >$< encodeField "name"
>*< encodeField "description"
>*< encodeField "stars"
)
where
adapt (Project{..}) = (projectName, (projectDescription, projectStars))
:}

UnionEncoder allows you to build an Encoder for a Dhall record. For example, let's take the following Haskell data type:

>>> :{
data Status = Queued Natural
| Result Text
| Errored Text
:}

And assume that we have the following Dhall union that we would like to parse as a Status:

< Result : Text
| Queued : Natural
| Errored : Text
>.Result "Finish successfully"

Our encoder has type Encoder Status, but we can't build that out of any smaller encoders, as Encoders cannot be combined. However, we can use an UnionEncoder to build an Encoder for Status:

>>> :{
injectStatus :: Encoder Status
injectStatus = adapt >$< unionEncoder
(   encodeConstructorWith "Queued"  inject
>|< encodeConstructorWith "Result"  inject
>|< encodeConstructorWith "Errored" inject
)
where
adapt (Queued  n) = Left n
adapt (Result  t) = Right (Left t)
adapt (Errored e) = Right (Right e)
:}

Or, since we are simply using the ToDhall instance to inject each branch, we could write

>>> :{
injectStatus :: Encoder Status
injectStatus = adapt >$< unionEncoder
(   encodeConstructor "Queued"
>|< encodeConstructor "Result"
>|< encodeConstructor "Errored"
)
where
adapt (Queued  n) = Left n
adapt (Result  t) = Right (Left t)
adapt (Errored e) = Right (Right e)
:}

Convert a RecordEncoder into the equivalent Encoder.

Convert a UnionEncoder into the equivalent Encoder.