Jordan.ToJSON.Class

Documentation

class Contravariant f => Selectable f where

Basically just Decidable but without a superclass constraint that we cannot implement for JSON.

More specifically, we can quite easily serialize some object into either a string or a number as a top-level JSON value, but we cannot serialize both a string and a number as a top level key. This means that we cannot implement Divisible, but we can implement all the operations from Decidable.

This class lets us decide without being able to divide, which is fun to say.

Methods

giveUp :: (arg -> Void) -> f arg

Give up trying to decide.

select :: (arg -> Either lhs rhs) -> f lhs -> f rhs -> f arg

Pick one thing, or another, as long as you can serialize both options.

Instances

Selectable JSONBuilder

Defined in Jordan.ToJSON.Builder

Methods

giveUp :: (arg -> Void) -> JSONBuilder arg

select :: (arg -> Either lhs rhs) -> JSONBuilder lhs -> JSONBuilder rhs -> JSONBuilder arg

selected :: Selectable f => f lhs -> f rhs -> f (Either lhs rhs)

class (Divisible f, Representational f) => JSONObjectSerializer f where

An abstract representation of how to serialize a JSON object. Since serializing is the exact opposite of parsing, we have to be Decidable instead of Alternative.

That is, if we are serializing a JSON object, we need to be able to break things apart.

Unfortunately the combinators for breaking things apart are more annoying to use than the combinators for putting things together, and involve a lot of tuples everywhere.

Thankfully we provide a good interface to derive these classes generically!

Minimal complete definition

serializeFieldWith, serializeJust

Methods

serializeFieldWith

Arguments

:: Text

Label for the field to serialize

-> (forall jsonSerializer. JSONSerializer jsonSerializer => jsonSerializer a)

How to serialize the field. The forall ensures that JSON serialization is kept completely abstract. You can only use the methods of JSONSerializer here.

-> f a

serializeField :: ToJSON a => Text -> f a

serializeDescribeFieldWith

Arguments

:: Text

Field key to serialize.

-> Text

Field description.

-> (forall valueSerializer. JSONSerializer valueSerializer => valueSerializer a)

Serializer for the field.

-> f a

serializeJust

Arguments

:: Text

Label for the field to serialize

-> (forall jsonSerializer. JSONSerializer jsonSerializer => jsonSerializer a)

Serializer for Just

-> f (Maybe a)

Write if we have Just a value. Do not add the field otherwise.

class (Divisible f, Representational f) => JSONTupleSerializer f where

Minimal complete definition

serializeItemWith

Methods

serializeItemWith

Arguments

:: (forall jsonSerializer. JSONSerializer jsonSerializer => jsonSerializer a)

Write a single item into the tuple. The forall keeps things abstract.

-> f a

serializeItem :: ToJSON a => f a

class (Selectable f, Representational f) => JSONSerializer f where

An abstract representation of how to serialize a Haskell value into JSON.

Minimal complete definition

serializeObject, serializeDictionary, serializeText, serializeTextConstant, serializeNull, serializeNumber, serializeBool, serializeTuple, serializeArray

Methods

serializeObject

Arguments

:: (forall objSerializer. JSONObjectSerializer objSerializer => objSerializer a)

How to serialize the object. The forall here keeps things abstract: you are only allowed to use the methods of JSONObjectSerializer here.

-> f a

serializeDictionary :: Foldable t => (forall jsonSerializer. JSONSerializer jsonSerializer => jsonSerializer a) -> f (t (Text, a))

serializeText :: f Text

serializeTextConstant :: Text -> f a

Serialize some text constant. Note that this returns a serializer of anything: if you are always going to serialize out the same string, we don't need to even look at the thing we're serializing!

serializeNull :: f any

serializeNumber :: f Scientific

serializeBool :: f Bool

serializeTuple :: (forall tupleSerializer. JSONTupleSerializer tupleSerializer => tupleSerializer a) -> f a

