aeson-commit-1.1: Parse Aeson data with commitment

Safe HaskellNone
LanguageHaskell2010

Data.Aeson.Commit

Description

Commitment mechanism for aeson parsers. This is comes up when you e.g. want to make a distinction between missing keys and malformed keys. As an example, this parser will look for a key "nested", and if present try to read the embedded "value", or alternatively look for a top level "value":

parse o = (o .:> "nested") (withObject "nestedObj" (.: "value"))
      <|> tryParser (o .: "value")
{ value: "foo", otherField: "bar" }
-> Right "foo"

{ value: "foo", nested: { value: "bar" } }
-> Right "bar"

{ value: "foo", nested: { bar: 9 } }
-> Left "Error in $.nested: key \"value\" not found"

{ value: "foo", nested: 9 }
-> Left "Error in $.nested: parsing nestedObj failed, expected Object, but encountered Number"

{}
-> Left
  "Error in $: No match,
   - key \"value\" not found"
   - key \"nested\" not found"
Synopsis

Documentation

newtype Commit a Source #

A Parser that has _two_ failure modes; recoverable and non-recoverable. The default, recoverable failure is the equivalent to aeson's default Parser behavior. The non-recoverable failure mode is used to commit to a branch; to commit means that every subsequent failure is non-recoverable.

You turn a commit back into a normal Parser using runCommit. As an additional benefit, if no commit succeeded the parser error message will contain all encountered errors.

The implementation works by capturing failure in either the ExceptT or in the underlying Parser. The derived Alternative instance will only recover from failures in the ExceptT. This means that as soon as we successfully construct a Right value, the Alternative considers the Commit a success, even though the underlying parser might have failed. The Void represents the guarantee that we only collect error values.

Constructors

Commit 
Instances
Monad Commit Source # 
Instance details

Defined in Data.Aeson.Commit

Methods

(>>=) :: Commit a -> (a -> Commit b) -> Commit b #

(>>) :: Commit a -> Commit b -> Commit b #

return :: a -> Commit a #

fail :: String -> Commit a #

Functor Commit Source # 
Instance details

Defined in Data.Aeson.Commit

Methods

fmap :: (a -> b) -> Commit a -> Commit b #

(<$) :: a -> Commit b -> Commit a #

Applicative Commit Source # 
Instance details

Defined in Data.Aeson.Commit

Methods

pure :: a -> Commit a #

(<*>) :: Commit (a -> b) -> Commit a -> Commit b #

liftA2 :: (a -> b -> c) -> Commit a -> Commit b -> Commit c #

(*>) :: Commit a -> Commit b -> Commit b #

(<*) :: Commit a -> Commit b -> Commit a #

Alternative Commit Source # 
Instance details

Defined in Data.Aeson.Commit

Methods

empty :: Commit a #

(<|>) :: Commit a -> Commit a -> Commit a #

some :: Commit a -> Commit [a] #

many :: Commit a -> Commit [a] #

commit :: Parser a -> (a -> Parser b) -> Commit b Source #

Construct a commit. If the first parser succeeds, the Commit is a success, and any failures in the inner action will be preserved.

runCommit :: Commit a -> Parser a Source #

Recommended way of turning a Commit back into a regular Parser.

(.:>) :: FromJSON a => Object -> Text -> (a -> Parser b) -> Commit b Source #

Convenience wrapper around commit for when the commit is checking whether a key is present in some object. If it is, it will commit and append the key to the JSONPath of the inner context through <?>, which will give nicer error messages.

tryParser :: Parser a -> Commit a Source #

Try to parse with a Parser and commit if it parses successfully. Unlike liftParser, the parser's failure is recoverable.

tryParser empty <|> p = p

liftParser :: Parser a -> Commit a Source #

Turn a Parser into a Commit. Unlike tryParser, the parser's failure is _not_ recoverable, i.e. the parse is always committed.

liftParser empty <|> p = empty