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


-- | XML back and forth! Parser, renderer, ToXml, FromXml, fixpoints.
--   
--   XML back and forth! Parser, renderer, ToXml, FromXml, fixpoints.
@package xmlbf
@version 0.4.1


-- | XML back and forth!
--   
--   <tt>xmlbf</tt> doesn't do any parsing of raw XML on its own. Instead,
--   one should rely on libraries like <a>xmlbf-xeno</a> or
--   <a>xmlbf-xmlhtml</a> for this.
--   
--   <tt>xmlbf</tt> provides a <a>FromXml</a> class intended to be used as
--   the familiar <a>FromJSON</a> from the <tt>aeson</tt> package. This
--   relies on the <a>Parser</a> type and the related tools.
--   
--   <tt>xmlbf</tt> provides a <a>ToXml</a> class intended to be used as
--   the familiar <a>toJSON</a> from the <tt>aeson</tt> package.
--   
--   <tt>xmlb</tt> provides tools like <a>dfpos</a> and <a>dfposM</a> for
--   finding a fixpoint of a XML structure.
module Xmlbf
class FromXml a

-- | Parses an XML fragment into a value of type <tt>a</tt>.
--   
--   If a <a>ToXml</a> instance for <tt>a</tt> exists, then:
--   
--   <pre>
--   <a>runParser</a> <a>fromXml</a> (<a>toXml</a> a) == <a>Right</a> a
--   </pre>
fromXml :: FromXml a => Parser a

-- | XML parser monad. To be run with <a>runParser</a>.
--   
--   You can build a <a>Parser</a> using <a>pElement</a>, <a>pAttr</a>,
--   <a>pAttrs</a>, <a>pText</a>, <a>pRead</a>, or any of the
--   <a>Applicative</a>, <a>Alternative</a> or <a>Monad</a> combinators.
data Parser a

-- | Run a parser on an XML fragment. If the parser fails, then a
--   <a>String</a> with an error message is returned.
--   
--   Notice that this function doesn't enforce that all input is consumed.
--   If you want that behavior, then please use <a>pEndOfInput</a> in the
--   given <a>Parser</a>.
runParser :: Parser a -> [Node] -> Either String a

-- | <tt><a>pElement</a> "foo" p</tt> runs a <a>Parser</a> <tt>p</tt>
--   inside a element node named <tt>"foo"</tt>. This fails if such element
--   does not exist at the current position.
--   
--   Leading whitespace is ignored. If you need to preserve that whitespace
--   for some reason, capture it using <a>pText</a> before using
--   <a>pElement</a>.
--   
--   Consumes the element from the parser state.
pElement :: Text -> Parser a -> Parser a

-- | Return the value of the requested attribute, if defined. May return an
--   empty string in case the attribute is defined but no value was given
--   to it.
--   
--   Consumes the attribute from the parser state.
pAttr :: Text -> Parser Text

-- | Returns all of the available element attributes. May return empty
--   strings as values in case an attribute is defined but no value was
--   given to it.
--   
--   Consumes all of the remaining attributes for this element from the
--   parser state.
pAttrs :: Parser (HashMap Text Text)

-- | Return a text node value (including CDATA).
--   
--   Consumes the text node from the parser state. Surrounding whitespace
--   is not removed.
--   
--   Law: When two consecutive calls to <a>pText</a> are made, the first
--   call returns all of the available consecutive text, and the second
--   call always fails.
pText :: Parser Text

-- | A version of <a>read</a> (from <a>Prelude</a>) that can fail in the
--   <a>Parser</a> monad (or any other <a>MonadFail</a>).
--   
--   Note: In case it isn't obvious from the type signature, this function
--   doesn't touch the underlying <a>Parser</a> state at all.
pRead :: (Typeable a, Read a, MonadFail m) => Text -> m a

-- | Succeeds if all of the elements, attributes and text nodes have been
--   consumed.
pEndOfInput :: Parser ()
class ToXml a

-- | Renders a value of type <tt>a</tt> into an XML fragment.
--   
--   If a <a>FromXml</a> instance for <tt>a</tt> exists, then:
--   
--   <pre>
--   <a>runParser</a> <a>fromXml</a> (<a>toXml</a> a) == <a>Right</a> a
--   </pre>
toXml :: ToXml a => a -> [Node]