serializeArray :: ToJSON a => f [a]

nameSerializer :: Text -> f a -> f a

Give a name to a serializer. Should be globally unique, if possible.

Instances

JSONSerializer JSONBuilder

Defined in Jordan.ToJSON.Builder

Methods

serializeObject :: (forall (objSerializer :: Type -> Type). JSONObjectSerializer objSerializer => objSerializer a) -> JSONBuilder a

serializeDictionary :: Foldable t => (forall (jsonSerializer :: Type -> Type). JSONSerializer jsonSerializer => jsonSerializer a) -> JSONBuilder (t (Text, a))

serializeText :: JSONBuilder Text

serializeTextConstant :: Text -> JSONBuilder a

serializeNull :: JSONBuilder any

serializeNumber :: JSONBuilder Scientific

serializeBool :: JSONBuilder Bool

serializeTuple :: (forall (tupleSerializer :: Type -> Type). JSONTupleSerializer tupleSerializer => tupleSerializer a) -> JSONBuilder a

serializeArray :: ToJSON a => JSONBuilder [a]

nameSerializer :: Text -> JSONBuilder a -> JSONBuilder a

class ToJSON v where

A class to provide the canonical way to encode a JSON.

This class uses finally tagless style to keep the instructions for serializing abstract. This allows us to automatically generate documentation, and to generate serializers that always avoid the need for intermediate structures.

This class is derivable generically, and will generate a "nice" format. In my opinion, at least.

If you want to customize this JSON, the newtype WithOptions can be helpful, as it allows you to specify options for the generic serialization. Unfortunately, due to a weird GHC quirk, you need to use it with -XStandaloneDeriving as well as -XDerivingVia . That is, you should write:

data PersonFilter = PersonFilter { filterFirstName :: Maybe Text, filterLastName :: Maybe Text }
  deriving (Show, Read, Eq, Ord, Generic)

