From 592845985828f3ee135c309257e9bbcb305be1fa Mon Sep 17 00:00:00 2001 From: Jasper Van der Jeugt Date: Wed, 27 Jan 2010 18:02:43 +0100 Subject: 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, ... --- src/Text/Hakyll/Context.hs | 6 ++--- src/Text/Hakyll/Internal/Template.hs | 12 +++++----- src/Text/Hakyll/Page.hs | 2 +- src/Text/Hakyll/Render.hs | 6 ++--- src/Text/Hakyll/Renderables.hs | 44 +++++++++++++++++++++++++++++++++--- src/Text/Hakyll/Tags.hs | 2 +- 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. -- cgit v1.2.3