Jordan

Base module!

Has all functionality for parsing and serializing JSON.

JSON Parsing

Concretely

parseViaMegaparsec :: forall val. FromJSON val => Text -> Either String val

Parse an object for which FromJSON is defined via Megaparsec.

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

Parse a ByteString via an Attoparsec Parser.

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

runParserViaMegaparsec :: (forall parser. JSONParser parser => parser a) -> Text -> Either String a

Run an abstract JSONParser via Megaparsec.

attoparsecParser :: FromJSON val => Parser val

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

megaparsecParser :: FromJSON val => Parser val

Get a megaparsec parser for your JSON value. This parser will not construct any intermediate maps or other structures - your object will be parsed directly!

Note: this parser, until the ones that are built into the class, can consume whitespace at the start of the JSON.

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.

Minimal complete definition

Nothing

Methods

fromJSON :: JSONParser f => f value

default fromJSON :: (Generic value, GFromJSON (Rep 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 Integer

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Integer

FromJSON ()

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f ()

FromJSON Text

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Text

FromJSON String

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f String

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 Scientific

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f Scientific

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, Typeable 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, 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 Text a)

Defined in Jordan.FromJSON.Class

Methods

fromJSON :: JSONParser f => f (Map Text 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. Monoid (f a)) => 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

:: Text

A label for the object. This label should, as much as possible, be "globally unique" in some way. This will enable better generation of documentation.

-> (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 :: Text -> (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

parseNull :: f ()

parseBool :: f Bool

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

Instances

JSONParser MegaparsecParser

Defined in Jordan.FromJSON.Megaparsec

Methods

parseObject :: Text -> (forall (objectParser :: Type -> Type). JSONObjectParser objectParser => objectParser a) -> MegaparsecParser a

parseObjectStrict :: Text -> (forall (objectParser :: Type -> Type). JSONObjectParser objectParser => objectParser a) -> MegaparsecParser a

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

parseText :: MegaparsecParser Text

parseTextConstant :: Text -> MegaparsecParser ()

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

parseArray :: FromJSON a => MegaparsecParser [a]

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

parseNumber :: MegaparsecParser Scientific

parseNull :: MegaparsecParser ()

parseBool :: MegaparsecParser Bool

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

class Applicative f => JSONObjectParser f where

A class for parsing JSON objects.

Minimal complete definition

parseFieldWith

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!

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

Instances

JSONObjectParser ObjectParser

Defined in Jordan.FromJSON.Megaparsec

Methods

parseFieldWith :: Text -> (forall (valueParser :: Type -> Type). JSONParser valueParser => valueParser a) -> ObjectParser a

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

class Applicative 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.

Instances

JSONTupleParser ArrayParser

Defined in Jordan.FromJSON.Megaparsec

Methods

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

consumeItem :: FromJSON v => ArrayParser v

Generically

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

data FromJSONOptions

Constructors

FromJSONOptions

Fields

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

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.1.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)))))

JSON Serialization

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.

toJSONText :: ToJSON a => a -> Text

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.

Minimal complete definition

Nothing

Methods

toJSON :: JSONSerializer f => f v

default toJSON :: (Generic v, GToJSON (Rep 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 Text

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f Text

ToJSON String

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f String

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 Scientific

Defined in Jordan.ToJSON.Class

Methods

toJSON :: JSONSerializer f => f Scientific

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 lhs, ToJSON rhs) => ToJSON (Either lhs rhs)

Defined in Jordan.ToJSON.Class

Methods

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

ToJSON a => ToJSON (Map Text a)

Defined in Jordan.ToJSON.Class

Methods

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

class Selectable f => JSONSerializer f where

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

Methods

serializeObject

Arguments

:: Text

A name for the object. Should be "globally unique" as much as possible.

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

Instances

JSONSerializer JSONBuilder

Defined in Jordan.ToJSON.Builder

Methods

serializeObject :: Text -> (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]

JSONSerializer JSONText

Defined in Jordan.ToJSON.Text

Methods

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

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

serializeText :: JSONText Text

serializeTextConstant :: Text -> JSONText a

serializeNull :: JSONText any

serializeNumber :: JSONText Scientific

serializeBool :: JSONText Bool

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

serializeArray :: ToJSON a => JSONText [a]

class Divisible 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!

Methods

writeField

Arguments

:: Text

Label for the field to write

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

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

-> f a

Instances

JSONObjectSerializer CommaBuilder

Defined in Jordan.ToJSON.Text

Methods

writeField :: Text -> (forall (jsonSerializer :: Type -> Type). JSONSerializer jsonSerializer => jsonSerializer a) -> CommaBuilder a

Generically

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

data ToJSONOptions

Constructors

ToJSONOptions

Fields

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