This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "heist".
The branch, master has been updated
via 3c186afcdd929b2afe45bd3af00b54eb4f1a5fcf (commit)
from aa91aaa6d7bc7750009f466c7c69b32e7316470f (commit)
Summary of changes:
src/Text/Templating/Heist.hs | 4 +-
src/Text/Templating/Heist/Constants.hs | 12 +++++
src/Text/Templating/Heist/Internal.hs | 75 +++++++++++++++++--------------
3 files changed, 54 insertions(+), 37 deletions(-)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 3c186afcdd929b2afe45bd3af00b54eb4f1a5fcf
Author: Mighty Byte <[email protected]>
Date: Thu May 27 20:26:28 2010 -0400
Improved documentation.
diff --git a/src/Text/Templating/Heist.hs b/src/Text/Templating/Heist.hs
index 77f435b..67cdb33 100644
--- a/src/Text/Templating/Heist.hs
+++ b/src/Text/Templating/Heist.hs
@@ -64,8 +64,8 @@ module Text.Templating.Heist
(
-- * Types
Node
- , Splice
, Template
+ , Splice
, TemplateMonad
, TemplateState
@@ -102,8 +102,6 @@ module Text.Templating.Heist
, getDoc
, bindStaticTag
- , heistExpatOptions
- , module Text.Templating.Heist.Constants
) where
import Control.Monad.Trans
diff --git a/src/Text/Templating/Heist/Constants.hs
b/src/Text/Templating/Heist/Constants.hs
index fc67032..79dc162 100644
--- a/src/Text/Templating/Heist/Constants.hs
+++ b/src/Text/Templating/Heist/Constants.hs
@@ -5,6 +5,18 @@ import Data.ByteString.Char8 (ByteString)
import qualified Data.Map as Map
import Data.Map (Map)
+
+------------------------------------------------------------------------------
+-- | Options passed to hexpat for XML parsing.
+heistExpatOptions :: X.ParserOptions ByteString ByteString
+heistExpatOptions =
+ X.defaultParserOptions {
+ X.parserEncoding = Just X.UTF8
+ , X.entityDecoder = Just (\k -> Map.lookup k htmlEntityLookupTable)
+ }
+
+------------------------------------------------------------------------------
+-- | Character entity references for HTML.
htmlEntityLookupTable :: Map ByteString ByteString
htmlEntityLookupTable = Map.fromList [
("acute" , "\xc2\xb4")
diff --git a/src/Text/Templating/Heist/Internal.hs
b/src/Text/Templating/Heist/Internal.hs
index a94e528..0a65b28 100644
--- a/src/Text/Templating/Heist/Internal.hs
+++ b/src/Text/Templating/Heist/Internal.hs
@@ -36,42 +36,29 @@ type Node = X.Node ByteString ByteString
------------------------------------------------------------------------------
--- | A 'Template' is a forest of XML nodes.
+-- | A 'Template' is a forest of XML nodes. Here we deviate from the "single
+-- root node" constraint of well-formed XML because we want to allow templates
+-- to contain fragments of a document that may not have a single root.
type Template = [Node]
------------------------------------------------------------------------------
--- | Reversed list of directories
+-- | Reversed list of directories. This holds the path to the template
+-- currently being processed.
type TPath = [ByteString]
------------------------------------------------------------------------------
+-- | All templates are stored in a map.
type TemplateMap = Map TPath Template
------------------------------------------------------------------------------
--- | Holds all the state information needed for template processing:
---
--- * a collection of named templates. If you use the @\<apply
--- template=\"foo\"\>@ tag to include another template by name, @\"foo\"@
--- is looked up in here.
---
--- * the mapping from tag names to 'Splice's.
---
--- * a flag to control whether we will recurse during splice processing.
---
--- We'll illustrate the recursion flag with a small example template:
---
--- > <foo>
--- > <bar>
--- > ...
--- > </bar>
--- > </foo>
---
--- Assume that @\"foo\"@ is bound to a splice procedure. Running the @foo@
--- splice will result in a list of nodes @L@; if the recursion flag is on we
--- will recursively scan @L@ for splices, otherwise @L@ will be included in the
--- output verbatim.
+-- | Holds all the state information needed for template processing. You will
+-- build a @TemplateState@ using any of Heist's @TemplateState m ->
+-- TemplateState m@ \"filter\" functions. Then you use the resulting
+-- @TemplateState@ in calls to @renderTemplate@, @runTemplate@, or
+-- @runrawtempl...@.
data TemplateState m = TemplateState {
-- | A mapping of splice names to splice actions
_spliceMap :: SpliceMap m
@@ -79,10 +66,16 @@ data TemplateState m = TemplateState {
, _templateMap :: TemplateMap
-- | A flag to control splice recursion
, _recurse :: Bool
+ -- | The path to the template currently being processed.
, _curContext :: TPath
+ -- | A counter keeping track of the current recursion depth to prevent
+ -- infinite loops.
, _recursionDepth :: Int
+ -- | A hook run on all templates at load time.
, _onLoadHook :: Template -> IO Template
+ -- | A hook run on all templates just before they are rendered.
, _preRunHook :: Template -> m Template
+ -- | A hook run on all templates just after they are rendered.
, _postRunHook :: Template -> m Template
}
@@ -137,7 +130,7 @@ instance (Typeable1 m, Typeable a) => Typeable
(TemplateMonad m a) where
------------------------------------------------------------------------------
--- | A Splice is a TemplateMonad computation that returns [Node].
+-- | A Splice is a TemplateMonad computation that returns a 'Template'.
type Splice m = TemplateMonad m Template
@@ -277,12 +270,34 @@ addTemplate n t st = insertTemplate (splitPaths n) t st
------------------------------------------------------------------------------
-- | Gets the node currently being processed.
+--
+-- > <speech author="Shakespeare">
+-- > To sleep, perchance to dream.
+-- > </speech>
+--
+-- When you call @getParamNode@ inside the code for the @speech@ splice, it
+-- returns the Node for the @speech@ tag and its children. @getParamNode >>=
+-- getChildren@ returns a list containing one 'Text' node containing part of
+-- Hamlet's speech. @getParamNode >>= getAttribute \"author\"@ would return
+-- @Just "Shakespeare"@.
getParamNode :: Monad m => TemplateMonad m Node
getParamNode = ask
------------------------------------------------------------------------------
--- | Stops the recursive processing of splices.
+-- | Stops the recursive processing of splices. Consider the following
+-- example:
+--
+-- > <foo>
+-- > <bar>
+-- > ...
+-- > </bar>
+-- > </foo>
+--
+-- Assume that @\"foo\"@ is bound to a splice procedure. Running the @foo@
+-- splice will result in a list of nodes @l...@. Normally @foo@ will
recursively
+-- scan @L@ for splices and run them. If @foo@ calls @stopRecursion@, @L@
+-- will be included in the output verbatim without running any splices.
stopRecursion :: Monad m => TemplateMonad m ()
stopRecursion = modify (\st -> st { _recurse = False })
@@ -425,14 +440,6 @@ renderTemplate ts name = do
------------------------------------------------------------------------------
-heistExpatOptions :: X.ParserOptions ByteString ByteString
-heistExpatOptions =
- X.defaultParserOptions {
- X.parserEncoding = Just X.UTF8
- , X.entityDecoder = Just (\k -> Map.lookup k htmlEntityLookupTable)
- }
-
-------------------------------------------------------------------------------
-- Template loading
------------------------------------------------------------------------------
-----------------------------------------------------------------------
hooks/post-receive
--
heist
_______________________________________________
Snap mailing list
[email protected]
http://mailman-mail5.webfaction.com/listinfo/snap
