From 15cf405c94e6fe649f592634338ca63c00279d19 Mon Sep 17 00:00:00 2001 From: vi Date: Tue, 1 Jul 2014 20:14:45 +0800 Subject: [PATCH] Some light documentation for Taggy.{Combinators,Renderer}. --- src/Text/Taggy/Combinators.hs | 20 ++++++++++++++++++++ src/Text/Taggy/Renderer.hs | 7 +++++-- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/src/Text/Taggy/Combinators.hs b/src/Text/Taggy/Combinators.hs index e2cfb90..4bd2c0c 100644 --- a/src/Text/Taggy/Combinators.hs +++ b/src/Text/Taggy/Combinators.hs @@ -41,19 +41,39 @@ innerText :: Element -> Text innerText = mconcat . map getContent . eltChildren where getContent = \case { NodeElement e -> innerText e; NodeContent x -> x } +-- | Filter an element and its children to those +-- satisfying a given predicate. (//) :: Element -> (Element -> Bool) -> [Element] (//) = flip filter . trees +-- | Given a sequence of predicates, filter an element +-- and its children, selecting only those subtrees who +-- match the provided predicate for each point. +-- +-- >>> let element = (\(NodeElement e) -> e) . head . domify . taggyWith False $ "foobaz" +-- >>> element /& [const False] +-- [] +-- >>> element /& [flip hasAttr "class", flip hasName "quux"] +-- [Element "quux" "" ""] + (/&) :: Element -> [(Element -> Bool)] -> [Element] (/&) element [] = [element] (/&) element (x:xs) = (/& xs) <=< filter x . catElements $ eltChildren element +-- | Filter from all subtrees (including the one +-- with the target as its root), those matching the +-- given sequence of predicates. + (/*) :: Element -> [(Element -> Bool)] -> [Element] (/*) element selector = concat . filter (not.null) . map (/& selector) $ trees element +-- | Extracts all subtrees of its target, including the target. + trees :: Element -> [Element] trees = ap (:) subtrees +-- | Extracts all subtrees of its target, excluding the target. + subtrees :: Element -> [Element] subtrees = ap (:) subtrees <=< catElements . eltChildren diff --git a/src/Text/Taggy/Renderer.hs b/src/Text/Taggy/Renderer.hs index 7263bbd..3b926a6 100644 --- a/src/Text/Taggy/Renderer.hs +++ b/src/Text/Taggy/Renderer.hs @@ -26,8 +26,8 @@ import Text.Blaze.Internal (ChoiceString(..), StaticString(..), MarkupM(..)) -- escaped, but a naked `Text s` is. class AsMarkup a where - -- If the first parameter is true, we align the constructors for entity - -- conversion. + -- | If the first parameter is true, we align the constructors for entity + -- conversion. toMarkup :: Bool -> a -> Markup -- | A 'Node' is convertible to 'Markup' @@ -49,6 +49,9 @@ class Renderable a where render = renderWith True renderWith :: Bool -> a -> Lazy.Text +-- | Any value convertible to 'Markup' can be rendered as HTML, by way of +-- 'render' and 'renderWith'. + instance AsMarkup a => Renderable a where renderWith = fmap renderMarkup . toMarkup