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


-- | Efficient and simple HTML/XML parsing library
--   
--   <i>taggy</i> is a simple package for parsing HTML (and should work
--   with XML) written on top of the <a>attoparsec</a> library, which makes
--   it one of the most efficient (space and time consumption wise) on
--   hackage.
--   
--   This is the root module of <i>taggy</i>. It reexports everything from
--   the package. See each module's docs for details about the functions
--   and types involved in <i>taggy</i>.
--   
--   While we've been testing the parser on <i>many</i> pages, it may still
--   be a bit rough around the edges. Let us know on <a>github</a> if you
--   have any problem.
--   
--   If you like to look at your HTML through various optical instruments,
--   feel free to take a look at the companion <a>taggy-lens</a> package
--   we've put up together. It makes HTML parsing a piece of cake.
--   
--   If you want to parse a document as list of tags and go through it as
--   some kind of stream by just picking what you need, head to
--   <a>Text.Taggy.Parser</a> and take a look at
--   <a>Text.Taggy.Parser.taggyWith</a> and <a>Text.Taggy.Parser.run</a>.
--   
--   If you want to parse the document as a DOM tree and traverse it to
--   find the information you need, use <a>Text.Taggy.DOM.parseDOM</a>.
--   This is especially useful when used in conjunction with
--   <a>taggy-lens</a>.
--   
--   If you build some HTML manually or just transform some existing DOM
--   tree and want to turn it into a <a>Data.Text.Lazy.Text</a> head to
--   <a>Text.Taggy.Renderer</a> and look at
--   <a>Text.Taggy.Renderer.render</a>.
@package taggy
@version 0.2.0


-- | Core types of <i>taggy</i>.
module Text.Taggy.Types

-- | A <a>Tag</a> can be one of the following types of tags:
--   
--   <ul>
--   <li>an opening tag that has a name, a list of attributes, and whether
--   it is a self-closing tag or not</li>
--   <li>a closing tag with the name of the tag</li>
--   <li>some raw <a>Text</a></li>
--   <li>an HTML comment tag</li>
--   <li>a <tt><a>script</a>...<a>/script</a></tt> tag</li>
--   <li>a <tt><a>style</a>...<a>/style</a></tt> tag</li>
--   </ul>
--   
--   The latter two are useful to be considered separately in the parser
--   and also lets you collect these bits quite easily.
data Tag
TagOpen :: !Text -> [Attribute] -> !Bool -> Tag
TagClose :: !Text -> Tag
TagText :: !Text -> Tag
TagComment :: !Text -> Tag
TagScript :: !Tag -> !Text -> !Tag -> Tag
TagStyle :: !Tag -> !Text -> !Tag -> Tag

-- | Name of a <a>Tag</a>.
--   
--   <pre>
--   tname (TagClose "a") == "a"
--   </pre>
tname :: Tag -> Text

-- | Is this <a>Tag</a> an opening tag?
isTagOpen :: Tag -> Bool

-- | Is this <a>Tag</a> a closing tag?
isTagClose :: Tag -> Bool

-- | Is this <a>Tag</a> just some flat text?
isTagText :: Tag -> Bool

-- | Is this <a>Tag</a> an HTML comment tag?
isTagComment :: Tag -> Bool

-- | Is this <a>Tag</a> a <tt><a>script</a>...<a>/script</a></tt> tag?
isTagScript :: Tag -> Bool

-- | Is this <a>Tag</a> a <tt><a>style</a>...<a>/style</a></tt> tag?
isTagStyle :: Tag -> Bool

-- | Get all the (opening) tags with the given name
tagsNamed :: Text -> [Tag] -> [Tag]

-- | An attribute is just an attribute name and an attribute value.
data Attribute
Attribute :: !Text -> !Text -> Attribute

-- | Get the attributes of a <a>Tag</a>.
attrs :: Tag -> [Attribute]

-- | Get the name of an <a>Attribute</a>.
attrKey :: Attribute -> Text

-- | Get the value of an <a>Attribute</a>.
attrValue :: Attribute -> Text
data L a
emptyL :: L a
appL :: L a -> L a -> L a
insertL :: a -> L a -> L a
singletonL :: a -> L a
toListL :: L a -> [a]
instance GHC.Classes.Eq Text.Taggy.Types.Tag
instance GHC.Show.Show Text.Taggy.Types.Tag
instance GHC.Classes.Eq Text.Taggy.Types.Attribute
instance GHC.Show.Show Text.Taggy.Types.Attribute

module Text.Taggy.Entities

-- | Convert all the (currently supported) HTML entities to their
--   corresponding unicode characters.
convertEntities :: Text -> Text


-- | Parse an HTML or XML document as a list of <a>Tag</a>s with
--   <a>taggyWith</a> or <a>run</a>.
module Text.Taggy.Parser

-- | Get a list of tags from an HTML document represented as a <a>Text</a>
--   value.
--   
--   The <a>Bool</a> lets you specify whether you want to convert HTML
--   entities to their corresponding unicode character. (<a>True</a> means
--   "yes convert")
taggyWith :: Bool -> Text -> [Tag]

