heist-0.8.0: An (x)html templating system

Safe HaskellNone

Text.Templating.Heist.Types

Description

This module contains the core Heist data types. HeistT intentionally does not expose any of its functionality via MonadState or MonadReader functions. We define passthrough instances for the most common types of monads. These instances allow the user to use HeistT in a monad stack without needing calls to lift.

Edward Kmett wrote most of the HeistT code and associated instances, liberating us from the unused writer portion of RWST.

Synopsis

Documentation

type Template = [Node]Source

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 MIMEType = ByteStringSource

MIME Type. The type alias is here to make the API clearer.

type TPath = [ByteString]Source

Reversed list of directories. This holds the path to the template currently being processed.

data DocumentFile Source

Constructors

DocumentFile 

Instances

type TemplateMap = HashMap TPath DocumentFileSource

All documents representing templates are stored in a map.

type Splice m = HeistT m TemplateSource

A Splice is a HeistT computation that returns a Template.

type SpliceMap m = HashMap Text (Splice m)Source

SpliceMap associates a name and a Splice.

data HeistState m Source

Holds all the state information needed for template processing. You will build a HeistState using any of Heist's HeistState m -> HeistState m "filter" functions. Then you use the resulting HeistState in calls to renderTemplate.

Constructors

HeistState 

Fields

_spliceMap :: SpliceMap m

A mapping of splice names to splice actions

_templateMap :: TemplateMap

A mapping of template names to templates

_recurse :: Bool

A flag to control splice recursion

_curContext :: TPath

The path to the template currently being processed.

_recursionDepth :: Int

A counter keeping track of the current recursion depth to prevent infinite loops.

_onLoadHook :: Template -> IO Template

A hook run on all templates at load time.

_preRunHook :: Template -> m Template

A hook run on all templates just before they are rendered.

_postRunHook :: Template -> m Template

A hook run on all templates just after they are rendered.

_doctypes :: [DocType]

The doctypes encountered during template processing.

_curTemplateFile :: Maybe FilePath

The full path to the current template's file on disk.

Instances

templateNames :: HeistState m -> [TPath]Source

Gets the names of all the templates defined in a HeistState.

spliceNames :: HeistState m -> [Text]Source

Gets the names of all the splices defined in a HeistState.

templateStateTyCon :: TyConSource

The Typeable instance is here so Heist can be dynamically executed with Hint.

newtype HeistT m a Source

HeistT is the monad used for Splice processing. HeistT provides "passthrough" instances for many of the monads you might use in the inner monad.

Constructors

HeistT 

Fields

runHeistT :: Node -> HeistState m -> m (a, HeistState m)
 

Instances

MonadTrans HeistT

MonadTrans instance

MonadError e m => MonadError e (HeistT m)

MonadError passthrough instance

MonadReader r m => MonadReader r (HeistT m)

MonadReader passthrough instance

MonadState s m => MonadState s (HeistT m)

MonadState passthrough instance

Monad m => Monad (HeistT m)

Monad instance

Functor m => Functor (HeistT m)

Functor instance

Typeable1 m => Typeable1 (HeistT m) 
MonadFix m => MonadFix (HeistT m)

MonadFix passthrough instance

MonadPlus m => MonadPlus (HeistT m)

MonadPlus passthrough instance

(Monad m, Functor m) => Applicative (HeistT m)

Applicative instance

MonadCatchIO m => MonadCatchIO (HeistT m)

MonadCatchIO instance

(Functor m, MonadPlus m) => Alternative (HeistT m)

Alternative passthrough instance

MonadIO m => MonadIO (HeistT m)

MonadIO instance

MonadCont m => MonadCont (HeistT m)

MonadCont passthrough instance

evalHeistT :: Monad m => HeistT m a -> Node -> HeistState m -> m aSource

Evaluates a template monad as a computation in the underlying monad.

liftCatch :: (m (a, HeistState m) -> (e -> m (a, HeistState m)) -> m (a, HeistState m)) -> HeistT m a -> (e -> HeistT m a) -> HeistT m aSource

Helper for MonadError instance.

liftCallCC :: ((((a, HeistState m) -> m (b, HeistState m)) -> m (a, HeistState m)) -> m (a, HeistState m)) -> ((a -> HeistT m b) -> HeistT m a) -> HeistT m aSource

Helper for MonadCont instance.

templateMonadTyCon :: TyConSource

The Typeable instance is here so Heist can be dynamically executed with Hint.

getParamNode :: Monad m => HeistT m NodeSource

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 >>= childNodes returns a list containing one TextNode containing part of Hamlet's speech. liftM (getAttribute "author") getParamNode would return Just Shakespeare.

localParamNode :: Monad m => (Node -> Node) -> HeistT m a -> HeistT m aSource

HeistT's local.

getsTS :: Monad m => (HeistState m -> r) -> HeistT m rSource

HeistT's gets.

getTS :: Monad m => HeistT m (HeistState m)Source

HeistT's get.

putTS :: Monad m => HeistState m -> HeistT m ()Source

HeistT's put.

modifyTS :: Monad m => (HeistState m -> HeistState m) -> HeistT m ()Source

HeistT's modify.

restoreTS :: Monad m => HeistState m -> HeistT m ()Source

Restores the HeistState. This function is almost like putTS except it preserves the current doctypes. You should use this function instead of putTS to restore an old state. This was needed because doctypes needs to be in a global scope as opposed to the template call local scope of state items such as recursionDepth, curContext, and spliceMap.

localTS :: Monad m => (HeistState m -> HeistState m) -> HeistT m a -> HeistT m aSource

Abstracts the common pattern of running a HeistT computation with a modified heist state.