-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | An xhtml templating system
--   
--   An xhtml templating system
@package heist
@version 0.2.2

module Text.Templating.Heist.Splices.Ignore

-- | Default name for the ignore splice.
ignoreTag :: ByteString

-- | The ignore tag and everything it surrounds disappears in the rendered
--   output.
ignoreImpl :: (Monad m) => Splice m

module Text.Templating.Heist.Splices.Markdown
data PandocMissingException
PandocMissingException :: PandocMissingException
data MarkdownException
MarkdownException :: ByteString -> MarkdownException

-- | Default name for the markdown splice.
markdownTag :: ByteString

-- | Implementation of the markdown splice.
markdownSplice :: (MonadIO m) => Splice m
pandoc :: FilePath -> FilePath -> IO ByteString
pandocBS :: FilePath -> ByteString -> IO ByteString
readProcessWithExitCode' :: FilePath -> [String] -> ByteString -> IO (ExitCode, ByteString, ByteString)
instance Typeable MarkdownException
instance Typeable PandocMissingException
instance Exception MarkdownException
instance Show MarkdownException
instance Exception PandocMissingException
instance Show PandocMissingException

module Text.Templating.Heist.Splices.Apply

-- | Default name for the apply splice.
applyTag :: ByteString

-- | Default attribute name for the apply tag.
applyAttr :: ByteString

-- | Implementation of the apply splice.
applyImpl :: (Monad m) => Splice m

module Text.Templating.Heist.Splices.Bind

-- | Default name for the bind splice.
bindTag :: ByteString

-- | Default attribute name for the bind tag.
bindAttr :: ByteString

-- | Implementation of the bind splice.
bindImpl :: (Monad m) => Splice m

module Text.Templating.Heist.Splices.Static

-- | State for storing static tag information
data StaticTagState

-- | Modifies a TemplateState to include a "static" tag. The static tag is
--   not bound automatically with the other default Heist tags. This is
--   because this function also returns StaticTagState, so the user will be
--   able to clear it with the <a>clearStaticTagCache</a> function.
bindStaticTag :: (MonadIO m) => TemplateState m -> IO (TemplateState m, StaticTagState)

-- | Clears the static tag state.
clearStaticTagCache :: StaticTagState -> IO ()

module Text.Templating.Heist.Splices


-- | This module contains the core definitions for the Heist template
--   system.
--   
--   The Heist template system is based on XML/xhtml. It allows you to
--   build custom XML-based markup languages. With Heist you can define
--   your own domain-specific XML tags implemented with Haskell and use
--   them in your templates.
--   
--   The most important concept in Heist is the <a>Splice</a>. Splices can
--   be thought of as functions that transform a node into a list of nodes.
--   Heist then substitutes the resulting list of nodes into your template
--   in place of the input node. <a>Splice</a> is implemented as a type
--   synonym <tt>type Splice m = TemplateMonad m [Node]</tt>, and
--   <a>TemplateMonad</a> has a function <a>getParamNode</a> that lets you
--   get the input node.
--   
--   Suppose you have a place on your page where you want to display a link
--   with the text "Logout username" if the user is currently logged in or
--   a link to the login page if no user is logged in. Assume you have a
--   function <tt>getUser :: MyAppMonad (Maybe ByteString)</tt> that gets
--   the current user. You can implement this functionality with a
--   <a>Splice</a> as follows:
--   
--   <pre>
--   import Text.XML.Expat.Tree
--   
--   link :: ByteString -&gt; ByteString -&gt; Node
--   link target text = X.Element "a" [("href", target)] [X.Text text]
--   
--   loginLink :: Node
--   loginLink = link "/login" "Login"
--   
--   logoutLink :: ByteString -&gt; Node
--   logoutLink user = link "/logout" (B.append "Logout " user)
--   
--   loginLogoutSplice :: Splice MyAppMonad
--   loginLogoutSplice = do
--       user &lt;- lift getUser
--       return $ [maybe loginLink logoutLink user]
--   </pre>
--   
--   Next, you need to bind that splice to an XML tag. Heist stores
--   information about splices and templates in the <a>TemplateState</a>
--   data structure. The following code demonstrates how this splice would
--   be used.
--   
--   <pre>
--   mySplices = [ ("loginLogout", loginLogoutSplice) ]
--   
--   main = do
--       ets &lt;- loadTemplates "templates" $
--              foldr (uncurry bindSplice) emptyTemplateState mySplices
--       let ts = either error id ets
--       t &lt;- runMyAppMonad $ renderTemplate ts "index"
--       print $ maybe "Page not found" id t
--   </pre>
--   
--   Here we build up our <a>TemplateState</a> by starting with
--   emptyTemplateState and applying bindSplice for all the splices we want
--   to add. Then we pass this to loadTemplates our final
--   <a>TemplateState</a> wrapped in an Either to handle errors. Then we
--   use this <a>TemplateState</a> to render our templates.
module Text.Templating.Heist

