Added createListing, createListingWith functions.

These functions were added to have a simpler and more high-level way to do the
common createCustomPage/renderAndConcat combination to create post lists, rss
feeds, ...

6 files changed, 55 insertions, 17 deletions

diff --git a/src/Text/Hakyll/Context.hs b/src/Text/Hakyll/Context.hs
index 11cc123..f84d161 100644
--- a/src/Text/Hakyll/Context.hs
+++ b/src/Text/Hakyll/Context.hs
@@ -24,9 +24,9 @@ type Context = Map String String
 -- | Type for context manipulating functions.
 type ContextManipulation = Context -> Context
 
--- | Do something with a value in a "Context", but keep the old value as well.
+-- | Do something with a value in a @Context@, but keep the old value as well.
 --   This is probably the most common function to construct a
---   "ContextManipulation".
+--   @ContextManipulation@.
 renderValue :: String -- ^ Key of which the value should be copied.
             -> String -- ^ Key the value should be copied to.
             -> (String -> String) -- ^ Function to apply on the value.
@@ -35,7 +35,7 @@ renderValue src dst f context = case M.lookup src context of
     Nothing      -> context
     (Just value) -> M.insert dst (f value) context
 
--- | Change a value in a "Context".
+-- | Change a value in a @Context@.
 --
 --   > import Data.Char (toUpper)
 --   > changeValue "title" (map toUpper)
diff --git a/src/Text/Hakyll/Internal/Template.hs b/src/Text/Hakyll/Internal/Template.hs
index 155189b..b6f73b7 100644
--- a/src/Text/Hakyll/Internal/Template.hs
+++ b/src/Text/Hakyll/Internal/Template.hs
@@ -29,7 +29,7 @@ data Template = Chunk String Template
               | End
               deriving (Show, Read, Eq)
 
--- | Construct a "Template" from a string.
+-- | Construct a @Template@ from a string.
 fromString :: String -> Template
 fromString [] = End
 fromString string
@@ -41,7 +41,7 @@ fromString string
   where
     tail' = tail string
 
--- | Read a "Template" from a file. This function might fetch the "Template"
+-- | Read a @Template@ from a file. This function might fetch the @Template@
 --   from the cache, if available.
 readTemplate :: FilePath -> Hakyll Template
 readTemplate path = do
@@ -54,7 +54,7 @@ readTemplate path = do
   where 
     fileName = "templates" </> path
 
--- | Substitutes @$identifiers@ in the given "Template" by values from the given
+-- | Substitutes @$identifiers@ in the given @Template@ by values from the given
 --   "Context". When a key is not found, it is left as it is. You can specify
 --   the characters used to replace escaped dollars (@$$@) here.
 substitute :: String -> Template -> Context -> String 
@@ -68,12 +68,12 @@ substitute escaper (EscapeCharacter template) context =
     escaper ++ substitute escaper template context
 substitute _ End _ = []
 
--- | "substitute" for use during a chain. This will leave escaped characters as
+-- | @substitute@ for use during a chain. This will leave escaped characters as
 --   they are.
 regularSubstitute :: Template -> Context -> String
 regularSubstitute = substitute "$$"
 
--- | "substitute" for the end of a chain (just before writing). This renders
+-- | @substitute@ for the end of a chain (just before writing). This renders
 --   escaped characters.
 finalSubstitute :: Template -> Context -> String
 finalSubstitute = substitute "$"
@@ -111,7 +111,7 @@ arbitraryTemplate length' = oneof [ do chunk <- chunk'
                 return $ if null sanitized then "foo"
                                            else sanitized
 
--- | Make "Template" testable.
+-- | Make @Template@ testable.
 instance Arbitrary Template where
     arbitrary = choose (0, 20) >>= arbitraryTemplate
 
