Jordan

Base module!

Has all functionality for parsing and serializing JSON.

JSON Parsing

Abstractly

class FromJSON value where

A class to provide the canonical way to parse a JSON. This class uses finally tagless tyle to keep the instructions for parsing abstract. This allows us to automatically generate documentation, and to generate parsers that do not use 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 (FromJSON PersonFilter)

Laws

This instance is lawless, unless ToJSON is also defined for this type. In that case, the representation parsed by FromJSON should match that of the representation serialized by ToJSON.

Minimal complete definition

Nothing

Methods

fromJSON :: JSONParser f => f value

default fromJSON :: (Generic value, GFromJSON (Rep value), Typeable value) => JSONParser f => f value

Instances

FromJSON Bool

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Bool

FromJSON Double

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Double

FromJSON Float

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Float

FromJSON Int

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Int

FromJSON Int32

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Int32

FromJSON Int64

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Int64

FromJSON Integer

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Integer

FromJSON ()

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f ()

FromJSON All

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f All

FromJSON Any

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Any

FromJSON String

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f String

FromJSON Scientific

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Scientific

FromJSON Text

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Text

FromJSON JSONType

Defined in Jordan.Types.JSONType

Methods

fromJSON :: JSONParser f => f JSONType

FromJSON JSONArrayError

Defined in Jordan.Types.JSONError

Methods

fromJSON :: JSONParser f => f JSONArrayError

FromJSON JSONObjectError

Defined in Jordan.Types.JSONError

Methods

fromJSON :: JSONParser f => f JSONObjectError

FromJSON JSONError

Defined in Jordan.Types.JSONError

Methods

fromJSON :: JSONParser f => f JSONError

FromJSON JSONValue

Defined in Jordan.Types.JSONValue

Methods

fromJSON :: JSONParser f => f JSONValue

FromJSON a => FromJSON [a]

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f [a]

FromJSON a => FromJSON (Maybe a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Maybe a)

(Integral a, FromJSON a) => FromJSON (Ratio a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Ratio a)

FromJSON a => FromJSON (Min a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Min a)

FromJSON a => FromJSON (Max a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Max a)