-- | Heist templates are XML documents. The hexpat library is polymorphic
--   over the type of strings, so here we define a <a>Node</a> alias to fix
--   the string types of the tag names and tag bodies to <a>ByteString</a>.
type Node = Node ByteString ByteString

-- | A <a>Template</a> is a forest of XML nodes. Here we deviate from the
--   <a>single root node</a> 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]

-- | A Splice is a TemplateMonad computation that returns a
--   <a>Template</a>.
type Splice m = TemplateMonad m Template

-- | TemplateMonad is the monad used for <a>Splice</a> processing.
--   TemplateMonad provides "passthrough" instances for many of the monads
--   you might use in the inner monad.
data TemplateMonad m a

-- | Holds all the state information needed for template processing. You
--   will build a <tt>TemplateState</tt> using any of Heist's
--   <tt>TemplateState m -&gt; TemplateState m</tt> "filter" functions.
--   Then you use the resulting <tt>TemplateState</tt> in calls to
--   <tt>renderTemplate</tt>.
data TemplateState m

-- | Adds a template to the template state.
addTemplate :: (Monad m) => ByteString -> InternalTemplate -> TemplateState m -> TemplateState m

-- | An empty template state, with Heist's default splices
--   (<tt>&lt;apply&gt;</tt>, <tt>&lt;bind&gt;</tt>,
--   <tt>&lt;ignore&gt;</tt>, and <tt>&lt;markdown&gt;</tt>) mapped. The
--   static tag is not mapped here because it must be mapped manually in
--   your application.
emptyTemplateState :: (MonadIO m) => TemplateState m

-- | Binds a new splice declaration to a tag name within a
--   <a>TemplateState</a>.
bindSplice :: (Monad m) => ByteString -> Splice m -> TemplateState m -> TemplateState m

-- | Binds a set of new splice declarations within a <a>TemplateState</a>.
bindSplices :: (Monad m) => [(ByteString, Splice m)] -> TemplateState m -> TemplateState m

-- | Convenience function for looking up a splice.
lookupSplice :: (Monad m) => ByteString -> TemplateState m -> Maybe (Splice m)

-- | Sets the templateMap in a TemplateState.
setTemplates :: (Monad m) => TemplateMap -> TemplateState m -> TemplateState m

-- | Traverses the specified directory structure and builds a TemplateState
--   by loading all the files with a <a>.tpl</a> extension.
loadTemplates :: (Monad m) => FilePath -> TemplateState m -> IO (Either String (TemplateState m))

-- | Returns <a>True</a> if the given template can be found in the template
--   state.
hasTemplate :: (Monad m) => ByteString -> TemplateState m -> Bool

-- | Adds an on-load hook to a <a>TemplateState</a>.
addOnLoadHook :: (Monad m) => (Template -> IO Template) -> TemplateState m -> TemplateState m

-- | Adds a pre-run hook to a <a>TemplateState</a>.
addPreRunHook :: (Monad m) => (Template -> m Template) -> TemplateState m -> TemplateState m

-- | Adds a post-run hook to a <a>TemplateState</a>.
addPostRunHook :: (Monad m) => (Template -> m Template) -> TemplateState m -> TemplateState m

-- | Stops the recursive processing of splices. Consider the following
--   example:
--   
--   <pre>
--   &lt;foo&gt;
--     &lt;bar&gt;
--       ...
--     &lt;/bar&gt;
--   &lt;/foo&gt;
--   </pre>
--   
--   Assume that <tt>"foo"</tt> is bound to a splice procedure. Running the
--   <tt>foo</tt> splice will result in a list of nodes <tt>L</tt>.
--   Normally <tt>foo</tt> will recursively scan <tt>L</tt> for splices and
--   run them. If <tt>foo</tt> calls <tt>stopRecursion</tt>, <tt>L</tt>
--   will be included in the output verbatim without running any splices.
stopRecursion :: (Monad m) => TemplateMonad m ()

