-- 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.7
-- | XML back and forth!
--
-- xmlbf provides high-level tools for encoding and decoding
-- XML.
--
-- xmlbf provides tools like dfpos and dfposM for
-- finding a fixpoint of an XML fragment.
--
-- xmlbf provides FromXml and ToXml typeclasses
-- intended to be used as the familiar FromJSON and ToXml
-- from the aeson package.
--
-- xmlbf doesn't do any parsing of raw XML on its own. Instead,
-- one should use xmlbf together with libraries like
-- xmlbf-xeno or xmlbf-xmlhtml for this.
module Xmlbf
-- | Pure version of parseM.
parse :: Parser a -> [Node] -> Either String a
-- | Run a ParserT on an XML fragment body.
--
-- Notice that this function doesn't enforce that all input is consumed.
-- If you want that behavior, then please use pEndOfInput in the
-- given ParserT.
parseM :: Applicative m => ParserT m a -> [Node] -> m (Either String a)
-- | Parser a is a type synonym for Parser
-- Identity a.
type Parser = ParserT Identity :: Type -> Type
-- | XML parser for a value of type a.
--
-- This parser runs on top of some Monad m, making
-- ParserT a suitable monad transformer.
--
-- You can build a ParserT using pElement,
-- pAnyElement, pName, pAttr, pAttrs,
-- pChildren, pText, pEndOfInput, any of the
-- Applicative, Alternative or Monad combinators, or
-- you can use parserT directly.
--
-- Run a ParserT using parse, parseM or
-- runParserT
data ParserT (m :: Type -> Type) (a :: Type)
-- | parserT is the most general way or building a ParserT.
--
-- Notice that ParserState's internals are not exported, so you
-- won't be able to do much with it other than pass it around.
--
--
-- runParserT . parserT == id
--
parserT :: (ParserState -> m (ParserState, Either String a)) -> ParserT m a
-- | runParserT is the most general way or running a ParserT.
--
-- As a simpler alternative to runParserT, consider using
-- parseM, or even parse if you don't need transformer
-- functionality.
--
-- Notice that ParserState's internals are not exported, so you
-- won't be able to do much with it other than pass it around.
--
--
-- runParserT . parserT == id
--
runParserT :: ParserT m a -> ParserState -> m (ParserState, Either String a)
-- | Internal parser state.
data ParserState
-- | Construct an initial ParserState to use with runParserT
-- from zero or more top-level Nodes.
initialParserState :: [Node] -> ParserState
-- | pElement "foo" p runs a ParserT p
-- inside a Element node named "foo". This parser
-- 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 pText before using
-- pElement.
--
-- Consumes the matched element from the parser state.
pElement :: Monad m => Text -> ParserT m a -> ParserT m a
-- | pAnyElement p runs a ParserT p inside
-- the Element node at the current position, if any. Otherwise, if
-- no such element exists, this parser fails.
--
-- You can recover the name of the matched element using pName
-- inside the given ParserT. However, if you already know
-- beforehand the name of the element that you want to match, it's better
-- to use pElement rather than pAnyElement.
--
-- Leading whitespace is ignored. If you need to preserve that whitespace
-- for some reason, capture it using pText before using
-- pAnyElement.
--
-- Consumes the matched element from the parser state.
pAnyElement :: Monad m => ParserT m a -> ParserT m a
-- | Returns the name of the currently selected Element.
--
-- This parser fails if there's no currently selected
-- Element (see pElement, pAnyElement).
--
-- Doesn't modify the parser state.
pName :: Applicative m => ParserT m Text
-- | Return the value of the requested attribute, if defined, as strict
-- Text. Returns an empty strict Text in case the
-- attribute is defined but no value was given to it.
--
-- This parser fails if there's no currently selected
-- Element (see pElement, pAnyElement).
--
-- Consumes the matched attribute from the parser state.
pAttr :: Applicative m => Text -> ParserT m Text
-- | Returns all of the available element attributes.
--
-- Returns empty strict Text as values in case an attribute
-- is defined but no value was given to it.
--
-- This parser fails if there's no currently selected
-- Element (see pElement, pAnyElement).
--
-- Consumes all the attributes for this element from the parser
-- state.
pAttrs :: Applicative m => ParserT m (HashMap Text Text)
-- | Returns all of the immediate children of the current element.
--
-- If parsing top-level nodes rather than a particular element (that is,
-- if pChildren is not being run inside pElement),
-- then all of the top level Nodes will be returned.
--
-- Consumes all the returned nodes from the parser state.
pChildren :: Applicative m => ParserT m [Node]
-- | Returns the contents of a text node as a strict Text.
--
-- Surrounidng whitespace is not removed, as it is considered to be part
-- of the text node.
--
-- If there is no text node at the current position, then this parser
-- fails. This implies that pText never returns an
-- empty strict Text, since there is no such thing as a text node
-- without text.
--
-- Please note that consecutive text nodes are always concatenated and
-- returned together.
--
--
-- parse pText (text "Ha" <> text "sk" <> text "ell")
-- == Right (text Haskell)
--
--
-- Consumes the text from the parser state. This implies that if
-- you perform two consecutive pText calls, the second will always
-- fail.
--
--
-- parse (pText >> pText) (text "Ha" <> text "sk" <> text "ell")
-- == Left "Missing text node"
--
pText :: Applicative m => ParserT m Text
-- | Like pText, but returns a lazy Text.
pTextLazy :: Applicative m => ParserT m Text
-- | Succeeds if all of the elements, attributes and text nodes have been
-- consumed.
pEndOfInput :: Applicative m => ParserT m ()
-- | Encodes a list of XML Nodes, representing an XML fragment body,
-- to an UTF8-encoded and XML-escaped bytestring.
--
-- This function doesn't render self-closing elements. Instead, all
-- elements have a corresponding closing tag.
--
-- Also, it doesn't render CDATA sections. Instead, all text is escaped
-- as necessary.
--
-- Element attributes are rendered in alphabetical order.
encode :: [Node] -> Builder
-- | Either a text or an element node in an XML fragment body.
--
-- Construct with text, textLazy or element.
--
-- Destruct with Text, TextLazy or Element.
data Node
-- | Case analysis for a Node.
node :: (Text -> HashMap Text Text -> [Node] -> a) -> (Text -> a) -> Node -> a
-- | Destruct an element Node.
--
--
-- case n :: Node of
-- Element t as cs -> ...
-- _ -> ...
--
pattern Element :: Text -> HashMap Text Text -> [Node] -> Node
-- | Construct a XML fragment body containing a single Element
-- Node, if possible.
--
-- This function will return empty list if it is not possible to
-- construct the Element with the given input. To learn more about
-- why it was not possible to construct it, use element
-- instead.
--
-- Using element' rather than element is recommended, so
-- that you are forced to acknowledge a failing situation in case it
-- happens. However, element is at times more convenient to use,
-- whenever you know the input is valid.
element :: Text -> HashMap Text Text -> [Node] -> [Node]
-- | Construct an Element Node.
--
-- Returns Left if the Element Node can't be
-- created, with an explanation of why.
element' :: Text -> HashMap Text Text -> [Node] -> Either String Node
-- | Destruct a text Node into a strict Text.
--
--
-- case n :: Node of
-- Text t -> ...
-- _ -> ...
--
pattern Text :: Text -> Node
-- | Construct a XML fragment body containing a single text Node, if
-- given Text not empty.
--
-- This function will return empty list if it is not possible to
-- construct the Text with the given input. To learn more about
-- why it was not possible to construct it, use text'
-- instead.
--
-- Using text' rather than text is recommended, so that you
-- are forced to acknowledge a failing situation in case it happens.
-- However, text is at times more convenient to use. For example,
-- when you know statically the input is valid.
text :: Text -> [Node]
-- | Construct a text Node, if given Text not empty.
--
-- Returns Left if the Text Node can't be created,
-- with an explanation of why.
text' :: Text -> Either String Node
-- | Destruct a text Node into a lazy Text.
--
--
-- case n :: Node of
-- TextLazy tl -> ...
-- _ -> ...
--
pattern TextLazy :: Text -> Node
-- | A version of text working with lazy Text.
textLazy :: Text -> [Node]
-- | A version of text' working with lazy Text.
textLazy' :: Text -> Either String 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 = dfpos $ \k -> \case
-- Element "w" as cs -> element "x" as cs >>= k
-- Element "x" as cs -> element "y" as cs
-- Element "y" as cs -> element "z" as cs >>= k
--
--
-- See dfpre for pre-orderd depth-first replacement.
--
-- WARNING If you call k in every branch, then
-- dfpos will never terminate. Make sure the recursion stops at
-- some point by simply returning a list of nodes instead of calling
-- k.
dfpos :: ((Node -> [Node]) -> Node -> [Node]) -> Node -> [Node]
-- | Monadic version of dfpos.
dfposM :: Monad m => ((Node -> m [Node]) -> Node -> m [Node]) -> Node -> m [Node]
-- | Pre-order depth-first replacement of Node and all of its
-- children.
--
-- This is just like dfpos but the search proceeds in a different
-- order.
dfpre :: ((Node -> [Node]) -> Node -> [Node]) -> Node -> [Node]
-- | Monadic version of dfpre.
dfpreM :: Monad m => ((Node -> m [Node]) -> Node -> m [Node]) -> Node -> m [Node]
class FromXml a
-- | Parses an XML fragment body into a value of type a.
--
-- If a ToXml instance for a exists, then:
--
--
-- parse fromXml (toXml a) == Right a
--
fromXml :: (FromXml a, Monad m) => ParserT m a
class ToXml a
-- | Renders a value of type a into an XML fragment body.
--
-- If a FromXml instance for a exists, then:
--
--
-- parse fromXml (toXml a) == Right a
--
toXml :: ToXml a => a -> [Node]
instance GHC.Classes.Eq Xmlbf.Node
instance GHC.Classes.Eq Xmlbf.ParserState
instance (GHC.Base.Monad m, GHC.Base.Semigroup a) => GHC.Base.Semigroup (Xmlbf.ParserT m a)
instance (GHC.Base.Monad m, GHC.Base.Monoid a) => GHC.Base.Monoid (Xmlbf.ParserT m a)
instance GHC.Base.Functor m => GHC.Base.Functor (Xmlbf.ParserT m)
instance GHC.Base.Monad m => GHC.Base.Applicative (Xmlbf.ParserT m)
instance GHC.Base.Monad m => GHC.Base.Alternative (Xmlbf.ParserT m)
instance GHC.Base.Monad m => Control.Selective.Selective (Xmlbf.ParserT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Xmlbf.ParserT m)
instance GHC.Base.Monad m => Control.Monad.Fail.MonadFail (Xmlbf.ParserT m)
instance GHC.Base.Monad m => GHC.Base.MonadPlus (Xmlbf.ParserT m)
instance Control.Monad.Fix.MonadFix m => Control.Monad.Fix.MonadFix (Xmlbf.ParserT m)
instance Control.Monad.Zip.MonadZip m => Control.Monad.Zip.MonadZip (Xmlbf.ParserT m)
instance Control.Monad.Trans.Class.MonadTrans Xmlbf.ParserT
instance Control.Monad.Morph.MFunctor Xmlbf.ParserT
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Xmlbf.ParserT m)
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Xmlbf.ParserT m)
instance Control.Monad.State.Class.MonadState s m => Control.Monad.State.Class.MonadState s (Xmlbf.ParserT m)
instance Control.Monad.Error.Class.MonadError e m => Control.Monad.Error.Class.MonadError e (Xmlbf.ParserT m)
instance Control.Monad.Catch.MonadThrow m => Control.Monad.Catch.MonadThrow (Xmlbf.ParserT m)
instance Control.Monad.Catch.MonadCatch m => Control.Monad.Catch.MonadCatch (Xmlbf.ParserT m)
instance Control.Monad.Catch.MonadMask m => Control.Monad.Catch.MonadMask (Xmlbf.ParserT m)
instance Control.DeepSeq.NFData Xmlbf.Node
instance GHC.Show.Show Xmlbf.Node