-- 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.2
-- | XML back and forth!
--
-- xmlbf doesn't do any parsing of raw XML on its own. Instead,
-- one should rely on libraries like xmlbf-xeno or
-- xmlbf-xmlhtml for this.
--
-- xmlbf provides a FromXml class intended to be used as
-- the familiar FromJSON from the aeson package. This
-- relies on the Parser type and the related tools.
--
-- xmlbf provides a ToXml class intended to be used as
-- the familiar toJSON from the aeson package.
--
-- xmlb provides tools like df and dfM for finding
-- a fixpoint of a XML structure.
module Xmlbf
class FromXml a
-- | Parses an XML fragment into a value of type a.
--
-- If a ToXml instance for a exists, then:
--
--
-- runParser fromXml (toXml a) == Right a
--
fromXml :: FromXml a => Parser a
-- | XML parser monad. To be run with runParser.
--
-- You can build a Parser using element, pAttr,
-- pAttrs, pText, pRead, or any of the
-- Applicative, Alternative or Monad combinators.
data Parser a
-- | Run a parser on an XML fragment. If the parser fails, then a
-- String with an error message is returned.
runParser :: Parser a -> [Node] -> Either String a
-- | pElement "foo" p runs a Parser p
-- inside a element node named "foo". This fails if such element
-- does not exist at the current position.
--
-- 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.
--
-- Law: When two consecutive calls to pText are made, the first
-- call returns all of the available consecutive text, and the second
-- call always fails.
pText :: Parser Text
-- | Parses a value that can be read.
--
-- Consumes the raw string from the parser state.
pRead :: (Typeable a, Read a) => Text -> Parser a
-- | Succeeds if all of the elements, attributes and text nodes have been
-- consumed.
pEndOfInput :: Parser ()
class ToXml a
-- | Renders a value of type a into an XML fragment.
--
-- If a FromXml instance for a exists, then:
--
--
-- runParser fromXml (toXml a) == Right a
--
toXml :: ToXml a => a -> [Node]
-- | Encodes a list of XML Nodes to an UTF8-encoded and XML-escaped
-- bytestring.
encode :: [Node] -> Builder
-- | Either a text or an element node in an XML fragment.
--
-- Construct with text or element. Destruct with
-- Text or Element.
data Node
-- | Destruct an element Node.
-- | Construct an element Node.
element :: Text -> HashMap Text Text -> [Node] -> Either String Node
-- | Destruct a text Node.
-- | Construct a text Node.
text :: Text -> Node
-- | Post-order depth-first replacement of Node and all of its
-- children.
--
-- This function works like fix, 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
-- "w" to "y", and every node named "y" to
-- "z". It accomplishes this by first renaming "w"
-- nodes to "x", and then, by using k recursively to
-- further rename all "x" nodes (including the ones that were
-- just created) to "y" in a post-order depth-first manner.
-- After renaming an "x" node to "y", the recursion
-- stops (i.e., k is not used), so our new "y" nodes
-- won't be further renamed to "z". However, nodes that were
-- named "y" initially will be renamed to "z".
--
-- 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.
--
--
-- foo :: Node -> [Node]
-- foo = df $ \k -> \case
-- Element "w" as cs -> let Right e = element "x" as cs in k e
-- Element "x" as cs -> let Right e = element "y" as cs in [e]
-- Element "y" as cs -> let Right e = element "z" as cs in k e
--
--
-- WARNING If you call k in every branch, then df
-- will never terminate. Make sure the recursion stops at some point by
-- simply returning a list of nodes instead of calling k.
df :: ((Node -> [Node]) -> Node -> [Node]) -> Node -> [Node]
-- | Monadic version of df.
dfM :: Monad m => ((Node -> m [Node]) -> Node -> m [Node]) -> Node -> m [Node]
instance GHC.Base.Functor Xmlbf.Parser
instance GHC.Show.Show Xmlbf.Node
instance GHC.Classes.Eq Xmlbf.Node
instance Data.String.IsString 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