diff --git a/src/Text/Hakyll/Page.hs b/src/Text/Hakyll/Page.hs
index 8741cd6..a0d9ed0 100644
--- a/src/Text/Hakyll/Page.hs
+++ b/src/Text/Hakyll/Page.hs
@@ -1,4 +1,4 @@
--- | A module for dealing with "Page"s. This module is mostly internally used.
+-- | A module for dealing with @Page@s. This module is mostly internally used.
 module Text.Hakyll.Page 
     ( Page
     , fromContext
diff --git a/src/Text/Hakyll/Render.hs b/src/Text/Hakyll/Render.hs
index 3329994..0802330 100644
--- a/src/Text/Hakyll/Render.hs
+++ b/src/Text/Hakyll/Render.hs
@@ -71,8 +71,8 @@ renderAndConcat :: Renderable a
 renderAndConcat = renderAndConcatWith id
 
 -- | Render each renderable with the given templates, then concatenate the
---   result. This function allows you to specify a "ContextManipulation" to
---   apply on every "Renderable".
+--   result. This function allows you to specify a @ContextManipulation@ to
+--   apply on every @Renderable@.
 renderAndConcatWith :: Renderable a
                     => ContextManipulation
                     -> [FilePath]
@@ -97,7 +97,7 @@ renderChain :: Renderable a => [FilePath] -> a -> Hakyll ()
 renderChain = renderChainWith id
 
 -- | A more custom render chain that allows you to specify a
---   "ContextManipulation" which to apply on the context when it is read first.
+--   @ContextManipulation@ which to apply on the context when it is read first.
 renderChainWith :: Renderable a
                 => ContextManipulation -> [FilePath] -> a -> Hakyll ()
 renderChainWith manipulation templatePaths renderable =
diff --git a/src/Text/Hakyll/Renderables.hs b/src/Text/Hakyll/Renderables.hs
index c7183a8..85b6fdd 100644
--- a/src/Text/Hakyll/Renderables.hs
+++ b/src/Text/Hakyll/Renderables.hs
@@ -1,6 +1,8 @@
 module Text.Hakyll.Renderables
     ( CustomPage
     , createCustomPage
+    , createListing
+    , createListingWith
     , PagePath
     , createPagePath
     , CombinedRenderable
@@ -9,11 +11,14 @@ module Text.Hakyll.Renderables
     ) where
 
 import qualified Data.Map as M
+import Control.Arrow (second)
 
 import Text.Hakyll.Hakyll (Hakyll)
 import Text.Hakyll.Page
 import Text.Hakyll.Renderable
 import Text.Hakyll.File
+import Text.Hakyll.Context
+import Text.Hakyll.Render
 
 -- | A custom page.
 data CustomPage = CustomPage 
@@ -35,6 +40,39 @@ createCustomPage :: String -- ^ Destination of the page, relative to _site.
                  -> CustomPage
 createCustomPage = CustomPage
 
+-- | A @createCustomPage@ function specialized in creating listings.
+--
+--   This function creates a listing of a certain list of @Renderable@s. Every
+--   item in the list is created by applying the given template to every
+--   renderable. You can also specify additional context to be included in the
+--   @CustomPage@.
+createListing :: (Renderable a)
+              => String -- ^ Destination of the page.
+              -> FilePath -- ^ Template to render all items with.
+              -> [a] -- ^ Renderables in the list.
+              -> [(String, String)] -- ^ Additional context.
+              -> CustomPage
+createListing = createListingWith id
+
+-- | A @createCustomPage@ function specialized in creating listings.
+--
+--   In addition to @createListing@, this function allows you to specify an
+--   extra @ContextManipulation@ for all @Renderable@s given.
+createListingWith :: (Renderable a)
+                  => ContextManipulation -- ^ Manipulation for the renderables.
+                  -> String -- ^ Destination of the page.
+                  -> FilePath -- ^ Template to render all items with.
+                  -> [a] -- ^ Renderables in the list.
+                  -> [(String, String)] -- ^ Additional context.
+                  -> CustomPage
+createListingWith manipulation url template renderables additional =
+    createCustomPage url dependencies context
+  where
+    dependencies = template : concatMap getDependencies renderables
+    context = ("body", Right concatenation) : additional'
+    concatenation = renderAndConcatWith manipulation [template] renderables
+    additional' = map (second Left) additional
+
 instance Renderable CustomPage where
     getDependencies = customPageDependencies
     getURL = customPageURL
@@ -62,15 +100,15 @@ data CombinedRenderable a b = CombinedRenderable a b
                             | CombinedRenderableWithURL FilePath a b
 
 -- | Combine two renderables. The url will always be taken from the first
---   "Renderable". Also, if a `$key` is present in both renderables, the
---   value from the first "Renderable" will be taken as well.
+--   @Renderable@. Also, if a `$key` is present in both renderables, the
+--   value from the first @Renderable@ will be taken as well.
 --
 --   Since renderables are always more or less key-value maps, you can see
 --   this as a @union@ between two maps.
 combine :: (Renderable a, Renderable b) => a -> b -> CombinedRenderable a b
 combine = CombinedRenderable
 
--- | Combine two renderables and set a custom URL. This behaves like "combine",
+-- | Combine two renderables and set a custom URL. This behaves like @combine@,
 --   except that for the @url@ field, the given URL is always chosen.
 combineWithURL :: (Renderable a, Renderable b)
                => FilePath
diff --git a/src/Text/Hakyll/Tags.hs b/src/Text/Hakyll/Tags.hs
index 16796c6..8c1cee2 100644
--- a/src/Text/Hakyll/Tags.hs
+++ b/src/Text/Hakyll/Tags.hs
@@ -59,7 +59,7 @@ readTagMap identifier paths = do
         return $ foldr (flip (M.insertWith (++)) [path]) current tags
 
 -- | Render a tag cloud.
-renderTagCloud :: M.Map String [FilePath] -- ^ Map as produced by "readTagMap".
+renderTagCloud :: M.Map String [FilePath] -- ^ Map as produced by @readTagMap@.
                -> (String -> String) -- ^ Function to produce an url for a tag.
                -> Float -- ^ Smallest font size, in percent.
                -> Float -- ^ Biggest font size, in percent.