deriving via (WithOptions '[KeepNothingFields] PersonFilter) instance (ToJSON PersonFilter)

Minimal complete definition

Nothing

Methods

toJSON :: forall f. JSONSerializer f => f v

default toJSON :: (Generic v, GToJSON (Rep v), Typeable v) => JSONSerializer f => f v

Instances

ToJSON Bool

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f Bool

ToJSON Double

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f Double

ToJSON Float

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f Float

ToJSON Int

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f Int

ToJSON Integer

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f Integer

ToJSON ()

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f ()

ToJSON All

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f All

ToJSON Any

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f Any

ToJSON String

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f String

ToJSON Scientific

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f Scientific

ToJSON Text

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f Text

ToJSON JSONType

Defined in Jordan.Types.JSONType

Methods

toJSON :: JSONSerializer f => f JSONType

ToJSON JSONArrayError

Defined in Jordan.Types.JSONError

Methods

toJSON :: JSONSerializer f => f JSONArrayError

ToJSON JSONObjectError

Defined in Jordan.Types.JSONError

Methods

toJSON :: JSONSerializer f => f JSONObjectError

ToJSON JSONError

Defined in Jordan.Types.JSONError

Methods

toJSON :: JSONSerializer f => f JSONError

ToJSON JSONValue

Defined in Jordan.Types.JSONValue

Methods

toJSON :: JSONSerializer f => f JSONValue

ToJSON a => ToJSON [a]

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f [a]

ToJSON a => ToJSON (Maybe a)

Nothings get serialized as null.

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (Maybe a)

(ToJSON a, Typeable a) => ToJSON (Ratio a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (Ratio a)

ToJSON a => ToJSON (Min a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (Min a)

ToJSON a => ToJSON (Max a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (Max a)

ToJSON a => ToJSON (First a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (First a)

ToJSON a => ToJSON (Last a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (Last a)

ToJSON a => ToJSON (Dual a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (Dual a)

ToJSON a => ToJSON (Sum a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (Sum a)

ToJSON a => ToJSON (Product a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (Product a)

ToJSON a => ToJSON (NonEmpty a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (NonEmpty a)

ToJSON a => ToJSON (Set a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (Set a)

(ToJSON lhs, ToJSON rhs) => ToJSON (Either lhs rhs)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (Either lhs rhs)

ToJSON a => ToJSON (Map Integer a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (Map Integer a)

ToJSON a => ToJSON (Map Text a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (Map Text a)

(Generic a, GToJSON (Rep a), Typeable a, SpecifiesToJSONOptions options) => ToJSON (WithOptions options a)

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f (WithOptions options a)

data ToJSONOptions

Constructors

ToJSONOptions

Fields

• toJSONEncodeSums :: SumTypeEncoding
• toJSONBaseName :: String
• toJSONRenderEnum :: String -> String
• toJSONOmitNothingFields :: Bool

defaultToJSONOptions :: ToJSONOptions

class SpecifiesToJSONOptions (a :: [*]) where

Methods

specifiedToJSONOptions :: ToJSONOptions

Instances

SpecifiesToJSONOptions ('[] :: [Type])

Defined in Jordan.ToJSON.Class

Methods

specifiedToJSONOptions :: ToJSONOptions

SpecifiesToJSONOptions xs => SpecifiesToJSONOptions (KeepNothingFields ': xs)

Defined in Jordan.ToJSON.Class

Methods

specifiedToJSONOptions :: ToJSONOptions

SpecifiesToJSONOptions xs => SpecifiesToJSONOptions (OmitNothingFields ': xs)

Defined in Jordan.ToJSON.Class

Methods

specifiedToJSONOptions :: ToJSONOptions

class GToJSON v where

Methods

gToJSON :: JSONSerializer s => ToJSONOptions -> s (v a)

Instances

GToJSON (V1 :: Type -> Type)

Defined in Jordan.ToJSON.Class

Methods

gToJSON :: JSONSerializer s => ToJSONOptions -> s (V1 a)

(GToJSON (PartOfSum l), GToJSON (PartOfSum r)) => GToJSON (PartOfSum (l :+: r))

Defined in Jordan.ToJSON.Class

Methods

gToJSON :: JSONSerializer s => ToJSONOptions -> s (PartOfSum (l :+: r) a)

(Constructor t, GToJSON (C1 t f)) => GToJSON (PartOfSum (C1 t f))

When rendering a sum type, and this is NOT an enum value, render via the sum encoding option the user provided.

Defined in Jordan.ToJSON.Class

Methods

gToJSON :: JSONSerializer s => ToJSONOptions -> s (PartOfSum (C1 t f) a)

KnownSymbol name => GToJSON (PartOfSum (C1 ('MetaCons name fixity 'False) (U1 :: Type -> Type)))

Defined in Jordan.ToJSON.Class

Methods

gToJSON :: JSONSerializer s => ToJSONOptions -> s (PartOfSum (C1 ('MetaCons name fixity 'False) U1) a)

ToJSON c => GToJSON (K1 i c :: Type -> Type)

Top-level metadata is ignored.

Defined in Jordan.ToJSON.Class

Methods

gToJSON :: JSONSerializer s => ToJSONOptions -> s (K1 i c a)

(GToJSON (PartOfSum l), GToJSON (PartOfSum r)) => GToJSON (l :+: r)

If we can serialize out both sides of a sum-type, we can serialize out the sum type.

Defined in Jordan.ToJSON.Class

Methods

gToJSON :: JSONSerializer s => ToJSONOptions -> s ((l :+: r) a)

(GToJSON f, Datatype t) => GToJSON (D1 t f)

Datatype metadata: we name the overall datatype with the baseName passed in the options, then serialize the inner information.

Defined in Jordan.ToJSON.Class

Methods

gToJSON :: JSONSerializer s => ToJSONOptions -> s (D1 t f a)

ToJSON i => GToJSON (C1 ('MetaCons n s 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) su ss ds) (Rec0 i)))

If we have a single-argument constructor with no selectors, we want to just parse it directly.

Defined in Jordan.ToJSON.Class

Methods

gToJSON :: JSONSerializer s0 => ToJSONOptions -> s0 (C1 ('MetaCons n s 'False) (S1 ('MetaSel 'Nothing su ss ds) (Rec0 i)) a)

KnownSymbol name => GToJSON (C1 ('MetaCons name fixity 'False) (U1 :: Type -> Type))

Serialize out a no-argument constructor via a string value of its name. This allows us to serialize out enum keys more easily.

This does not get a unique name as recursion cannot happen.

Defined in Jordan.ToJSON.Class

Methods

gToJSON :: JSONSerializer s => ToJSONOptions -> s (C1 ('MetaCons name fixity 'False) U1 a)

(GToJSONObject inner, Constructor ('MetaCons n s 'True)) => GToJSON (C1 ('MetaCons n s 'True) inner)

If we have a constructor with arguments AND selectors (IE, a record), then we serialize out a JSON object.

Defined in Jordan.ToJSON.Class

Methods

gToJSON :: JSONSerializer s0 => ToJSONOptions -> s0 (C1 ('MetaCons n s 'True) inner a)

(GToJSONTuple inner, Constructor ('MetaCons n s 'False)) => GToJSON (C1 ('MetaCons n s 'False) inner)

IF we have a constructor with arguments, but not selectors, then we serialize as a tuple.

Defined in Jordan.ToJSON.Class

Methods

gToJSON :: JSONSerializer s0 => ToJSONOptions -> s0 (C1 ('MetaCons n s 'False) inner a)

sumToEither :: (l :+: r) a -> Either (l a) (r a)

class GToJSONObject v where

Type class for generically converting to a JSON object. We can do this if all the fields under a constructor are named.

Methods

gToJSONObject :: JSONObjectSerializer f => ToJSONOptions -> f (v a)

Instances

(GToJSONObject lhs, GToJSONObject rhs) => GToJSONObject (lhs :*: rhs)

Defined in Jordan.ToJSON.Class

Methods

gToJSONObject :: JSONObjectSerializer f => ToJSONOptions -> f ((lhs :*: rhs) a)

(GToJSON f, KnownSymbol selector) => GToJSONObject (S1 ('MetaSel ('Just selector) su ss ds) f)

Defined in Jordan.ToJSON.Class

Methods

gToJSONObject :: JSONObjectSerializer f0 => ToJSONOptions -> f0 (S1 ('MetaSel ('Just selector) su ss ds) f a)

(ToJSON a, KnownSymbol selector) => GToJSONObject (S1 ('MetaSel ('Just selector) su ss ds) (Rec0 (Maybe a)))

Defined in Jordan.ToJSON.Class

Methods

gToJSONObject :: JSONObjectSerializer f => ToJSONOptions -> f (S1 ('MetaSel ('Just selector) su ss ds) (Rec0 (Maybe a)) a0)

class GToJSONTuple v where

Methods

gToJSONTuple :: JSONTupleSerializer f => ToJSONOptions -> f (v a)

Instances

(GToJSONTuple lhs, GToJSONTuple rhs) => GToJSONTuple (lhs :*: rhs)

Defined in Jordan.ToJSON.Class

Methods

gToJSONTuple :: JSONTupleSerializer f => ToJSONOptions -> f ((lhs :*: rhs) a)

GToJSON f => GToJSONTuple (S1 ('MetaSel ('Nothing :: Maybe Symbol) su ss ds) f)

Defined in Jordan.ToJSON.Class

Methods

gToJSONTuple :: JSONTupleSerializer f0 => ToJSONOptions -> f0 (S1 ('MetaSel 'Nothing su ss ds) f a)