-- | Same as <a>taggyWith</a> but hands you back a <a>Result</a> from
--   <tt>attoparsec</tt>
run :: Bool -> Text -> Result [Tag]
tagopen :: Bool -> Parser Tag
tagclose :: Parser Tag
tagcomment :: Parser Tag
tagstyle :: Bool -> Parser Tag
tagscript :: Bool -> Parser Tag
tagtext :: Bool -> Parser Tag
htmlWith :: Bool -> Parser [Tag]


-- | This module will help you represent an HTML or XML document as a tree
--   and let you traverse it in whatever way you like.
--   
--   This is especially useful when used in conjunction with
--   <a>taggy-lens</a>
module Text.Taggy.DOM

-- | An attribute name is just a <a>Text</a> value
type AttrName = Text

-- | An attribute value is just a <a>Text</a> value
type AttrValue = Text

-- | An <a>Element</a> here refers to a tag name, the attributes specified
--   withing that tag, and all the children nodes of that element. An
--   <a>Element</a> is basically anything but "raw" content.
data Element
Element :: !Text -> !(HashMap AttrName AttrValue) -> [Node] -> Element

-- | name of the element. e.g "a" for <a>a</a>
[eltName] :: Element -> !Text

-- | a (hash)map from attribute names to attribute values
[eltAttrs] :: Element -> !(HashMap AttrName AttrValue)

-- | children <a>Node</a>s
[eltChildren] :: Element -> [Node]

-- | A <a>Node</a> is either an <a>Element</a> or some raw text.
data Node
NodeElement :: Element -> Node
NodeContent :: Text -> Node

-- | Get the children of a node.
--   
--   If called on some raw text, this function returns <tt>[]</tt>.
nodeChildren :: Node -> [Node]

-- | Parse an HTML or XML document as a DOM tree.
--   
--   The <a>Bool</a> argument lets you specify whether you want to convert
--   HTML entities to their corresponding unicode characters, just like in
--   <a>Text.Taggy.Parser</a>.
--   
--   <pre>
--   parseDOM convertEntities = domify . taggyWith cventities
--   </pre>
parseDOM :: Bool -> Text -> [Node]

-- | Transform a list of tags (produced with <a>taggyWith</a>) into a list
--   of toplevel nodes. If the document you're working on is valid, there
--   should only be one toplevel node, but let's not assume we're living in
--   an ideal world.
domify :: [Tag] -> [Node]
untilClosed :: Text -> ([Node], [Tag]) -> ([Node], [Tag])
convertText :: Text -> Node
instance GHC.Show.Show Text.Taggy.DOM.Element
instance GHC.Classes.Eq Text.Taggy.DOM.Element
instance GHC.Show.Show Text.Taggy.DOM.Node
instance GHC.Classes.Eq Text.Taggy.DOM.Node


-- | Render a DOM tree (from <a>Text.Taggy.DOM</a>) using the excellent
--   blaze markup rendering library.
module Text.Taggy.Renderer
class AsMarkup a

-- | If the first parameter is true, we align the constructors for entity
--   conversion.
toMarkup :: AsMarkup a => Bool -> a -> Markup

-- | A <a>Node</a> is convertible to <a>Markup</a>

-- | An <a>Element</a> is convertible to <a>Markup</a>
class Renderable a where render = renderWith True
render :: Renderable a => a -> Text
renderWith :: Renderable a => Bool -> a -> Text

-- | Any value convertible to <a>Markup</a> can be rendered as HTML, by way
--   of <a>render</a> and <a>renderWith</a>.
toAttribute :: HashMap Text Text -> (Markup -> Markup)
toStatic :: Text -> StaticString
instance Text.Taggy.Renderer.AsMarkup Text.Taggy.DOM.Node
instance Text.Taggy.Renderer.AsMarkup Text.Taggy.DOM.Element
instance Text.Taggy.Renderer.AsMarkup a => Text.Taggy.Renderer.Renderable a


-- | <i>taggy</i> is a simple package for parsing HTML (and should work
--   with XML) written on top of the <a>attoparsec</a> library, which makes
--   it one of the most efficient (space and time consumption wise) on
--   hackage.
--   
--   This is the root module of <i>taggy</i>. It reexports everything from
--   the package. See each module's docs for details about the functions
--   and types involved in <i>taggy</i>.
--   
--   While we've been testing the parser on <i>many</i> pages, it may still
--   be a bit rough around the edges. Let us know on <a>github</a> if you
--   have any problem.
--   
--   If you like to look at your HTML through various optical instruments,
--   feel free to take a look at the companion <a>taggy-lens</a> package
--   we've put up together.
--   
--   <ul>
--   <li>If you want to parse a document as list of tags and go through it
--   as some kind of stream by just picking what you need, head to
--   <a>Text.Taggy.Parser</a> and take a look at <a>taggyWith</a> and
--   <a>run</a>.</li>
--   <li>If you want to parse the document as a DOM tree and traverse it to
--   find the information you need, use <a>parseDOM</a>. This is especially
--   useful when used in conjunction with <a>taggy-lens</a>.</li>
--   <li>If you build some HTML manually or just transform some existing
--   DOM tree and want to turn it into a <a>Text</a> head to
--   <a>Text.Taggy.Renderer</a> and look at <a>render</a>.</li>
--   </ul>
module Text.Taggy
