Data.API.JSON

This module defines a JSON parser, like Aeson's FromJSON, but with more detailed error-reporting capabilities. In particular, it reports errors in a structured format, and can report multiple independent errors rather than stopping on the first one encountered.

Representation of JSON parsing errors

data JSONError

Represents an error that can be encountered while parsing

Constructors

Expected Expected String Value

BadFormat FormatExpected String Text

MissingField

MissingAlt [String]

UnexpectedField

UnexpectedEnumVal [Text] Text

IntRangeError String Int IntRange

UTCRangeError String UTCTime UTCRange

RegexError String Text RegEx

SyntaxError String

Instances

Eq JSONError

Show JSONError

ToJSON JSONError

FromJSON JSONError

data Expected

JSON type expected at a particular position, when a value of a different type was encountered

Constructors

ExpArray

ExpBool

ExpInt

ExpObject

ExpString

Instances

Eq Expected

Show Expected

ToJSON Expected

FromJSON Expected

data FormatExpected

Special format expected of a string

Constructors

FmtBinary

FmtUTC

FmtOther

Instances

Eq FormatExpected

Show FormatExpected

ToJSON FormatExpected

FromJSON FormatExpected

type Position = [Step]

A position inside a JSON value is a list of steps, ordered innermost first (so going inside an object prepends a step).

data Step

Each step may be into a field of an object, or a specific element of an array.

Constructors

InField Text

InElem Int

Instances

Eq Step

Show Step

ToJSON Step

FromJSON Step

SafeCopy Step

PPLines Step

prettyJSONErrorPositions :: [(JSONError, Position)] -> String

Human-readable presentation of a list of parse errors with their positions

prettyJSONError :: JSONError -> String

Human-readable description of a JSON parse error

prettyStep :: Step -> String

Human-readable description of a single step in a position

Parser with multiple error support

data ParserWithErrs a

Like Parser, but keeping track of locations within the JSON structure and able to report multiple errors.

Careful! The Monad instance does not agree with the Applicative instance in all circumstances, and you should use the Applicative instance where possible. In particular:

• pf <*> ps returns errors from both arguments
• pf `ap` ps returns errors from pf only

Instances

Monad ParserWithErrs

Functor ParserWithErrs

Applicative ParserWithErrs

Alternative ParserWithErrs

data ParseFlags

Options to modify the behaviour of the JSON parser

defaultParseFlags :: ParseFlags

Use this as a basis for overriding individual fields of the ParseFlags record, in case more flags are added in the future.

runParserWithErrsTop :: ParseFlags -> ParserWithErrs a -> Either [(JSONError, Position)] a

FromJSON class with multiple error support

class FromJSONWithErrs a where

Like FromJSON, but keeping track of multiple errors and their positions. Moreover, this class is more liberal in accepting invalid inputs:

• a string like "3" is accepted as an integer; and
• the integers 0 and 1 are accepted as booleans.

Methods

parseJSONWithErrs :: Value -> ParserWithErrs a

Parse a JSON value with structured error-reporting support. If this method is omitted, fromJSON will be used instead: note that this will result in less precise errors.

Instances

FromJSONWithErrs Bool

FromJSONWithErrs Int

FromJSONWithErrs Integer

FromJSONWithErrs ()

FromJSONWithErrs Text

FromJSONWithErrs UTCTime

FromJSONWithErrs Value

FromJSONWithErrs Version

FromJSONWithErrs Binary

FromJSONWithErrs Thing

Generate an API spec from the JSON

FromJSONWithErrs DefaultValue

FromJSONWithErrs BasicType

FromJSONWithErrs TypeRef

FromJSONWithErrs APIType

FromJSONWithErrs Field

FromJSONWithErrs Conversion

FromJSONWithErrs UTCRange

FromJSONWithErrs IntRange

FromJSONWithErrs RegularExpression

FromJSONWithErrs Filter

FromJSONWithErrs SpecNewtype

FromJSONWithErrs Spec

FromJSONWithErrs APINode

FromJSONWithErrs a => FromJSONWithErrs [a]

FromJSONWithErrs a => FromJSONWithErrs (Maybe a)

fromJSONWithErrs :: FromJSONWithErrs a => Value -> Either [(JSONError, Position)] a

Run the JSON parser on a value to produce a result or a list of errors with their positions. This should not be used inside an implementation of parseJSONWithErrs as it will not pass on the current position.

fromJSONWithErrs' :: FromJSONWithErrs a => ParseFlags -> Value -> Either [(JSONError, Position)] a

Run the JSON parser on a value to produce a result or a list of errors with their positions. This version allows the ParseFlags to be specified.

decodeWithErrs :: FromJSONWithErrs a => ByteString -> Either [(JSONError, Position)] a

Decode a ByteString and run the JSON parser

decodeWithErrs' :: FromJSONWithErrs a => ParseFlags -> ByteString -> Either [(JSONError, Position)] a

Decode a ByteString and run the JSON parser, allowing the ParseFlags to be specified

ParserWithErrs combinators

withParseFlags :: (ParseFlags -> ParserWithErrs a) -> ParserWithErrs a

failWith :: JSONError -> ParserWithErrs a

expectedArray :: Value -> JSONError

expectedBool :: Value -> JSONError

expectedInt :: Value -> JSONError

expectedObject :: Value -> JSONError

expectedString :: Value -> JSONError

badFormat :: String -> Text -> JSONError

withInt :: String -> (Int -> ParserWithErrs a) -> Value -> ParserWithErrs a

withNum :: Num n => String -> (n -> ParserWithErrs a) -> Value -> ParserWithErrs a

withIntRange :: IntRange -> String -> (Int -> ParserWithErrs a) -> Value -> ParserWithErrs a

withBinary :: String -> (Binary -> ParserWithErrs a) -> Value -> ParserWithErrs a

withBool :: String -> (Bool -> ParserWithErrs a) -> Value -> ParserWithErrs a

withText :: String -> (Text -> ParserWithErrs a) -> Value -> ParserWithErrs a

withRegEx :: RegEx -> String -> (Text -> ParserWithErrs a) -> Value -> ParserWithErrs a

withUTC :: String -> (UTCTime -> ParserWithErrs a) -> Value -> ParserWithErrs a

withUTCRange :: UTCRange -> String -> (UTCTime -> ParserWithErrs a) -> Value -> ParserWithErrs a

withVersion :: String -> (Version -> ParserWithErrs a) -> Value -> ParserWithErrs a

withField :: Text -> (Value -> ParserWithErrs a) -> Object -> ParserWithErrs a

Look up the value of a field, treating missing fields as null

withDefaultField :: Bool -> Maybe Value -> Text -> (Value -> ParserWithErrs a) -> Object -> ParserWithErrs a

Look up the value of a field, which may be read-only or use a default value (depending on the ParseFlags).

(.:.) :: FromJSONWithErrs a => Object -> Text -> ParserWithErrs a

Parse the value of a field, treating missing fields as null

(.::) :: FromJSONWithErrs a => Object -> Text -> ParserWithErrs a

Parse the value of a field, failing on missing fields

withUnion :: [(Text, Value -> ParserWithErrs a)] -> Value -> ParserWithErrs a

Match an inhabitant of a disjoint union, which should be an object with a single field, and call the continuation corresponding to the field name.