-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Parse Aeson data with commitment
--   
--   Commitment mechanism for <tt>aeson</tt> parsers. Commitment means that
--   if some initial parsing succeeds, subsequent failures are
--   unrecoverable.
@package aeson-commit
@version 1.4


-- | Commit mechanism for aeson's <a>Parser</a>. To commit means that if
--   some initial parsing succeeds, subsequent failures are unrecoverable.
--   
--   In the following example, we use <a>.:&gt;</a> to look for a key
--   <tt>.nested.value</tt>, and if that does not exist, <tt>.value</tt>.
--   
--   <pre>
--   parse o = (o .:&gt; "nested") (withObject "nestedObj" (.: "value"))
--           &lt;|&gt; tryParser (o .: "value")
--   </pre>
--   
--   Not having the key <tt>nested</tt> is a normal, recoverable failure,
--   and parsing will continue looking for <tt>value</tt>. However, if
--   <tt>nested</tt> is present but malformed, parsing fails.
--   
--   <pre>
--   { value: "foo", otherField: "bar" }
--   -&gt; Right "foo"
--   
--   { value: "foo", nested: { value: "bar" } }
--   -&gt; Right "bar"
--   
--   { value: "foo", nested: { bar: 9 } }
--   -&gt; Left "Error in $.nested: key \"value\" not found"
--   
--   { value: "foo", nested: 9 }
--   -&gt; Left "Error in $.nested: parsing nestedObj failed, expected Object, but encountered Number"
--   
--   {}
--   -&gt; Left
--     "Error in $: No match,
--      - key \"value\" not found"
--      - key \"nested\" not found"
--   </pre>
module Data.Aeson.Commit

-- | Construct a commit. If the first parser fails, the failure is
--   recoverable through <a>Alternative</a>. If the first parser succeeds,
--   the <a>Commit</a> is a success, and any failures in the inner action
--   will be preserved.
commit :: Parser a -> (a -> Parser b) -> Commit b

-- | Run a <a>Commit</a>, capturing its result in a <a>Parser</a>.
runCommit :: Commit a -> Parser a

-- | Convenience wrapper around <a>commit</a> 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
--   <a>&lt;?&gt;</a>, which will give nicer error messages.
(.:>) :: FromJSON a => Object -> Key -> (a -> Parser b) -> Commit b

-- | Turn a <a>Parser</a> into a <a>Commit</a> Unlike <a>liftParser</a>,
--   the parser's failure is recoverable.
--   
--   <pre>
--   tryParser empty &lt;|&gt; p = p
--   tryParser p = commit p pure
--   </pre>
tryParser :: Parser a -> Commit a

-- | Turn a <a>Parser</a> into a <a>Commit</a>. Unlike <a>tryParser</a>,
--   the parser's failure is _not_ recoverable, i.e. the parse is always
--   committed.
--   
--   <pre>
--   liftParser empty &lt;|&gt; p = empty
--   liftParser p = commit (pure ()) (const p)
--   </pre>
liftParser :: Parser a -> Commit a

-- | A <a>Commit</a> is a <a>Parser</a> that has two failure modes;
--   recoverable and non-recoverable.
--   
--   <pre>
--   tryParser empty &lt;|&gt; p = p
--   liftParser empty &lt;|&gt; p = empty
--   </pre>
--   
--   <a>Commit</a> is typically constructed using <a>commit</a>, and
--   consumed using <a>runCommit</a>, which captures its result in a
--   <a>Parser</a>.
--   
--   The implementation works by wrapping <a>Parser</a> in an
--   <a>ExceptT</a>. The derived <a>Alternative</a> instance will then only
--   recover from failures in the <a>ExceptT</a>. This means that as soon
--   as we successfully construct a <a>Right</a> value, the
--   <a>Alternative</a> considers the <a>Commit</a> a success, even though
--   the underlying parser might have failed. The <a>Void</a> represents
--   the guarantee that we only collect error values.
newtype Commit a
Commit :: ExceptT [Parser Void] Parser a -> Commit a
[unCommit] :: Commit a -> ExceptT [Parser Void] Parser a
instance GHC.Base.Alternative Data.Aeson.Commit.Commit
instance GHC.Base.Applicative Data.Aeson.Commit.Commit
instance GHC.Base.Functor Data.Aeson.Commit.Commit
instance GHC.Base.Monad Data.Aeson.Commit.Commit