| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Dovetail.Aeson
Description
This module provides support for using Dovetail with aeson.
For certain appliations, it is useful to use JSON as an input or output format, but to let the user decide the exact schema for that JSON data. The simplest way to let the user have control over this from Dovetail is to use PureScript's types to define the serialization functions. That is, just like with generic deriving, our serializers will be inferred from our types. But with Dovetail, we will use the inferred *PureScript* type to synthesize a serializer, not the Haskell types.
The query-json example in the repository is a good example. The user's program
defines a function from JSON inputs to JSON outputs, and the types and format
of the input and output data are determined by the type of the user's program,
which is allowed to be a function between any two *serializable* PureScript types.
Serializable types include primitives (strings, chars, ints, numbers and booleans),
records and arrays of other serializable types, and the special Nullable type
which is provided for handling serialization of nullable JSON substructures.
Note: you do not need to use this module if you are working with JSON whose structure is known ahead of time. In that case, you can simply use Dovetail directly to marshall Haskell data back and forth over the FFI boundary, and Aeson for serialization. This module should be used when the structure is not known ahead of time, because it is controlled by the user.
The user's program may have a polymorphic type signature. This can happen
easily: for example, if the user's program in the query-json example is a
record accessor such as _.foo, then it will have a polymorphic (indeed, also
row-polymorphic) type. We cannot know what JSON data the user will pass as an
input to a polymorphic program, and we can't synthesize a specific type for
that input data. So, this module also provides the UnknownJSON type for
handling these cases, which is simply a wrapper around Aeson's Value
type. Since a polymorphic program cannot inspect a value with a polymorphic
type (thanks to parametricity), it is safe to make this data accessible to
the program in this way. However, this also means that such data will not
be visible in the debugger (and instead, will appear as an abstract foreign
value).
Synopsis
- evalJSON :: Maybe ModuleName -> Text -> Interpret ctx Value
- type Serializable ctx a = (FromJSON a, ToJSON a, ToValue ctx a)
- reify :: forall ctx r. SourceType -> (forall a. Serializable ctx a => Proxy a -> Eval ctx r) -> Eval ctx r
- stdlib :: Interpret ctx (Module Ann)
- newtype Nullable a = Nullable (Maybe a)
- newtype UnknownJSON = UnknownJSON {}
Serializable types
Evaluation
evalJSON :: Maybe ModuleName -> Text -> Interpret ctx Value Source #
Evaluate a PureScript expression from source, returning its value as encoded JSON.
This function is a convenient counterpart to eval which can be useful
for applications whose output format is JSON.
Type reification
Arguments
| :: forall ctx r. SourceType | The PureScript type we wish to reify, for example, from the return value of |
| -> (forall a. Serializable ctx a => Proxy a -> Eval ctx r) | The continuation, which will receive a |
| -> Eval ctx r |
Reify a PureScript SourceType as a Haskell type which supports
transport via the FFI using ToValue, and JSON serialization using
ToJSON and FromJSON.
Just as DeriveGeneric allows us to derive a type-directed serialization
method based on the Haskell type of our values, this function allows us to
derive a serialization method based on the *PureScript* type of a value.
This can be useful in more advanced use cases where evalJSON won't suffice.
For example, if we want to take data as input from a JSON structure,
then we can reify the PureScript type of the domain of a PureScript function.
Supporting code
stdlib :: Interpret ctx (Module Ann) Source #
This action makes a module named JSON available to your PureScript code.
It defines the PureScript counterpart of the Nullable type, which is used
to serialize nullable types when deriving serializers using reify.
Any PureScript code which needs to support type-directed serialization for
values which may involve null should import this module.
newtype UnknownJSON Source #
A representation of arbitrary JSON values for use in derived serializers.
This type is reified to stand in for any polymorphic type variables in a PureScript type, since we cannot know the structure of values of those types ahead of time.
Constructors
| UnknownJSON | |
Fields | |
Instances
| ToJSON UnknownJSON Source # | |
Defined in Dovetail.Aeson Methods toJSON :: UnknownJSON -> Value # toEncoding :: UnknownJSON -> Encoding # toJSONList :: [UnknownJSON] -> Value # toEncodingList :: [UnknownJSON] -> Encoding # | |
| FromJSON UnknownJSON Source # | |
Defined in Dovetail.Aeson | |
| ToValue ctx UnknownJSON Source # | |
Defined in Dovetail.Aeson | |