FromJSON a => FromJSON (First a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (First a)

FromJSON a => FromJSON (Last a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Last a)

FromJSON a => FromJSON (First a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (First a)

FromJSON a => FromJSON (Last a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Last a)

FromJSON a => FromJSON (Dual a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Dual a)

FromJSON a => FromJSON (Sum a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Sum a)

FromJSON a => FromJSON (Product a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Product a)

FromJSON a => FromJSON (NonEmpty a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (NonEmpty a)

(FromJSON a, Ord a) => FromJSON (Set a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Set a)

(FromJSON l, FromJSON r) => FromJSON (Either l r)

Right-biased: will try to parse a Right value first.

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Either l r)

FromJSON a => FromJSON (Map Integer a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Map Integer a)

FromJSON a => FromJSON (Map Text a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Map Text a)

(Generic a, GFromJSON (Rep a), Typeable a, SpecifiesFromJSONOptions options) => FromJSON (WithOptions options a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (WithOptions options a)

FromJSON (f a) => FromJSON (Ap f a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f0 => f0 (Ap f a)

FromJSON (f a) => FromJSON (Alt f a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f0 => f0 (Alt f a)

class (Functor f, forall a. Semigroup (f a), Representational f) => JSONParser f where

Abstract class representing various parsers.

All parsers must have a Monoid instance that represents choice with failure as the identity.

Minimal complete definition

parseObject, parseDictionary, parseText, parseTuple, parseArrayWith, parseNumber, parseNull, parseBool, validateJSON

Methods

parseObject

Arguments

:: (forall objectParser. JSONObjectParser objectParser => objectParser a)

Instructions on how to parse the object. Note that the actual implementation is kept abstract: you can only use methods found in JSONObjectParser, or combinators of those methods. This ensures that we can generate the proper parser in all cases.

-> f a

parseObjectStrict :: (forall objectParser. JSONObjectParser objectParser => objectParser a) -> f a

Parse an object where you are okay if we parse strictly, IE, do not allow extra fields. This sometimes enables us to generate parsers that run faster.

parseDictionary :: (forall jsonParser. JSONParser jsonParser => jsonParser a) -> f [(Text, a)]

Parse a dictionary of key-value pairs.

parseText :: f Text

Parse a text field.

parseTextConstant :: Text -> f ()

parseTuple :: (forall arrayParser. JSONTupleParser arrayParser => arrayParser o) -> f o

Use a tuple parser to parse an array.

parseArray :: FromJSON a => f [a]

parseArrayWith :: (forall jsonParser. JSONParser jsonParser => jsonParser a) -> f [a]

parseNumber :: f Scientific

parseInteger :: f Integer

parseNull :: f ()

parseBool :: f Bool

validateJSON :: f (Either Text a) -> f a

nameParser :: Text -> f a -> f a

Give a parser a unique name. May be used for documentation.

addFormat :: Text -> f a -> f a

Add information about the format of a particular parser.

class (Applicative f, Representational f) => JSONObjectParser f where

A class for parsing JSON objects.

Minimal complete definition

parseFieldWith, parseFieldWithDefault

Methods

parseFieldWith

Arguments

:: Text

Label of the field. Will be parsed into escaped text, if need be.

-> (forall valueParser. JSONParser valueParser => valueParser a)

How to parse the field. Note the forall in this type signature: you cannot have this be specific to any particular implementation of parsing, to keep the parsing of a JSON abstract.

-> f a

Parse an object field with a given label, using a parser.

Note: in order to enable the generation of better documentation, use parseField instead if at all possible!

parseDescribeFieldWith

Arguments

:: Text

Field key to parse

-> Text

Description of the field

-> (forall valueParser. JSONParser valueParser => valueParser a)

Parser for the field

-> f a

parseField :: FromJSON v => Text -> f v

parseDescribeField :: FromJSON v => Text -> Text -> f v

parseFieldWithDefault

Arguments

:: Text

Label of the field.

-> (forall valueParser. JSONParser valueParser => valueParser a)

Parse the value from the field

-> a

Default value for the field

-> f a

Field in the object.

parseDescribeFieldWithDefault

Arguments

:: Text

Label of the field

-> Text

Description of the field

-> (forall valueParser. JSONParser valueParser => valueParser a)

Parser for the field

-> a

-> f a

class (Applicative f, Representational f) => JSONTupleParser f where

A class for parsing JSON arrays.

Minimal complete definition

consumeItemWith

Methods

consumeItemWith :: (forall valueParser. JSONParser valueParser => valueParser a) -> f a

Use a JSON parser to consume a single item of an array, then move onto the next one.

Note: you should prefer consumeItem as it enables better documentation generation.

consumeItem :: FromJSON v => f v

Consume a single array item.

Concretely

Via Attoparsec

These parsers use the excellent Attoparsec library to do their work. This means that they're quite fast, but that they also provide less-than-ideal error messages. You should use these when speed is needed, or when you're reasonably certain that nobody will make a mistake. APIs intended only for internal use, for example.

parseViaAttoparsec :: forall val. FromJSON val => ByteString -> Either String val

Parse a ByteString via an Attoparsec Parser.

parseViaAttoparsecWith :: (forall parser. JSONParser parser => parser a) -> ByteString -> Either String a

attoparsecParser :: FromJSON val => Parser val

Get an Attoparsec parser for a particular JSON-parsable value.

attoparsecParserFor :: (forall parser. JSONParser parser => parser a) -> Parser a

Convert an abstract JSON parser to an Attoparsec Parser. This function will skip leading whitespace.

With Error Reporting

These parsers parse to either a value or an *error report*, which is a detailed report of what exactly what wrong. This uses a roll-our-own parsing library based on *unboxed sums*. It's been tested via QuickCheck, but it is doing some spooky-scary raw pointer opertions.

This is a bit slower than the attoparsec parser, but *much* better at error handling. Use it for external-facing APIs---assuming that you trust my ability to write primops.

parseOrReport :: FromJSON a => ByteString -> Either JSONError a

parseOrReportWith :: (forall parser. JSONParser parser => parser a) -> ByteString -> Either JSONError a

Generically

gFromJSON :: (GFromJSON v, JSONParser f) => FromJSONOptions -> f (v a)

data FromJSONOptions

Constructors

FromJSONOptions

Fields

• fromJSONEncodeSums :: SumTypeEncoding
• fromJSONBaseName :: String
• convertEnum :: String -> String
• fromJSONOmitNothingFields :: Bool

Instances

Generic FromJSONOptions

Defined in Jordan.FromJSON.Class

Associated Types

type Rep FromJSONOptions :: Type -> Type

Methods

from :: FromJSONOptions -> Rep FromJSONOptions x

to :: Rep FromJSONOptions x -> FromJSONOptions

type Rep FromJSONOptions

Defined in Jordan.FromJSON.Class

type Rep FromJSONOptions = D1 ('MetaData "FromJSONOptions" "Jordan.FromJSON.Class" "jordan-0.2.0.0-inplace" 'False) (C1 ('MetaCons "FromJSONOptions" 'PrefixI 'True) ((S1 ('MetaSel ('Just "fromJSONEncodeSums") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 SumTypeEncoding) :*: S1 ('MetaSel ('Just "fromJSONBaseName") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 String)) :*: (S1 ('MetaSel ('Just "convertEnum") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (String -> String)) :*: S1 ('MetaSel ('Just "fromJSONOmitNothingFields") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool))))

JSON Serialization

Abstractly

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)

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 (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.

Re-Exports for Serialization

class Contravariant (f :: Type -> Type) where

The class of contravariant functors.

Whereas in Haskell, one can think of a Functor as containing or producing values, a contravariant functor is a functor that can be thought of as consuming values.

As an example, consider the type of predicate functions a -> Bool. One such predicate might be negative x = x < 0, which classifies integers as to whether they are negative. However, given this predicate, we can re-use it in other situations, providing we have a way to map values to integers. For instance, we can use the negative predicate on a person's bank balance to work out if they are currently overdrawn:

newtype Predicate a = Predicate { getPredicate :: a -> Bool }

instance Contravariant Predicate where
  contramap f (Predicate p) = Predicate (p . f)
                                         |   `- First, map the input...
                                         `----- then apply the predicate.

overdrawn :: Predicate Person
overdrawn = contramap personBankBalance negative

Any instance should be subject to the following laws:

Identity

contramap id = id

Composition

contramap (g . f) = contramap f . contramap g

Note, that the second law follows from the free theorem of the type of contramap and the first law, so you need only check that the former condition holds.

Minimal complete definition

contramap

Methods

contramap :: (a -> b) -> f b -> f a

(>$) :: b -> f b -> f a infixl 4

Replace all locations in the output with the same value. The default definition is contramap . const, but this may be overridden with a more efficient version.

Instances

Contravariant Predicate

A Predicate is a Contravariant Functor, because contramap can apply its function argument to the input of the predicate.

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> Predicate b -> Predicate a

(>$) :: b -> Predicate b -> Predicate a

Contravariant Comparison

A Comparison is a Contravariant Functor, because contramap can apply its function argument to each input of the comparison function.

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> Comparison b -> Comparison a

(>$) :: b -> Comparison b -> Comparison a

Contravariant Equivalence

Equivalence relations are Contravariant, because you can apply the contramapped function to each input to the equivalence relation.

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> Equivalence b -> Equivalence a

(>$) :: b -> Equivalence b -> Equivalence a

Contravariant JSONBuilder

Defined in Jordan.ToJSON.Builder

Methods

contramap :: (a -> b) -> JSONBuilder b -> JSONBuilder a

(>$) :: b -> JSONBuilder b -> JSONBuilder a

Contravariant (V1 :: Type -> Type)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> V1 b -> V1 a

(>$) :: b -> V1 b -> V1 a

Contravariant (U1 :: Type -> Type)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> U1 b -> U1 a

(>$) :: b -> U1 b -> U1 a

Contravariant (Op a)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a0 -> b) -> Op a b -> Op a a0

(>$) :: b -> Op a b -> Op a a0

Contravariant (Proxy :: Type -> Type)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> Proxy b -> Proxy a

(>$) :: b -> Proxy b -> Proxy a

Contravariant f => Contravariant (Rec1 f)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> Rec1 f b -> Rec1 f a

(>$) :: b -> Rec1 f b -> Rec1 f a

Contravariant (Const a :: Type -> Type)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a0 -> b) -> Const a b -> Const a a0

(>$) :: b -> Const a b -> Const a a0

Contravariant f => Contravariant (Alt f)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> Alt f b -> Alt f a

(>$) :: b -> Alt f b -> Alt f a

Contravariant m => Contravariant (ErrorT e m)

Defined in Control.Monad.Trans.Error

Methods

contramap :: (a -> b) -> ErrorT e m b -> ErrorT e m a

(>$) :: b -> ErrorT e m b -> ErrorT e m a

Contravariant (K1 i c :: Type -> Type)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> K1 i c b -> K1 i c a

(>$) :: b -> K1 i c b -> K1 i c a

(Contravariant f, Contravariant g) => Contravariant (f :+: g)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> (f :+: g) b -> (f :+: g) a

(>$) :: b -> (f :+: g) b -> (f :+: g) a

(Contravariant f, Contravariant g) => Contravariant (f :*: g)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> (f :*: g) b -> (f :*: g) a

(>$) :: b -> (f :*: g) b -> (f :*: g) a

(Contravariant f, Contravariant g) => Contravariant (Product f g)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> Product f g b -> Product f g a

(>$) :: b -> Product f g b -> Product f g a

(Contravariant f, Contravariant g) => Contravariant (Sum f g)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> Sum f g b -> Sum f g a

(>$) :: b -> Sum f g b -> Sum f g a

Contravariant f => Contravariant (M1 i c f)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> M1 i c f b -> M1 i c f a

(>$) :: b -> M1 i c f b -> M1 i c f a

(Functor f, Contravariant g) => Contravariant (f :.: g)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> (f :.: g) b -> (f :.: g) a

(>$) :: b -> (f :.: g) b -> (f :.: g) a

(Functor f, Contravariant g) => Contravariant (Compose f g)

Defined in Data.Functor.Contravariant

Methods

contramap :: (a -> b) -> Compose f g b -> Compose f g a

(>$) :: b -> Compose f g b -> Compose f g a

class Contravariant f => Divisible (f :: Type -> Type) where

A Divisible contravariant functor is the contravariant analogue of Applicative.

Continuing the intuition that Contravariant functors consume input, a Divisible contravariant functor also has the ability to be composed "beside" another contravariant functor.

Serializers provide a good example of Divisible contravariant functors. To begin let's start with the type of serializers for specific types:

newtype Serializer a = Serializer { runSerializer :: a -> ByteString }

This is a contravariant functor:

instance Contravariant Serializer where
  contramap f s = Serializer (runSerializer s . f)

That is, given a serializer for a (s :: Serializer a), and a way to turn bs into as (a mapping f :: b -> a), we have a serializer for b: contramap f s :: Serializer b.

Divisible gives us a way to combine two serializers that focus on different parts of a structure. If we postulate the existance of two primitive serializers - string :: Serializer String and int :: Serializer Int, we would like to be able to combine these into a serializer for pairs of Strings and Ints. How can we do this? Simply run both serializers and combine their output!

data StringAndInt = StringAndInt String Int

stringAndInt :: Serializer StringAndInt
stringAndInt = Serializer $ \(StringAndInt s i) ->
  let sBytes = runSerializer string s
      iBytes = runSerializer int i
  in sBytes <> iBytes

divide is a generalization by also taking a contramap like function to split any a into a pair. This conveniently allows you to target fields of a record, for instance, by extracting the values under two fields and combining them into a tuple.

To complete the example, here is how to write stringAndInt using a Divisible instance:

instance Divisible Serializer where
  conquer = Serializer (const mempty)

  divide toBC bSerializer cSerializer = Serializer $ \a ->
    case toBC a of
      (b, c) ->
        let bBytes = runSerializer bSerializer b
            cBytes = runSerializer cSerializer c
        in bBytes <> cBytes

stringAndInt :: Serializer StringAndInt
stringAndInt =
  divide (\(StringAndInt s i) -> (s, i)) string int

Methods

divide :: (a -> (b, c)) -> f b -> f c -> f a

conquer :: f a

Conquer acts as an identity for combining Divisible functors.

Instances

Divisible SettableStateVar

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> SettableStateVar b -> SettableStateVar c -> SettableStateVar a

conquer :: SettableStateVar a

Divisible Predicate

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Predicate b -> Predicate c -> Predicate a

conquer :: Predicate a

Divisible Comparison

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Comparison b -> Comparison c -> Comparison a

conquer :: Comparison a

Divisible Equivalence

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Equivalence b -> Equivalence c -> Equivalence a

conquer :: Equivalence a

Divisible (U1 :: Type -> Type)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> U1 b -> U1 c -> U1 a

conquer :: U1 a

Monoid r => Divisible (Op r)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Op r b -> Op r c -> Op r a

conquer :: Op r a

Divisible (Proxy :: Type -> Type)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Proxy b -> Proxy c -> Proxy a

conquer :: Proxy a

Divisible m => Divisible (MaybeT m)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> MaybeT m b -> MaybeT m c -> MaybeT m a

conquer :: MaybeT m a

Divisible m => Divisible (ListT m)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> ListT m b -> ListT m c -> ListT m a

conquer :: ListT m a

Divisible f => Divisible (Rec1 f)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Rec1 f b -> Rec1 f c -> Rec1 f a

conquer :: Rec1 f a

Monoid m => Divisible (Const m :: Type -> Type)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Const m b -> Const m c -> Const m a

conquer :: Const m a

Divisible f => Divisible (Alt f)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Alt f b -> Alt f c -> Alt f a

conquer :: Alt f a

Divisible f => Divisible (Reverse f)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Reverse f b -> Reverse f c -> Reverse f a

conquer :: Reverse f a

Monoid m => Divisible (Constant m :: Type -> Type)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Constant m b -> Constant m c -> Constant m a

conquer :: Constant m a

Divisible m => Divisible (WriterT w m)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> WriterT w m b -> WriterT w m c -> WriterT w m a

conquer :: WriterT w m a

Divisible m => Divisible (WriterT w m)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> WriterT w m b -> WriterT w m c -> WriterT w m a

conquer :: WriterT w m a

Divisible m => Divisible (StateT s m)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> StateT s m b -> StateT s m c -> StateT s m a

conquer :: StateT s m a

Divisible m => Divisible (StateT s m)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> StateT s m b -> StateT s m c -> StateT s m a

conquer :: StateT s m a

Divisible m => Divisible (ReaderT r m)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> ReaderT r m b -> ReaderT r m c -> ReaderT r m a

conquer :: ReaderT r m a

Divisible f => Divisible (IdentityT f)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> IdentityT f b -> IdentityT f c -> IdentityT f a

conquer :: IdentityT f a

Divisible m => Divisible (ExceptT e m)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> ExceptT e m b -> ExceptT e m c -> ExceptT e m a

conquer :: ExceptT e m a

Divisible m => Divisible (ErrorT e m)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> ErrorT e m b -> ErrorT e m c -> ErrorT e m a

conquer :: ErrorT e m a

Divisible f => Divisible (Backwards f)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Backwards f b -> Backwards f c -> Backwards f a

conquer :: Backwards f a

(Divisible f, Divisible g) => Divisible (f :*: g)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> (f :*: g) b -> (f :*: g) c -> (f :*: g) a

conquer :: (f :*: g) a

(Divisible f, Divisible g) => Divisible (Product f g)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Product f g b -> Product f g c -> Product f g a

conquer :: Product f g a

Divisible f => Divisible (M1 i c f)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c0)) -> M1 i c f b -> M1 i c f c0 -> M1 i c f a

conquer :: M1 i c f a

(Applicative f, Divisible g) => Divisible (f :.: g)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> (f :.: g) b -> (f :.: g) c -> (f :.: g) a

conquer :: (f :.: g) a

(Applicative f, Divisible g) => Divisible (Compose f g)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> Compose f g b -> Compose f g c -> Compose f g a

conquer :: Compose f g a

Divisible m => Divisible (RWST r w s m)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> RWST r w s m b -> RWST r w s m c -> RWST r w s m a

conquer :: RWST r w s m a

Divisible m => Divisible (RWST r w s m)

Defined in Data.Functor.Contravariant.Divisible

Methods

divide :: (a -> (b, c)) -> RWST r w s m b -> RWST r w s m c -> RWST r w s m a

conquer :: RWST r w s m a

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

Concretely

toJSONAsBuilder :: ToJSON a => a -> Builder

Serialize a Haskell datatype to a Builder.

This is available for performance reasons: you may wish to use hPutBuilder in order to (more or less) directly serialize some JSON object to a file handle.

toJSONViaBuilder :: ToJSON a => a -> ByteString

Serialize a Haskell datatype to a lazy ByteString.

Generically

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

data ToJSONOptions

Constructors

ToJSONOptions

Fields

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

Parsing or Serializing Arbitrary JSON

data JSONValue

A type for any JSON value. This is a basic Haskell sum type representation.

This is intended to for use when working with JSON where you do not know much about its structure.

Constructors

JNull

JBool Bool

JText Text

JNumber Scientific

JArray [JSONValue]

JObject (Map Text JSONValue)

Instances

Eq JSONValue

Defined in Jordan.Types.JSONValue

Methods

(==) :: JSONValue -> JSONValue -> Bool

(/=) :: JSONValue -> JSONValue -> Bool

Ord JSONValue

Defined in Jordan.Types.JSONValue

Methods

compare :: JSONValue -> JSONValue -> Ordering

(<) :: JSONValue -> JSONValue -> Bool

(<=) :: JSONValue -> JSONValue -> Bool

(>) :: JSONValue -> JSONValue -> Bool

(>=) :: JSONValue -> JSONValue -> Bool

max :: JSONValue -> JSONValue -> JSONValue

min :: JSONValue -> JSONValue -> JSONValue

Show JSONValue

Defined in Jordan.Types.JSONValue

Methods

showsPrec :: Int -> JSONValue -> ShowS

show :: JSONValue -> String

showList :: [JSONValue] -> ShowS

Generic JSONValue

Defined in Jordan.Types.JSONValue

Associated Types

type Rep JSONValue :: Type -> Type

Methods

from :: JSONValue -> Rep JSONValue x

to :: Rep JSONValue x -> JSONValue

FromJSON JSONValue

Defined in Jordan.Types.JSONValue

Methods

fromJSON :: JSONParser f => f JSONValue

ToJSON JSONValue

Defined in Jordan.Types.JSONValue

Methods

toJSON :: JSONSerializer f => f JSONValue

type Rep JSONValue

Defined in Jordan.Types.JSONValue

type Rep JSONValue = D1 ('MetaData "JSONValue" "Jordan.Types.JSONValue" "jordan-0.2.0.0-inplace" 'False) ((C1 ('MetaCons "JNull" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "JBool" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool)) :+: C1 ('MetaCons "JText" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Text)))) :+: (C1 ('MetaCons "JNumber" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Scientific)) :+: (C1 ('MetaCons "JArray" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [JSONValue])) :+: C1 ('MetaCons "JObject" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Map Text JSONValue))))))

Newtypes for DerivingVia

newtype WithOptions (options :: [*]) a

A newtype wrapper, designed to make it easier to derive ToJSON and FromJSON instances. The API of abstract JSON serializing is awkward due to the somewhat bad ergonomics of the Divisible and (especially) Decidable typeclasses.

In general, using -XDerivingVia , -XDeriveGeneric , -XDataKinds and this wrapper will make your life much easier. Unfortunately, due to a weird GHC quirk, you also need -XDerivingVia .

That is, the following won't work, complaining about role errors:

 data PersonFilter = PersonFilter { filterFirstName :: Maybe Text, filterLastName :: Maybe Text }
   deriving (Show, Generic)
   deriving (ToJSON, FromJSON) via (WithOptions '[KeepNothingFields] PersonFilter)

But this will:

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

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

Constructors

WithOptions

Fields

• getWithOptions :: a

Instances

Eq a => Eq (WithOptions options a)

Defined in Jordan.Generic.Options

Methods

(==) :: WithOptions options a -> WithOptions options a -> Bool

(/=) :: WithOptions options a -> WithOptions options a -> Bool

Ord a => Ord (WithOptions options a)

Defined in Jordan.Generic.Options

Methods

compare :: WithOptions options a -> WithOptions options a -> Ordering

(<) :: WithOptions options a -> WithOptions options a -> Bool

(<=) :: WithOptions options a -> WithOptions options a -> Bool

(>) :: WithOptions options a -> WithOptions options a -> Bool

(>=) :: WithOptions options a -> WithOptions options a -> Bool

max :: WithOptions options a -> WithOptions options a -> WithOptions options a

min :: WithOptions options a -> WithOptions options a -> WithOptions options a

Show a => Show (WithOptions options a)

Defined in Jordan.Generic.Options

Methods

showsPrec :: Int -> WithOptions options a -> ShowS

show :: WithOptions options a -> String

showList :: [WithOptions options a] -> ShowS

(Generic a, GFromJSON (Rep a), Typeable a, SpecifiesFromJSONOptions options) => FromJSON (WithOptions options a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (WithOptions options 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 OmitNothingFields

Newtype for use with GeneralizedNewtypeDeriving. Will have us omit Nothing fields for parsing and serializing.

Instances

SpecifiesFromJSONOptions xs => SpecifiesFromJSONOptions (OmitNothingFields ': xs)

Defined in Jordan.FromJSON.Class

Methods

specifiedFromJSONOptions :: FromJSONOptions

SpecifiesToJSONOptions xs => SpecifiesToJSONOptions (OmitNothingFields ': xs)

Defined in Jordan.ToJSON.Class

Methods

specifiedToJSONOptions :: ToJSONOptions

data KeepNothingFields

Keep nothing fields. Will have us omit null when serializing Maybe types.

Instances

SpecifiesFromJSONOptions xs => SpecifiesFromJSONOptions (KeepNothingFields ': xs)

Defined in Jordan.FromJSON.Class

Methods

specifiedFromJSONOptions :: FromJSONOptions

SpecifiesToJSONOptions xs => SpecifiesToJSONOptions (KeepNothingFields ': xs)

Defined in Jordan.ToJSON.Class

Methods

specifiedToJSONOptions :: ToJSONOptions