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


-- | A high level web scraping library for Haskell.
--   
--   Scalpel core provides a subset of the scalpel web scraping library
--   that is intended to have lightweight dependencies and to be free of
--   all non-Haskell dependencies.
@package scalpel-core
@version 0.5.1


-- | Scalpel core provides a subset of the <a>scalpel</a> web scraping
--   library that is intended to have lightweight dependencies and to be
--   free of all non-Haskell dependencies.
--   
--   Notably this package does not contain any networking support. Users
--   who desire a batteries include solution should depend on
--   <tt>scalpel</tt> which does include networking support instead of
--   <tt>scalpel-core</tt>.
--   
--   More thorough documentation including example code can be found in the
--   documentation of the <a>scalpel</a> package.
module Text.HTML.Scalpel.Core

-- | <a>Selector</a> defines a selection of an HTML DOM tree to be operated
--   on by a web scraper. The selection includes the opening tag that
--   matches the selection, all of the inner tags, and the corresponding
--   closing tag.
data Selector

-- | An <a>AttributePredicate</a> is a method that takes a <a>Attribute</a>
--   and returns a <a>Bool</a> indicating if the given attribute matches a
--   predicate.
data AttributePredicate

-- | The <a>AttributeName</a> type can be used when creating
--   <a>Selector</a>s to specify the name of an attribute of a tag.
data AttributeName
AnyAttribute :: AttributeName
AttributeString :: String -> AttributeName

-- | The <a>TagName</a> type is used when creating a <a>Selector</a> to
--   specify the name of a tag.
data TagName
AnyTag :: TagName
TagString :: String -> TagName
tagSelector :: String -> Selector

-- | A selector which will match all tags
anySelector :: Selector

