Data.Aeson.Commit

Commitment mechanism for aeson Parser. Commitment means that if some initial parsing succeeds, subsequent failures are unrecoverable. In this example, not having the key nested is a normal, recoverable failure, and parsing will continue looking for another key. However, if nested is present but malformed, the entire parser fails.

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"

Documentation

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

Construct a commit. If the first parser fails, the failure is recoverable through Alternative. 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

Run a Commit, capturing its result in a Parser.

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

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

Turn a Parser into a Commit Unlike liftParser, the parser's failure is recoverable.

tryParser empty <|> p = p
tryParser p = commit p pure

liftParser :: Parser a -> Commit a

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
liftParser p = commit (pure ()) (const p)

newtype Commit a

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 run a Commit and capture its result in a Parser using runCommit. As an additional benefit, it will contain error info for all attempted parsing branches.

The implementation works by wrapping Parser in an ExceptT. The derived Alternative instance will then 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

Fields

• unCommit :: ExceptT [Parser Void] Parser a

Instances

Monad Commit

Defined in Data.Aeson.Commit

Methods

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

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

return :: a -> Commit a

Functor Commit

Defined in Data.Aeson.Commit

Methods

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

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

Applicative Commit

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

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]