api-tools-0.2: DSL for generating API boilerplate and docs

Safe HaskellNone




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 Expected Source

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

data FormatExpected Source

Special format expected of a string



type Position = [Step] Source

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

data Step Source

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


InField Text 
InElem Int 

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

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

prettyJSONError :: JSONError -> String Source

Human-readable description of a JSON parse error

prettyStep :: Step -> String Source

Human-readable description of a single step in a position

Parser with multiple error support

data ParserWithErrs a Source

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

FromJSON class with multiple error support

class FromJSONWithErrs a where Source

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.

Minimal complete definition



parseJSONWithErrs :: Value -> ParserWithErrs a Source

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.

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

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.

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

Decode a ByteString and run the JSON parser

ParserWithErrs combinators

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

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

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

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

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

Parse the value of a field, failing on missing fields