-- | The <a>//</a> operator creates an <a>Selector</a> by nesting one
--   <a>Selector</a> in another. For example, <tt>"div" // "a"</tt> will
--   create a <a>Selector</a> that matches anchor tags that are nested
--   arbitrarily deep within a div tag.
(//) :: Selector -> Selector -> Selector
infixl 5 //

-- | The <a>@:</a> operator creates a <a>Selector</a> by combining a
--   <a>TagName</a> with a list of <a>AttributePredicate</a>s.
(@:) :: TagName -> [AttributePredicate] -> Selector
infixl 9 @:

-- | The <a>@=</a> operator creates an <a>AttributePredicate</a> that will
--   match attributes with the given name and value.
--   
--   If you are attempting to match a specific class of a tag with
--   potentially multiple classes, you should use the <a>hasClass</a>
--   utility function.
(@=) :: AttributeName -> String -> AttributePredicate
infixl 6 @=

-- | The <a>@=~</a> operator creates an <a>AttributePredicate</a> that will
--   match attributes with the given name and whose value matches the given
--   regular expression.
(@=~) :: RegexLike re String => AttributeName -> re -> AttributePredicate
infixl 6 @=~

-- | The classes of a tag are defined in HTML as a space separated list
--   given by the <tt>class</tt> attribute. The <a>hasClass</a> function
--   will match a <tt>class</tt> attribute if the given class appears
--   anywhere in the space separated list of classes.
hasClass :: String -> AttributePredicate

-- | Negates an <a>AttributePredicate</a>.
notP :: AttributePredicate -> AttributePredicate

-- | The <a>match</a> function allows for the creation of arbitrary
--   <a>AttributePredicate</a>s. The argument is a function that takes the
--   attribute key followed by the attribute value and returns a boolean
--   indicating if the attribute satisfies the predicate.
match :: (String -> String -> Bool) -> AttributePredicate

-- | A value of <a>Scraper</a> <tt>a</tt> defines a web scraper that is
--   capable of consuming a list of <a>Tag</a>s and optionally producing a
--   value of type <tt>a</tt>.
data Scraper str a

-- | The <a>attr</a> function takes an attribute name and a selector and
--   returns the value of the attribute of the given name for the first
--   opening tag that matches the given selector.
--   
--   This function will match only the opening tag matching the selector,
--   to match every tag, use <a>attrs</a>.
attr :: (Ord str, Show str, StringLike str) => String -> Selector -> Scraper str str

-- | The <a>attrs</a> function takes an attribute name and a selector and
--   returns the value of the attribute of the given name for every opening
--   tag that matches the given selector.
attrs :: (Ord str, Show str, StringLike str) => String -> Selector -> Scraper str [str]

-- | The <a>html</a> function takes a selector and returns the html string
--   from the set of tags described by the given selector.
--   
--   This function will match only the first set of tags matching the
--   selector, to match every set of tags, use <a>htmls</a>.
html :: (Ord str, StringLike str) => Selector -> Scraper str str

-- | The <a>htmls</a> function takes a selector and returns the html string
--   from every set of tags matching the given selector.
htmls :: (Ord str, StringLike str) => Selector -> Scraper str [str]

-- | The <a>innerHTML</a> function takes a selector and returns the inner
--   html string from the set of tags described by the given selector.
--   Inner html here meaning the html within but not including the selected
--   tags.
--   
--   This function will match only the first set of tags matching the
--   selector, to match every set of tags, use <a>innerHTMLs</a>.
innerHTML :: (Ord str, StringLike str) => Selector -> Scraper str str

-- | The <a>innerHTMLs</a> function takes a selector and returns the inner
--   html string from every set of tags matching the given selector.
innerHTMLs :: (Ord str, StringLike str) => Selector -> Scraper str [str]

-- | The <a>text</a> function takes a selector and returns the inner text
--   from the set of tags described by the given selector.
--   
--   This function will match only the first set of tags matching the
--   selector, to match every set of tags, use <a>texts</a>.
text :: (Ord str, StringLike str) => Selector -> Scraper str str

-- | The <a>texts</a> function takes a selector and returns the inner text
--   from every set of tags matching the given selector.
texts :: (Ord str, StringLike str) => Selector -> Scraper str [str]

-- | The <a>chroot</a> function takes a selector and an inner scraper and
--   executes the inner scraper as if it were scraping a document that
--   consists solely of the tags corresponding to the selector.
--   
--   This function will match only the first set of tags matching the
--   selector, to match every set of tags, use <a>chroots</a>.
chroot :: (Ord str, StringLike str) => Selector -> Scraper str a -> Scraper str a

-- | The <a>chroots</a> function takes a selector and an inner scraper and
--   executes the inner scraper as if it were scraping a document that
--   consists solely of the tags corresponding to the selector. The inner
--   scraper is executed for each set of tags matching the given selector.
chroots :: (Ord str, StringLike str) => Selector -> Scraper str a -> Scraper str [a]

-- | The <a>position</a> function is intended to be used within the
--   do-block of a <a>chroots</a> call. Within the do-block position will
--   return the index of the current sub-tree within the list of all
--   sub-trees matched by the selector passed to <a>chroots</a>.
--   
--   For example, consider the following HTML:
--   
--   <pre>
--   &lt;article&gt;
--    &lt;p&gt; First paragraph. &lt;/p&gt;
--    &lt;p&gt; Second paragraph. &lt;/p&gt;
--    &lt;p&gt; Third paragraph. &lt;/p&gt;
--   &lt;/article&gt;
--   </pre>
--   
--   The <a>position</a> function can be used to determine the index of
--   each <tt>&lt;p&gt;</tt> tag within the <tt>article</tt> tag by doing
--   the following.
--   
--   <pre>
--   chroots "article" // "p" $ do
--     index   &lt;- position
--     content &lt;- text "p"
--     return (index, content)
--   </pre>
--   
--   Which will evaluate to the list:
--   
--   <pre>
--   [
--     (0, "First paragraph.")
--   , (1, "Second paragraph.")
--   , (2, "Third paragraph.")
--   ]
--   </pre>
position :: (Ord str, StringLike str) => Scraper str Int

-- | The <a>scrape</a> function executes a <a>Scraper</a> on a list of
--   <a>Tag</a>s and produces an optional value.
scrape :: (Ord str, StringLike str) => Scraper str a -> [Tag str] -> Maybe a

-- | The <a>scrapeStringLike</a> function parses a <tt>StringLike</tt>
--   value into a list of tags and executes a <a>Scraper</a> on it.
scrapeStringLike :: (Ord str, StringLike str) => str -> Scraper str a -> Maybe a