-- | Gets the node currently being processed.
--   
--   <pre>
--   &lt;speech author="Shakespeare"&gt;
--     To sleep, perchance to dream.
--   &lt;/speech&gt;
--   </pre>
--   
--   When you call <tt>getParamNode</tt> inside the code for the
--   <tt>speech</tt> splice, it returns the Node for the <tt>speech</tt>
--   tag and its children. <tt>getParamNode &gt;&gt;= getChildren</tt>
--   returns a list containing one Text node containing part of Hamlet's
--   speech. <tt>getParamNode &gt;&gt;= getAttribute "author"</tt> would
--   return <tt>Just <a>Shakespeare</a></tt>.
getParamNode :: (Monad m) => TemplateMonad m Node

-- | Performs splice processing on a list of nodes.
runNodeList :: (Monad m) => [Node] -> Splice m

-- | Gets the current context
getContext :: (Monad m) => TemplateMonad m TPath

-- | TemplateMonad's <a>local</a>.
localParamNode :: (Monad m) => (Node -> Node) -> TemplateMonad m a -> TemplateMonad m a

-- | TemplateMonad's <a>gets</a>.
getsTS :: (Monad m) => (TemplateState m -> r) -> TemplateMonad m r

-- | TemplateMonad's <a>get</a>.
getTS :: (Monad m) => TemplateMonad m (TemplateState m)

-- | TemplateMonad's <a>put</a>.
putTS :: (Monad m) => TemplateState m -> TemplateMonad m ()

-- | TemplateMonad's <a>modify</a>.
modifyTS :: (Monad m) => (TemplateState m -> TemplateState m) -> TemplateMonad m ()

-- | Restores the components of TemplateState that can get modified in
--   template calls. You should use this function instead of <tt>putTS</tt>
--   to restore an old state. Thas was needed because doctypes needs to be
--   in a <a>global scope</a> as opposed to the template call <a>local
--   scope</a> of state items such as recursionDepth, curContext, and
--   spliceMap.
restoreTS :: (Monad m) => TemplateState m -> TemplateMonad m ()

-- | Looks up a template name evaluates it by calling runNodeList.
evalTemplate :: (Monad m) => ByteString -> TemplateMonad m (Maybe Template)

-- | Renders a template with the specified parameters. This is the function
--   to use when you want to <a>call</a> a template and pass in parameters
--   from code.
callTemplate :: (Monad m) => ByteString -> [(ByteString, ByteString)] -> TemplateMonad m (Maybe Template)

-- | Renders a template from the specified TemplateState.
renderTemplate :: (Monad m) => TemplateState m -> ByteString -> m (Maybe ByteString)

-- | Binds a list of constant string splices
bindStrings :: (Monad m) => [(ByteString, ByteString)] -> TemplateState m -> TemplateState m

-- | Reads an XML document from disk.
getDoc :: String -> IO (Either String InternalTemplate)

-- | Turns an in-memory XML/XHTML bytestring into a (doctype,'[Node]')
--   pair.
parseDoc :: ByteString -> IO (Either String (Maybe ByteString, [Node]))

-- | Modifies a TemplateState to include a "static" tag. The static tag is
--   not bound automatically with the other default Heist tags. This is
--   because this function also returns StaticTagState, so the user will be
--   able to clear it with the <a>clearStaticTagCache</a> function.
bindStaticTag :: (MonadIO m) => TemplateState m -> IO (TemplateState m, StaticTagState)


-- | This module defines a TemplateDirectory data structure for convenient
--   interaction with templates within web apps.
module Text.Templating.Heist.TemplateDirectory

-- | Structure representing a template directory.
data TemplateDirectory m

-- | Creates and returns a new <a>TemplateDirectory</a> wrapped in an
--   Either for error handling.
newTemplateDirectory :: (MonadIO m, MonadIO n) => FilePath -> TemplateState m -> n (Either String (TemplateDirectory m))

-- | Creates and returns a new <a>TemplateDirectory</a>, using the monad's
--   fail function on error.
newTemplateDirectory' :: (MonadIO m, MonadIO n) => FilePath -> TemplateState m -> n (TemplateDirectory m)

-- | Gets the <a>TemplateState</a> from a TemplateDirectory.
getDirectoryTS :: (Monad m, MonadIO n) => TemplateDirectory m -> n (TemplateState m)

-- | Clears cached content and reloads templates from disk.
reloadTemplateDirectory :: (MonadIO m, MonadIO n) => TemplateDirectory m -> n (Either String ())