| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Data.Aeson.Commit
Description
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 Source #
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.
tryParser :: Parser a -> Commit a Source #
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 Source #
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.