-- | Encodes a list of XML <a>Node</a>s to an UTF8-encoded and XML-escaped
--   bytestring.
encode :: [Node] -> Builder

-- | Either a text or an element node in an XML fragment.
--   
--   Construct with <a>text</a> or <a>element</a>. Destruct with
--   <a>Text</a> or <a>Element</a>.
data Node

-- | Destruct an element <a>Node</a>.
pattern Element :: Text -> HashMap Text Text -> [Node] -> Node

-- | Construct an element <a>Node</a>.
element :: Text -> HashMap Text Text -> [Node] -> Either String Node

-- | Unsafe version of <a>element</a>, causing a runtime <a>error</a> in
--   situations where <a>element</a> would return <a>Left</a>. So, don't
--   use this unless you know what you are doing.
element' :: Text -> HashMap Text Text -> [Node] -> Node

-- | Destruct a text <a>Node</a>.
pattern Text :: Text -> Node

-- | Construct a text <a>Node</a>.
text :: Text -> Node

-- | Post-order depth-first replacement of <a>Node</a> and all of its
--   children.
--   
--   This function works like <a>fix</a>, but the given function is trying
--   to find a fixpoint for the individual children nodes, not for the root
--   node.
--   
--   For example, the following function renames every node named
--   <tt>"w"</tt> to <tt>"y"</tt>, and every node named <tt>"y"</tt> to
--   <tt>"z"</tt>. It accomplishes this by first renaming <tt>"w"</tt>
--   nodes to <tt>"x"</tt>, and then, by using <tt>k</tt> recursively to
--   further rename all <tt>"x"</tt> nodes (including the ones that were
--   just created) to <tt>"y"</tt> in a post-order depth-first manner.
--   After renaming an <tt>"x"</tt> node to <tt>"y"</tt>, the recursion
--   stops (i.e., <tt>k</tt> is not used), so our new <tt>"y"</tt> nodes
--   won't be further renamed to <tt>"z"</tt>. However, nodes that were
--   named <tt>"y"</tt> initially will be renamed to <tt>"z"</tt>.
--   
--   In our example we only replace one node with another, but a node can
--   be replaced with zero or more nodes, depending on the length of the
--   resulting list.
--   
--   <pre>
--   foo :: <a>Node</a> -&gt; [<a>Node</a>]
--   foo = <a>dfpos</a> $ \k -&gt; \case
--       <a>Element</a> "w" as cs -&gt; k (<a>element'</a> "x" as cs)
--       <a>Element</a> "x" as cs -&gt; [<a>element'</a> "y" as cs]
--       <a>Element</a> "y" as cs -&gt; k (<a>element'</a> "z" as cs)
--   </pre>
--   
--   See <a>dfpre</a> for pre-orderd depth-first replacement.
--   
--   <i>WARNING</i> If you call <tt>k</tt> in every branch, then
--   <a>dfpos</a> will never terminate. Make sure the recursion stops at
--   some point by simply returning a list of nodes instead of calling
--   <tt>k</tt>.
dfpos :: ((Node -> [Node]) -> Node -> [Node]) -> Node -> [Node]

-- | Monadic version of <a>dfpos</a>.
dfposM :: Monad m => ((Node -> m [Node]) -> Node -> m [Node]) -> Node -> m [Node]

-- | Pre-order depth-first replacement of <a>Node</a> and all of its
--   children.
--   
--   This is just like <a>dfpos</a> but the search proceeds in a different
--   order.
dfpre :: ((Node -> [Node]) -> Node -> [Node]) -> Node -> [Node]

-- | Monadic version of <a>dfpre</a>.
dfpreM :: Monad m => ((Node -> m [Node]) -> Node -> m [Node]) -> Node -> m [Node]
instance GHC.Base.Functor Xmlbf.Parser
instance GHC.Show.Show Xmlbf.S
instance GHC.Classes.Eq Xmlbf.Node
instance GHC.Base.Applicative Xmlbf.Parser
instance GHC.Base.Monad Xmlbf.Parser
instance Control.Monad.Fail.MonadFail Xmlbf.Parser
instance GHC.Base.Alternative Xmlbf.Parser
instance GHC.Base.MonadPlus Xmlbf.Parser
instance GHC.Show.Show Xmlbf.Node
instance Data.String.IsString Xmlbf.Node
