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


-- | Parse Aeson data with commitment
--   
--   Aeson parsers backtracks too much for some use cases. The commit
--   parser forbids backtracking for already committed parses.
@package aeson-commit
@version 1.1


-- | 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 <tt>"nested"</tt>, and if
--   present try to read the embedded <tt>"value"</tt>, or alternatively
--   look for a top level <tt>"value"</tt>:
--   
--   <pre>
--   parse o = (o .:&gt; "nested") (withObject "nestedObj" (.: "value"))
--         &lt;|&gt; tryParser (o .: "value")
--   </pre>
--   
--   <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

-- | A <a>Parser</a> that has _two_ failure modes; recoverable and
--   non-recoverable. The default, recoverable failure is the equivalent to
--   aeson's default <a>Parser</a> 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 <a>Parser</a> using
--   <a>runCommit</a>. 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
--   <a>ExceptT</a> or in the underlying <a>Parser</a>. The derived
--   <a>Alternative</a> instance will 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

-- | Construct a commit. 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

-- | Recommended way of turning a <a>Commit</a> back into a regular
--   <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 -> Text -> (a -> Parser b) -> Commit b

-- | Try to parse with a <a>Parser</a> and commit if it parses
--   successfully. Unlike <a>liftParser</a>, the parser's failure is
--   recoverable.
--   
--   <pre>
--   tryParser empty &lt;|&gt; p = p
--   </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
--   </pre>
liftParser :: Parser a -> Commit 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