Data.Aeson.Commit

Commit mechanism for aeson's Parser. To commit means that if some initial parsing succeeds, subsequent failures are unrecoverable.

In the following example, we use .:> to look for a key .nested.value, and if that does not exist, .value.

parse o = (o .:> "nested") (withObject "nestedObj" (.: "value"))
        <|> tryParser (o .: "value")

Not having the key nested is a normal, recoverable failure, and parsing will continue looking for value. However, if nested is present but malformed, parsing fails.

{ 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 -> Key -> (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 Commit is a Parser that has two failure modes; recoverable and non-recoverable.

tryParser empty <|> p = p
liftParser empty <|> p = empty

Commit is typically constructed using commit, and consumed using runCommit, which captures its result in a Parser.

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]