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


-- | An Haskell template system supporting both HTML5 and XML.
--   
--   Heist is a powerful template system that supports both HTML5 and XML.
--   Some of Heist's features are:
--   
--   <ul>
--   <li>Designer-friendly HTML5 (or XML) syntax</li>
--   <li>Templates can be reloaded to make changes visible without
--   recompiling your Haskell code</li>
--   <li>Enforces near-perfect separation of business logic and view</li>
--   <li>Powerful abstraction primitives allowing you to eliminate
--   repetition</li>
--   <li>Easy creation of domain-specific markup languages</li>
--   <li>Built-in support for including JSON and Markdown content in
--   templates</li>
--   <li>Simple mechanism for designer-specified template caching</li>
--   <li>Optional merging of multiple &lt;head&gt; tags defined anywhere in
--   the document</li>
--   </ul>
@package heist
@version 1.1

module Heist.Compiled.LowLevel

-- | Promises are used for referencing the results of future runtime
--   computations during load time splice processing.
data Promise a

-- | Creates an empty promise.
newEmptyPromise :: HeistT n IO (Promise a)

-- | Gets the result of a promised runtime computation.
getPromise :: (Monad n) => Promise a -> RuntimeSplice n a

-- | Adds a promise to the runtime splice context.
putPromise :: (Monad n) => Promise a -> a -> RuntimeSplice n ()

-- | Modifies a promise.
adjustPromise :: Monad n => Promise a -> (a -> a) -> RuntimeSplice n ()


-- | Compiled splices are similar to the original Heist (interpreted)
--   splices, but without the high performance costs of traversing a DOM at
--   runtime. Compiled splices do all of their DOM processing at load time.
--   They are compiled to produce a runtime computation that generates a
--   ByteString Builder. This preserves the ability to write splices that
--   access runtime information from the HTTP request, database, etc.
--   
--   If you import both this module and <a>Heist.Interpreted</a> in the
--   same file, then you will need to import them qualified.
module Heist.Compiled

-- | A compiled Splice is a HeistT computation that returns a <tt>DList
--   (Chunk m)</tt>.
--   
--   The more interesting part of the type signature is what comes before
--   the return value. The first type parameter in <tt><a>HeistT</a> n
--   IO</tt> is the runtime monad. This reveals that the Chunks know about
--   the runtime monad. The second type parameter in <tt>HeistT n IO</tt>
--   is <tt>IO</tt>. This tells us that the compiled splices themselves are
--   run in the IO monad, which will usually mean at load time. Compiled
--   splices run at load time, and they return computations that run at
--   runtime.
type Splice n = HeistT n IO (DList (Chunk n))

-- | Looks up a compiled template and returns a runtime monad computation
--   that constructs a builder.
--   
--   Note that template names should not include the .tpl extension:
--   
--   <pre>
--   renderTemplate hs "index"
--   </pre>
renderTemplate :: Monad n => HeistState n -> ByteString -> Maybe (n Builder, MIMEType)

-- | Given a list of output chunks, codeGen turns consecutive runs of
--   <tt>Pure Html</tt> values into maximally-efficient pre-rendered strict
--   <a>ByteString</a> chunks.
codeGen :: Monad n => DList (Chunk n) -> RuntimeSplice n Builder

-- | Runs the parameter node's children and returns the resulting compiled
--   chunks. By itself this function is a simple passthrough splice that
--   makes the spliced node disappear. In combination with locally bound
--   splices, this function makes it easier to pass the desired view into
--   your splices.
runChildren :: Monad n => Splice n

-- | Converts a pure text splice function to a pure Builder splice
--   function.
textSplice :: (a -> Text) -> a -> Builder

-- | This is the same as htmlNodeSplice.

-- | <i>Deprecated: Use xmlNodeSplice or htmlNodeSplice, will be removed in
--   Heist 1.1</i>
nodeSplice :: (a -> [Node]) -> a -> Builder

-- | Converts a pure XML Node splice function to a pure Builder splice
--   function.
xmlNodeSplice :: (a -> [Node]) -> a -> Builder

-- | Converts a pure HTML Node splice function to a pure Builder splice
--   function.
htmlNodeSplice :: (a -> [Node]) -> a -> Builder

-- | Converts a pure Builder splice function into a monadic splice function
--   of a RuntimeSplice.
pureSplice :: Monad n => (a -> Builder) -> RuntimeSplice n a -> Splice n

-- | Similar to <a>mapSplices</a> in interpreted mode. Gets a runtime list
--   of items and applies a compiled runtime splice function to each
--   element of the list.
deferMany :: (Foldable f, Monad n) => (RuntimeSplice n a -> Splice n) -> RuntimeSplice n (f a) -> Splice n

-- | Saves the results of a runtime computation in a <a>Promise</a> so they
--   don't get recalculated if used more than once.
--   
--   Note that this is just a specialized version of function application
--   ($) done for the side effect in runtime splice.
defer :: Monad n => (RuntimeSplice n a -> Splice n) -> RuntimeSplice n a -> Splice n

-- | A version of defer which applies a function on the runtime value.
deferMap :: Monad n => (a -> RuntimeSplice n b) -> (RuntimeSplice n b -> Splice n) -> RuntimeSplice n a -> Splice n

-- | Like deferMap, but only runs the result if a Maybe function of the
--   runtime value returns Just. If it returns Nothing, then no output is
--   generated.
mayDeferMap :: Monad n => (a -> RuntimeSplice n (Maybe b)) -> (RuntimeSplice n b -> Splice n) -> RuntimeSplice n a -> Splice n

-- | Converts an RuntimeSplice into a Splice, given a helper function that
--   generates a Builder.
bindLater :: (Monad n) => (a -> RuntimeSplice n Builder) -> RuntimeSplice n a -> Splice n

-- | Runs a splice, but first binds splices given by splice functions that
--   need some runtime data.
withSplices :: Monad n => Splice n -> Splices (RuntimeSplice n a -> Splice n) -> RuntimeSplice n a -> Splice n

-- | Like withSplices, but evaluates the splice repeatedly for each element
--   in a list generated at runtime.
manyWithSplices :: (Foldable f, Monad n) => Splice n -> Splices (RuntimeSplice n a -> Splice n) -> RuntimeSplice n (f a) -> Splice n

-- | More powerful version of manyWithSplices that lets you also define
--   attribute splices.
manyWith :: (Foldable f, Monad n) => Splice n -> Splices (RuntimeSplice n a -> Splice n) -> Splices (RuntimeSplice n a -> AttrSplice n) -> RuntimeSplice n (f a) -> Splice n

-- | Adds a list of compiled splices to the splice map. This function is
--   useful because it allows compiled splices to bind other compiled
--   splices during load-time splice processing.
withLocalSplices :: Splices (Splice n) -> Splices (AttrSplice n) -> HeistT n IO a -> HeistT n IO a

-- | Yields a pure Builder known at load time. You should use this and
--   <a>yieldPureText</a> as much as possible to maximize the parts of your
--   page that can be compiled to static ByteStrings.
yieldPure :: Builder -> DList (Chunk n)

-- | Yields a runtime action that returns a builder.
yieldRuntime :: RuntimeSplice n Builder -> DList (Chunk n)

-- | Yields a runtime action that returns no value and is only needed for
--   its side effect.
yieldRuntimeEffect :: Monad n => RuntimeSplice n () -> DList (Chunk n)

-- | A convenience wrapper around yieldPure for working with Text. Roughly
--   equivalent to <a>textSplice</a> from Heist.Interpreted.
yieldPureText :: Text -> DList (Chunk n)

-- | Convenience wrapper around yieldRuntime allowing you to work with
--   Text.
yieldRuntimeText :: Monad n => RuntimeSplice n Text -> DList (Chunk n)

-- | Returns a computation that performs load-time splice processing on the
--   supplied list of nodes.
runNodeList :: Monad n => [Node] -> Splice n

-- | Runs a single node. If there is no splice referenced anywhere in the
--   subtree, then it is rendered as a pure chunk, otherwise it calls
--   compileNode to generate the appropriate runtime computation.
runNode :: Monad n => Node -> Splice n

-- | Performs splice processing on a list of attributes. This is useful in
--   situations where you need to stop recursion, but still run splice
--   processing on the node's attributes.
runAttributes :: Monad n => [(Text, Text)] -> HeistT n IO [DList (Chunk n)]

-- | Performs splice processing on a list of attributes. This is useful in
--   situations where you need to stop recursion, but still run splice
--   processing on the node's attributes.
runAttributesRaw :: Monad n => [(Text, Text)] -> HeistT n IO (RuntimeSplice n [(Text, Text)])

-- | Looks up a compiled template and returns a compiled splice.
callTemplate :: Monad n => ByteString -> Splice n


-- | This module defines the API for writing and working with interpreted
--   splices. It exports some of the same symbols as <a>Heist.Compiled</a>,
--   so you will probably want to import it qualified.
--   
--   Interpreted splices can be thought of as a function <tt>Node -&gt; m
--   [Node]</tt>. 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 = HeistT m [Node]</tt>, and
--   <tt>HeistT</tt> has a function <tt>getParamNode</tt> 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 Text)</tt> that gets the
--   current user. You can implement this functionality with a
--   <a>Splice</a> as follows:
--   
--   <pre>
--   import           Blaze.ByteString.Builder
--   import           Data.ByteString.Char8 (ByteString)
--   import qualified Data.ByteString.Char8 as B
--   import           Data.Text (Text)
--   import qualified Data.Text as T
--   import qualified Text.XmlHtml as X
--   
--   import qualified Heist.Interpreted as I
--   
--   link :: Text -&gt; Text -&gt; X.Node
--   link target text = X.Element "a" [("href", target)] [X.TextNode text]
--   
--   loginLink :: X.Node
--   loginLink = link "/login" "Login"
--   
--   logoutLink :: Text -&gt; X.Node
--   logoutLink user = link "/logout" (T.append "Logout " user)
--   
--   loginLogoutSplice :: I.Splice MyAppMonad
--   loginLogoutSplice = do
--       user &lt;- lift getUser
--       return [maybe loginLink logoutLink user]
--   </pre>
module Heist.Interpreted
type Splice n = HeistT n n Template

-- | Adds an HTML format template to the heist state.
addTemplate :: ByteString -> Template -> Maybe FilePath -> HeistState n -> HeistState n

-- | Adds an XML format template to the heist state.
addXMLTemplate :: ByteString -> Template -> Maybe FilePath -> HeistState n -> HeistState n

-- | Convenience function for looking up a splice.
lookupSplice :: Text -> HeistState n -> Maybe (Splice n)

-- | Binds a new splice declaration to a tag name within a
--   <a>HeistState</a>.
bindSplice :: Text -> Splice n -> HeistState n -> HeistState n

-- | Binds a set of new splice declarations within a <a>HeistState</a>.
bindSplices :: Splices (Splice n) -> HeistState n -> HeistState n

-- | Binds a set of new splice declarations within a <a>HeistState</a>.
bindAttributeSplices :: Splices (AttrSplice n) -> HeistState n -> HeistState n

-- | Converts <a>Text</a> to a splice returning a single <tt>TextNode</tt>.
textSplice :: Monad m => Text -> HeistT n m Template

-- | Runs the parameter node's children and returns the resulting node
--   list. By itself this function is a simple passthrough splice that
--   makes the spliced node disappear. In combination with locally bound
--   splices, this function makes it easier to pass the desired view into
--   your splices.
runChildren :: Monad n => Splice n

-- | Binds a list of splices before using the children of the spliced node
--   as a view.
runChildrenWith :: (Monad n) => Splices (Splice n) -> Splice n

-- | Wrapper around runChildrenWith that applies a transformation function
--   to the second item in each of the tuples before calling
--   runChildrenWith.
runChildrenWithTrans :: (Monad n) => (b -> Splice n) -> Splices b -> Splice n

-- | Like runChildrenWith but using constant templates rather than dynamic
--   splices.
runChildrenWithTemplates :: (Monad n) => Splices Template -> Splice n

-- | Like runChildrenWith but using literal text rather than dynamic
--   splices.
runChildrenWithText :: (Monad n) => Splices Text -> Splice n

-- | Maps a splice generating function over a list and concatenates the
--   results. This function now has a more general type signature so it
--   works with both compiled and interpreted splices. The old type
--   signature was this:
--   
--   <pre>
--   mapSplices :: (Monad n)
--           =&gt; (a -&gt; Splice n n)
--           -&gt; [a]
--           -&gt; Splice n n
--   </pre>
mapSplices :: (Monad m, Monoid b) => (a -> m b) -> [a] -> m b

-- | 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 => HeistT n m ()

-- | Performs splice processing on a single node.
runNode :: Monad n => Node -> Splice n

-- | Performs splice processing on a list of attributes. This is useful in
--   situations where you need to stop recursion, but still run splice
--   processing on the node's attributes.
runAttributes :: Monad n => [(Text, Text)] -> HeistT n n [(Text, Text)]

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

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

-- | Binds a list of constant string splices.
bindStrings :: Monad n => Splices Text -> HeistState n -> HeistState n

-- | Binds a single constant string splice.
bindString :: Monad n => Text -> Text -> HeistState n -> HeistState n

-- | Renders a template with the specified parameters. This is the function
--   to use when you want to "call" a template and pass in parameters from
--   inside a splice. If the template does not exist, this version simply
--   returns an empty list.
callTemplate :: Monad n => ByteString -> Splices (Splice n) -> HeistT n n Template

-- | Like callTemplate except the splices being bound are constant text
--   splices.
callTemplateWithText :: Monad n => ByteString -> Splices Text -> HeistT n n Template

-- | Renders a template from the specified HeistState to a <a>Builder</a>.
--   The MIME type returned is based on the detected character encoding,
--   and whether the root template was an HTML or XML format template. It
--   will always be <tt>text/html</tt> or <tt>text/xml</tt>. If a more
--   specific MIME type is needed for a particular XML application, it must
--   be provided by the application.
--   
--   Note that template names should not include the .tpl extension:
--   
--   <pre>
--   renderTemplate hs "index"
--   </pre>
renderTemplate :: Monad n => HeistState n -> ByteString -> n (Maybe (Builder, MIMEType))
renderTemplateToDoc :: Monad n => HeistState n -> ByteString -> n (Maybe Document)

-- | Renders a template with the specified arguments passed to it. This is
--   a convenience function for the common pattern of calling
--   renderTemplate after using bindString, bindStrings, or bindSplice to
--   set up the arguments to the template.
renderWithArgs :: Monad n => Splices Text -> HeistState n -> ByteString -> n (Maybe (Builder, MIMEType))


-- | Internal types and accessors. There are no guarantees that heist will
--   preserve backwards compatibility for symbols in this module. If you
--   use them, no complaining when your code breaks.
module Heist.Internal.Types

-- | Convenient type alies for splices.
type Splices s = MapSyntax Text s

-- | A <a>Template</a> 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 document fragments that may not have a
--   single root.
type Template = [Node]

-- | MIME Type. The type alias is here to make the API clearer.
type MIMEType = ByteString

-- | Reversed list of directories. This holds the path to the template
--   currently being processed.
type TPath = [ByteString]

-- | Holds data about templates read from disk.
data DocumentFile
DocumentFile :: Document -> Maybe FilePath -> DocumentFile
[dfDoc] :: DocumentFile -> Document
[dfFile] :: DocumentFile -> Maybe FilePath

-- | Designates whether a document should be treated as XML or HTML.
data Markup
Xml :: Markup
Html :: Markup

-- | Monad used for runtime splice execution.
newtype RuntimeSplice m a
RuntimeSplice :: StateT HeterogeneousEnvironment m a -> RuntimeSplice m a
[unRT] :: RuntimeSplice m a -> StateT HeterogeneousEnvironment m a

-- | Opaque type representing pieces of output from compiled splices.
data Chunk m

-- | output known at load time
Pure :: !ByteString -> Chunk m

-- | output computed at run time
RuntimeHtml :: !(RuntimeSplice m Builder) -> Chunk m

-- | runtime action used only for its side-effect
RuntimeAction :: !(RuntimeSplice m ()) -> Chunk m
showChunk :: Chunk m -> String
isPureChunk :: Chunk m -> Bool

-- | Type alias for attribute splices. The function parameter is the value
--   of the bound attribute splice. The return value is a list of attribute
--   key/value pairs that get substituted in the place of the bound
--   attribute.
type AttrSplice m = Text -> RuntimeSplice m [(Text, Text)]

-- | Detailed information about a splice error.
data SpliceError
SpliceError :: [(TPath, Maybe FilePath, Text)] -> Maybe FilePath -> [Text] -> Node -> Text -> SpliceError
[spliceHistory] :: SpliceError -> [(TPath, Maybe FilePath, Text)]
[spliceTemplateFile] :: SpliceError -> Maybe FilePath
[visibleSplices] :: SpliceError -> [Text]
[contextNode] :: SpliceError -> Node
[spliceMsg] :: SpliceError -> Text

-- | Transform a SpliceError record to a Text message.
spliceErrorText :: SpliceError -> Text

-- | Exception type for splice compile errors. Wraps the original exception
--   and provides context. data (Exception e) =&gt; CompileException e =
--   CompileException
data CompileException
CompileException :: e -> [SpliceError] -> CompileException
[originalException] :: CompileException -> e
[exceptionContext] :: CompileException -> [SpliceError]

-- | Holds all the state information needed for template processing. You
--   will build a <tt>HeistState</tt> using <tt>initHeist</tt> and any of
--   Heist's <tt>HeistState -&gt; HeistState</tt> "filter" functions. Then
--   you use the resulting <tt>HeistState</tt> in calls to
--   <tt>renderTemplate</tt>.
--   
--   m is the runtime monad
data HeistState m
HeistState :: HashMap Text (HeistT m m Template) -> HashMap TPath DocumentFile -> HashMap Text (HeistT m IO (DList (Chunk m))) -> !(HashMap TPath ([Chunk m], MIMEType)) -> HashMap Text (AttrSplice m) -> Bool -> TPath -> [(TPath, Maybe FilePath, Text)] -> Int -> [DocType] -> Maybe FilePath -> KeyGen -> Bool -> Markup -> Text -> [SpliceError] -> Bool -> Int -> HeistState m

-- | A mapping of splice names to splice actions
[_spliceMap] :: HeistState m -> HashMap Text (HeistT m m Template)

-- | A mapping of template names to templates
[_templateMap] :: HeistState m -> HashMap TPath DocumentFile

-- | A mapping of splice names to splice actions
[_compiledSpliceMap] :: HeistState m -> HashMap Text (HeistT m IO (DList (Chunk m)))

-- | A mapping of template names to templates , _compiledTemplateMap ::
--   HashMap TPath (m Builder, MIMEType)
[_compiledTemplateMap] :: HeistState m -> !(HashMap TPath ([Chunk m], MIMEType))
[_attrSpliceMap] :: HeistState m -> HashMap Text (AttrSplice m)

-- | A flag to control splice recursion
[_recurse] :: HeistState m -> Bool

-- | The path to the template currently being processed.
[_curContext] :: HeistState m -> TPath

-- | Stack of the splices used.
[_splicePath] :: HeistState m -> [(TPath, Maybe FilePath, Text)]

-- | A counter keeping track of the current recursion depth to prevent
--   infinite loops.
[_recursionDepth] :: HeistState m -> Int

-- | The doctypes encountered during template processing.
[_doctypes] :: HeistState m -> [DocType]

-- | The full path to the current template's file on disk.
[_curTemplateFile] :: HeistState m -> Maybe FilePath

-- | A key generator used to produce new unique Promises.
[_keygen] :: HeistState m -> KeyGen

-- | Flag indicating whether we're in preprocessing mode. During
--   preprocessing, errors should stop execution and be reported. During
--   template rendering, it's better to skip the errors and render the
--   page.
[_preprocessingMode] :: HeistState m -> Bool

-- | This is needed because compiled templates are generated with a bunch
--   of calls to renderFragment rather than a single call to render.
[_curMarkup] :: HeistState m -> Markup

-- | A prefix for all splices (namespace ++ ":").
[_splicePrefix] :: HeistState m -> Text

-- | List of errors encountered during splice processing.
[_spliceErrors] :: HeistState m -> [SpliceError]

-- | Whether to throw an error when a tag wih the heist namespace does not
--   correspond to a bound splice. When not using a namespace, this flag is
--   ignored.
[_errorNotBound] :: HeistState m -> Bool
[_numNamespacedTags] :: HeistState m -> Int

-- | HeistT is the monad transformer used for splice processing. 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 <a>lift</a>.
--   
--   <tt>n</tt> is the runtime monad (the parameter to HeistState).
--   
--   <tt>m</tt> is the monad being run now. In this case, "now" is a
--   variable concept. The type <tt>HeistT n n</tt> means that "now" is
--   runtime. The type <tt>HeistT n IO</tt> means that "now" is
--   <tt>IO</tt>, and more importantly it is NOT runtime. In Heist, the
--   rule of thumb is that <tt>IO</tt> means load time and <tt>n</tt> means
--   runtime.
newtype HeistT n m a
HeistT :: (Node -> HeistState n -> m (a, HeistState n)) -> HeistT n m a
[runHeistT] :: HeistT n m a -> Node -> HeistState n -> m (a, HeistState n)

-- | Gets the names of all the templates defined in a HeistState.
templateNames :: HeistState m -> [TPath]

-- | Gets the names of all the templates defined in a HeistState.
compiledTemplateNames :: HeistState m -> [TPath]

-- | Gets the names of all the interpreted splices defined in a HeistState.
spliceNames :: HeistState m -> [Text]

-- | Gets the names of all the compiled splices defined in a HeistState.
compiledSpliceNames :: HeistState m -> [Text]

-- | Evaluates a template monad as a computation in the underlying monad.
evalHeistT :: (Monad m) => HeistT n m a -> Node -> HeistState n -> m a

-- | Functor instance

-- | Applicative instance

-- | Monad instance

-- | MonadIO instance

-- | MonadTrans instance

-- | MonadFix passthrough instance

-- | Alternative passthrough instance

-- | MonadPlus passthrough instance

-- | MonadState passthrough instance

-- | MonadReader passthrough instance

-- | Helper for MonadError instance.
_liftCatch :: (m (a, HeistState n) -> (e -> m (a, HeistState n)) -> m (a, HeistState n)) -> HeistT n m a -> (e -> HeistT n m a) -> HeistT n m a

-- | MonadError passthrough instance

-- | Helper for MonadCont instance.
_liftCallCC :: ((((a, HeistState n) -> m (b, HeistState n)) -> m (a, HeistState n)) -> m (a, HeistState n)) -> ((a -> HeistT n m b) -> HeistT n m a) -> HeistT n m a

-- | MonadCont passthrough instance

-- | 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;= childNodes</tt>
--   returns a list containing one <tt>TextNode</tt> containing part of
--   Hamlet's speech. <tt>liftM (getAttribute "author") getParamNode</tt>
--   would return <tt>Just "Shakespeare"</tt>.
getParamNode :: Monad m => HeistT n m Node

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

-- | HeistT's <tt>gets</tt>.
getsHS :: Monad m => (HeistState n -> r) -> HeistT n m r

-- | HeistT's <a>get</a>.
getHS :: Monad m => HeistT n m (HeistState n)

-- | HeistT's <a>put</a>.
putHS :: Monad m => HeistState n -> HeistT n m ()

-- | HeistT's <tt>modify</tt>.
modifyHS :: Monad m => (HeistState n -> HeistState n) -> HeistT n m ()

-- | Restores the HeistState. This function is almost like putHS except it
--   preserves the current doctypes and splice errors. You should use this
--   function instead of <tt>putHS</tt> 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.
restoreHS :: Monad m => HeistState n -> HeistT n m ()

-- | Abstracts the common pattern of running a HeistT computation with a
--   modified heist state.
localHS :: Monad m => (HeistState n -> HeistState n) -> HeistT n m a -> HeistT n m a

-- | Modifies the recursion depth.
modRecursionDepth :: Monad m => (Int -> Int) -> HeistT n m ()

-- | Increments the namespaced tag count
incNamespacedTags :: Monad m => HeistT n m ()

-- | AST to hold attribute parsing structure. This is necessary because
--   attoparsec doesn't support parsers running in another monad.
data AttAST
Literal :: Text -> AttAST
Ident :: Text -> AttAST
isIdent :: AttAST -> Bool
type TemplateRepo = HashMap TPath DocumentFile

-- | An IO action for getting a template repo from this location. By not
--   just using a directory path here, we support templates loaded from a
--   database, retrieved from the network, or anything else you can think
--   of.
type TemplateLocation = IO (Either [String] TemplateRepo)

-- | My lens creation function to avoid a dependency on lens.
lens :: Functor f => (t1 -> t) -> (t1 -> a -> b) -> (t -> f a) -> t1 -> f b

-- | The splices and templates Heist will use. To bind a splice simply
--   include it in the appropriate place here.
data SpliceConfig m
SpliceConfig :: Splices (Splice m) -> Splices (Splice IO) -> Splices (Splice m) -> Splices (AttrSplice m) -> [TemplateLocation] -> (TPath -> Bool) -> SpliceConfig m

-- | Interpreted splices are the splices that Heist has always had. They
--   return a list of nodes and are processed at runtime.
[_scInterpretedSplices] :: SpliceConfig m -> Splices (Splice m)

-- | Load time splices are like interpreted splices because they return a
--   list of nodes. But they are like compiled splices because they are
--   processed once at load time. All of Heist's built-in splices should be
--   used as load time splices.
[_scLoadTimeSplices] :: SpliceConfig m -> Splices (Splice IO)

-- | Compiled splices return a DList of Chunks and are processed at load
--   time to generate a runtime monad action that will be used to render
--   the template.
[_scCompiledSplices] :: SpliceConfig m -> Splices (Splice m)

-- | Attribute splices are bound to attribute names and return a list of
--   attributes.
[_scAttributeSplices] :: SpliceConfig m -> Splices (AttrSplice m)

-- | A list of all the locations that Heist should get its templates from.
[_scTemplateLocations] :: SpliceConfig m -> [TemplateLocation]

-- | Predicate function to control which templates to compile. Using
--   templates filtered out with this is still possible via callTemplate.
[_scCompiledTemplateFilter] :: SpliceConfig m -> TPath -> Bool

-- | Lens for interpreted splices :: Simple Lens (SpliceConfig m) (Splices
--   (I.Splice m))
scInterpretedSplices :: Functor f => (Splices (Splice m) -> f (Splices (Splice m))) -> SpliceConfig m -> f (SpliceConfig m)

-- | Lens for load time splices :: Simple Lens (SpliceConfig m) (Splices
--   (I.Splice IO))
scLoadTimeSplices :: Functor f => (Splices (Splice IO) -> f (Splices (Splice IO))) -> SpliceConfig m -> f (SpliceConfig m)

-- | Lens for complied splices :: Simple Lens (SpliceConfig m) (Splices
--   (C.Splice m))
scCompiledSplices :: Functor f => (Splices (Splice m) -> f (Splices (Splice m))) -> SpliceConfig m -> f (SpliceConfig m)

-- | Lens for attribute splices :: Simple Lens (SpliceConfig m) (Splices
--   (AttrSplice m))
scAttributeSplices :: Functor f => (Splices (AttrSplice m) -> f (Splices (AttrSplice m))) -> SpliceConfig m -> f (SpliceConfig m)

-- | Lens for template locations :: Simple Lens (SpliceConfig m)
--   [TemplateLocation]
scTemplateLocations :: Functor f => ([TemplateLocation] -> f [TemplateLocation]) -> SpliceConfig m -> f (SpliceConfig m)

-- | Lens for compiled template filter :: Simple Lens (SpliceConfig m)
--   (TBool -&gt; Bool)
scCompiledTemplateFilter :: Functor f => ((TPath -> Bool) -> f (TPath -> Bool)) -> SpliceConfig m -> f (SpliceConfig m)
data HeistConfig m
HeistConfig :: SpliceConfig m -> Text -> Bool -> HeistConfig m

-- | Splices and templates
[_hcSpliceConfig] :: HeistConfig m -> SpliceConfig m

-- | A namespace to use for all tags that are bound to splices. Use empty
--   string for no namespace.
[_hcNamespace] :: HeistConfig m -> Text

-- | Whether to throw an error when a tag wih the heist namespace does not
--   correspond to a bound splice. When not using a namespace, this flag is
--   ignored.
[_hcErrorNotBound] :: HeistConfig m -> Bool

-- | Lens for the SpliceConfig :: Simple Lens (HeistConfig m) (SpliceConfig
--   m)
hcSpliceConfig :: Functor f => ((SpliceConfig m) -> f (SpliceConfig m)) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for the namespace :: Simple Lens (HeistConfig m) Text
hcNamespace :: Functor f => (Text -> f Text) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for the namespace error flag :: Simple Lens (HeistConfig m) Bool
hcErrorNotBound :: Functor f => (Bool -> f Bool) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for interpreted splices :: Simple Lens (HeistConfig m) (Splices
--   (I.Splice m))
hcInterpretedSplices :: Functor f => (Splices (Splice m) -> f (Splices (Splice m))) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for load time splices :: Simple Lens (HeistConfig m) (Splices
--   (I.Splice IO))
hcLoadTimeSplices :: Functor f => (Splices (Splice IO) -> f (Splices (Splice IO))) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for compiled splices :: Simple Lens (HeistConfig m) (Splices
--   (C.Splice m))
hcCompiledSplices :: Functor f => (Splices (Splice m) -> f (Splices (Splice m))) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for attribute splices :: Simple Lens (HeistConfig m) (Splices
--   (AttrSplice m))
hcAttributeSplices :: Functor f => (Splices (AttrSplice m) -> f (Splices (AttrSplice m))) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for template locations :: Simple Lens (HeistConfig m)
--   [TemplateLocation]
hcTemplateLocations :: Functor f => ([TemplateLocation] -> f [TemplateLocation]) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for compiled template filter :: Simple Lens (SpliceConfig m)
--   (TBool -&gt; Bool)
hcCompiledTemplateFilter :: Functor f => ((TPath -> Bool) -> f (TPath -> Bool)) -> HeistConfig m -> f (HeistConfig m)
instance Data.Semigroup.Semigroup (Heist.Internal.Types.SpliceConfig m)
instance GHC.Base.Monoid (Heist.Internal.Types.SpliceConfig m)

module Heist.Splices.Apply

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

-- | Default attribute name for the apply tag.
applyAttr :: Text
rawApply :: (Monad n) => Text -> [Node] -> Maybe FilePath -> TPath -> [Node] -> Splice n

-- | Applies a template as if the supplied nodes were the children of the
--   <a>apply</a> tag.
applyNodes :: Monad n => Template -> Text -> Splice n

-- | Implementation of the apply splice.
applyImpl :: Monad n => Splice n

-- | This splice crashes with an error message. Its purpose is to provide a
--   load-time warning to anyone still using the old content tag in their
--   templates. In Heist 0.10, tho content tag was replaced by two separate
--   apply-content and bind-content tags used by the apply and bind splices
--   respectively.
deprecatedContentCheck :: Monad m => Splice m

module Heist.Splices.Bind

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

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

-- | Implementation of the bind splice.
bindImpl :: Monad n => Splice n

module Heist.Splices.BindStrict

-- | Default name for the bind splice.
bindStrictTag :: Text

-- | Implementation of the bind splice.
bindStrictImpl :: Monad n => Splice n


-- | The "cache" splice ensures that its contents are cached and only
--   evaluated periodically. The cached contents are returned every time
--   the splice is referenced.
--   
--   Use the ttl attribute to set the amount of time between reloads. The
--   ttl value should be a positive integer followed by a single character
--   specifying the units. Valid units are a single letter abbreviation for
--   one of seconds, minutes, hours, days, and weeks. If the ttl string is
--   invalid or the ttl attribute is not specified, the cache is never
--   refreshed unless explicitly cleared with clearCacheTagState. The
--   compiled splice version of the cache tag does not require a cache tag
--   state, so clearCacheTagState will not work for compiled cache tags.
module Heist.Splices.Cache

-- | State for storing cache tag information
data CacheTagState

-- | This is the splice that actually does the work. You should bind it to
--   the same tag name as you bound the splice returned by mkCacheTag
--   otherwise it won't work and you'll get runtime errors.
cacheImpl :: (MonadIO n) => CacheTagState -> Splice n

-- | This is the compiled splice version of cacheImpl.
cacheImplCompiled :: (MonadIO n) => CacheTagState -> Splice n

-- | Returns items necessary to set up a "cache" tag. The cache tag cannot
--   be bound automatically with the other default Heist tags. This is
--   because this function also returns CacheTagState, so the user will be
--   able to clear it with the <a>clearCacheTagState</a> function.
--   
--   This function returns a splice and a CacheTagState. The splice is of
--   type <tt>Splice IO</tt> because it has to be bound as a load time
--   preprocessing splice. Haskell's type system won't allow you to screw
--   up and pass this splice as the wrong argument to initHeist.
mkCacheTag :: IO (Splice IO, CacheTagState)

-- | Clears the cache tag state.
clearCacheTagState :: CacheTagState -> IO ()

module Heist.Splices.Html

-- | Name for the html splice.
htmlTag :: Text

-- | The html splice runs all children and then traverses the returned node
--   forest removing all head nodes. Then it merges them all and prepends
--   it to the html tag's child list.
htmlImpl :: Monad n => Splice n

-- | Extracts all heads from a node tree.
extractHeads :: Node -> ([Node], Maybe Node)

module Heist.Splices.Ignore

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

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

module Heist.Splices.Json

-- | This splice binds convenience tags for the given JSON (or
--   JSON-convertible) value and runs the tag's child nodes using the new
--   bindings.
--   
--   <i>Tags bound when you pass in an object</i>
--   
--   Tags bound for an object looking like this:
--   
--   <pre>
--   { "k_1": v_1, ..., "k_N": v_N }
--   </pre>
--   
--   <tt>&lt;value:{k_i}&gt;</tt> -- treats v_i as text
--   <tt>&lt;snippet:{k_i}&gt;</tt> -- treats v_i as HTML
--   <tt>&lt;with:{k_i}&gt;</tt> -- explodes v_i and runs its children
--   
--   <tt>&lt;value var="foo.bar.baz"/&gt;</tt> -- walks the JSON tree to
--   find "foo.bar.baz", and interprets it as a string <tt>&lt;snippet
--   var="foo.bar.baz"/&gt;</tt> <tt>&lt;with
--   var="foo.bar.baz"&gt;...&lt;with&gt;</tt>
--   
--   <i>Tags bound when you pass in anything else</i>
--   
--   <tt>&lt;value/&gt;</tt> -- the given JSON value, as a string
--   <tt>&lt;snippet/&gt;</tt> -- the given JSON value, parsed and spliced
--   in as HTML
bindJson :: (ToJSON a, Monad n) => a -> Splice n


-- | The "markdown" splice formats markdown content as HTML and inserts it
--   into the document.
--   
--   If the file attribute is present the contents of the tag is ignored
--   and the file specified is converted to HTML.
--   
--   Otherwise the non-markup children of the tag are processed as markdown
--   and converted to HTML.
--   
--   This splice requires that the "pandoc" executable is in your path.
--   
--   You can add custom pandoc splice with <a>pandocSplice</a>. It is not
--   limited to markdown input, and can process anything pandoc can.
--   
--   For example you can create a page with generated table of contents,
--   using heist template as pandoc template.
--   
--   <pre>
--   &lt;!-- _wrap.tpl --&gt;
--   &lt;html&gt;
--     &lt;head&gt; &lt;title&gt; &lt;pageTitle/&gt; &lt;/title&gt; &lt;/head&gt;
--   
--     &lt;div class="nav"&gt; &lt;pageToc/&gt; &lt;/div&gt;
--     &lt;apply-content/&gt;
--   &lt;/html&gt;
--   </pre>
--   
--   And pandoc template, which would bind <tt>pageTitle</tt> and
--   <tt>pageToc</tt> splices and applies "_wrap" template.
--   
--   <pre>
--   &lt;!-- _pandoc.tpl --&gt;
--   &lt;apply template="_wrap.tpl"&gt;
--     &lt;bind tag="pageTitle"&gt; $title$&lt;/bind&gt;
--     &lt;bind tag="pageToc"&gt; $toc$&lt;/bind&gt;
--     $body$
--   &lt;/apply&gt;
--   </pre>
--   
--   Bind splice pandoc splice. Set it to not wrap in div, or it will break
--   html from _wrap.tpl
--   
--   <pre>
--   splices = "docmarkdown" ## pandocSplice opts
--     where
--       opts = setPandocArgs  ["-S", "--no-wrap", "--toc"
--                             , "--standalone"
--                             , "--template", "_pandoc.tpl"
--                             , "--html5"]
--              $ setPandocWrapDiv Nothing
--              $ defaultPandocOptions
--   </pre>
--   
--   And then use it to render your markdown file
--   
--   <pre>
--   &lt;!-- apidocs.tpl --&gt;
--   &lt;DOCTYPE html&gt;
--   &lt;html lang="en"&gt;
--   &lt;head&gt;
--     &lt;link href="/static/css/site.css rel="stylesheet"&gt;
--   &lt;/head&gt;
--   &lt;body&gt;
--     &lt;apply template="_navbar.tpl" /&gt;
--     &lt;docmarkdown file="apidocs.md"/&gt;
--   &lt;/body&gt;
--   </pre>
module Heist.Splices.Markdown
data PandocMissingException
data MarkdownException
data NoMarkdownFileException

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

-- | Default markdown splice with executable "pandoc"
markdownSplice :: MonadIO m => Splice m

-- | Implementation of the markdown splice.
pandocSplice :: MonadIO m => PandocOptions -> Splice m
data PandocOptions

-- | Default options
defaultPandocOptions :: PandocOptions

-- | Name of pandoc executable
setPandocExecutable :: FilePath -> PandocOptions -> PandocOptions

-- | Arguments passed to pandoc
setPandocArgs :: [String] -> PandocOptions -> PandocOptions

-- | Base directory for input files, defaults to current template dir
setPandocBaseDir :: Maybe FilePath -> PandocOptions -> PandocOptions

-- | Wrap pandoc output in div with class. Appends node attributes to div
--   and appends class to ones specified on node.
setPandocWrapDiv :: Maybe Text -> PandocOptions -> PandocOptions
pandocExecutable :: Functor f => (FilePath -> f FilePath) -> PandocOptions -> f PandocOptions
pandocArgs :: Functor f => ([String] -> f [String]) -> PandocOptions -> f PandocOptions
pandocBaseDir :: Functor f => (Maybe FilePath -> f (Maybe FilePath)) -> PandocOptions -> f PandocOptions
pandocWrapDiv :: Functor f => (Maybe Text -> f (Maybe Text)) -> PandocOptions -> f PandocOptions
instance GHC.Show.Show Heist.Splices.Markdown.PandocOptions
instance GHC.Classes.Ord Heist.Splices.Markdown.PandocOptions
instance GHC.Classes.Eq Heist.Splices.Markdown.PandocOptions
instance GHC.Show.Show Heist.Splices.Markdown.NoMarkdownFileException
instance GHC.Exception.Exception Heist.Splices.Markdown.NoMarkdownFileException
instance GHC.Show.Show Heist.Splices.Markdown.MarkdownException
instance GHC.Exception.Exception Heist.Splices.Markdown.MarkdownException
instance GHC.Show.Show Heist.Splices.Markdown.PandocMissingException
instance GHC.Exception.Exception Heist.Splices.Markdown.PandocMissingException

module Heist.Splices

-- | Run the splice contents if given condition is True, make splice
--   disappear if not.
ifISplice :: Monad m => Bool -> Splice m

-- | Function for constructing if splices that use a runtime predicate
--   function to determine whether the node's children should be rendered.
ifCSplice :: Monad m => (t -> Bool) -> RuntimeSplice m t -> Splice m

-- | Implements an if/then/else conditional splice. It splits its children
--   around the &lt;else/&gt; element to get the markup to be used for the
--   two cases.
ifElseISplice :: Monad m => Bool -> Splice m

-- | Implements an if/then/else conditional splice. It splits its children
--   around the &lt;else/&gt; element to get the markup to be used for the
--   two cases.
ifElseCSplice :: Monad m => Bool -> Splice m


-- | This module defines the core data types used by Heist. In practice you
--   will also want to import one or both of <a>Heist.Compiled</a> or
--   <a>Heist.Interpreted</a> to get functions needed for writing splices.
--   
--   The Heist template system allows you to build custom HTML and XML
--   based markup languages. With Heist you can define your own
--   domain-specific tags implemented with Haskell and use them in your
--   templates.
module Heist

-- | Loads templates from disk. This function returns just a template map
--   so you can load multiple directories and combine the maps before
--   initializing your HeistState.
loadTemplates :: FilePath -> IO (Either [String] TemplateRepo)

-- | Reloads all the templates an an existing TemplateRepo.
reloadTemplates :: TemplateRepo -> IO (Either [String] TemplateRepo)

-- | Adds a path prefix to a templates in a map returned by loadTemplates.
--   If you want to add multiple levels of directories, separate them with
--   slashes as in "foo/bar". Using an empty string as a path prefix will
--   leave the map unchanged.
addTemplatePathPrefix :: ByteString -> TemplateRepo -> TemplateRepo

-- | This is the main Heist initialization function. You pass in a map of
--   all templates and all of your splices and it constructs and returns a
--   HeistState.
--   
--   We don't provide functions to add either type of loadtime splices to
--   your HeistState after initHeist because it doesn't make any sense
--   unless you re-initialize all templates with the new splices. If you
--   add any old-style runtime heist splices after calling this function,
--   they will still work fine if you use Heist.Interpreted.renderTemplate.
--   If you add any templates later, then those templates will be available
--   for interpreted rendering, but not for compiled rendering.
--   
--   In the past you could add templates to your HeistState after
--   initialization using its Monoid instance. Due to implementation
--   details, this is no longer possible. All of your templates must be
--   known when you call this function.
initHeist :: Monad n => HeistConfig n -> IO (Either [String] (HeistState n))

-- | Wrapper around initHeist that also sets up a cache tag. It sets up
--   both compiled and interpreted versions of the cache tag splices. If
--   you need to configure the cache tag differently than how this function
--   does it, you will still probably want to pattern your approach after
--   this function's implementation.
initHeistWithCacheTag :: MonadIO n => HeistConfig n -> IO (Either [String] (HeistState n, CacheTagState))

-- | The built-in set of static splices. All the splices that used to be
--   enabled by default are included here. To get the normal Heist behavior
--   you should include these in the scLoadTimeSplices list in your
--   SpliceConfig. If you are using interpreted splice mode, then you might
--   also want to bind the <a>deprecatedContentCheck</a> splice to the
--   content tag as a load time splice.
defaultInterpretedSplices :: MonadIO m => Splices (Splice m)

-- | The built-in set of splices that you should use in compiled splice
--   mode. This list includes everything from
--   <a>defaultInterpretedSplices</a> plus a splice for the content tag
--   that errors out when it sees any instance of the old content tag,
--   which has now been moved to two separate tags called apply-content and
--   bind-content.
defaultLoadTimeSplices :: MonadIO m => Splices (Splice m)

-- | An empty HeistConfig that uses the "h" namespace with error checking
--   turned on.
emptyHeistConfig :: HeistConfig m

-- | The splices and templates Heist will use. To bind a splice simply
--   include it in the appropriate place here.
data SpliceConfig m
data HeistConfig m
type TemplateRepo = HashMap TPath DocumentFile

-- | An IO action for getting a template repo from this location. By not
--   just using a directory path here, we support templates loaded from a
--   database, retrieved from the network, or anything else you can think
--   of.
type TemplateLocation = IO (Either [String] TemplateRepo)

-- | A <a>Template</a> 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 document fragments that may not have a
--   single root.
type Template = [Node]

-- | Reversed list of directories. This holds the path to the template
--   currently being processed.
type TPath = [ByteString]

-- | MIME Type. The type alias is here to make the API clearer.
type MIMEType = ByteString

-- | Holds data about templates read from disk.
data DocumentFile
DocumentFile :: Document -> Maybe FilePath -> DocumentFile
[dfDoc] :: DocumentFile -> Document
[dfFile] :: DocumentFile -> Maybe FilePath

-- | Type alias for attribute splices. The function parameter is the value
--   of the bound attribute splice. The return value is a list of attribute
--   key/value pairs that get substituted in the place of the bound
--   attribute.
type AttrSplice m = Text -> RuntimeSplice m [(Text, Text)]

-- | Monad used for runtime splice execution.
data RuntimeSplice m a

-- | Opaque type representing pieces of output from compiled splices.
data Chunk m

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

-- | Detailed information about a splice error.
data SpliceError
SpliceError :: [(TPath, Maybe FilePath, Text)] -> Maybe FilePath -> [Text] -> Node -> Text -> SpliceError
[spliceHistory] :: SpliceError -> [(TPath, Maybe FilePath, Text)]
[spliceTemplateFile] :: SpliceError -> Maybe FilePath
[visibleSplices] :: SpliceError -> [Text]
[contextNode] :: SpliceError -> Node
[spliceMsg] :: SpliceError -> Text

-- | Exception type for splice compile errors. Wraps the original exception
--   and provides context. data (Exception e) =&gt; CompileException e =
--   CompileException
data CompileException
CompileException :: e -> [SpliceError] -> CompileException
[originalException] :: CompileException -> e
[exceptionContext] :: CompileException -> [SpliceError]

-- | HeistT is the monad transformer used for splice processing. 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 <a>lift</a>.
--   
--   <tt>n</tt> is the runtime monad (the parameter to HeistState).
--   
--   <tt>m</tt> is the monad being run now. In this case, "now" is a
--   variable concept. The type <tt>HeistT n n</tt> means that "now" is
--   runtime. The type <tt>HeistT n IO</tt> means that "now" is
--   <tt>IO</tt>, and more importantly it is NOT runtime. In Heist, the
--   rule of thumb is that <tt>IO</tt> means load time and <tt>n</tt> means
--   runtime.
data HeistT n m a

-- | Lens for interpreted splices :: Simple Lens (SpliceConfig m) (Splices
--   (I.Splice m))
scInterpretedSplices :: Functor f => (Splices (Splice m) -> f (Splices (Splice m))) -> SpliceConfig m -> f (SpliceConfig m)

-- | Lens for load time splices :: Simple Lens (SpliceConfig m) (Splices
--   (I.Splice IO))
scLoadTimeSplices :: Functor f => (Splices (Splice IO) -> f (Splices (Splice IO))) -> SpliceConfig m -> f (SpliceConfig m)

-- | Lens for complied splices :: Simple Lens (SpliceConfig m) (Splices
--   (C.Splice m))
scCompiledSplices :: Functor f => (Splices (Splice m) -> f (Splices (Splice m))) -> SpliceConfig m -> f (SpliceConfig m)

-- | Lens for attribute splices :: Simple Lens (SpliceConfig m) (Splices
--   (AttrSplice m))
scAttributeSplices :: Functor f => (Splices (AttrSplice m) -> f (Splices (AttrSplice m))) -> SpliceConfig m -> f (SpliceConfig m)

-- | Lens for template locations :: Simple Lens (SpliceConfig m)
--   [TemplateLocation]
scTemplateLocations :: Functor f => ([TemplateLocation] -> f [TemplateLocation]) -> SpliceConfig m -> f (SpliceConfig m)

-- | Lens for compiled template filter :: Simple Lens (SpliceConfig m)
--   (TBool -&gt; Bool)
scCompiledTemplateFilter :: Functor f => ((TPath -> Bool) -> f (TPath -> Bool)) -> SpliceConfig m -> f (SpliceConfig m)

-- | Lens for the SpliceConfig :: Simple Lens (HeistConfig m) (SpliceConfig
--   m)
hcSpliceConfig :: Functor f => ((SpliceConfig m) -> f (SpliceConfig m)) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for the namespace :: Simple Lens (HeistConfig m) Text
hcNamespace :: Functor f => (Text -> f Text) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for the namespace error flag :: Simple Lens (HeistConfig m) Bool
hcErrorNotBound :: Functor f => (Bool -> f Bool) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for interpreted splices :: Simple Lens (HeistConfig m) (Splices
--   (I.Splice m))
hcInterpretedSplices :: Functor f => (Splices (Splice m) -> f (Splices (Splice m))) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for load time splices :: Simple Lens (HeistConfig m) (Splices
--   (I.Splice IO))
hcLoadTimeSplices :: Functor f => (Splices (Splice IO) -> f (Splices (Splice IO))) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for compiled splices :: Simple Lens (HeistConfig m) (Splices
--   (C.Splice m))
hcCompiledSplices :: Functor f => (Splices (Splice m) -> f (Splices (Splice m))) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for attribute splices :: Simple Lens (HeistConfig m) (Splices
--   (AttrSplice m))
hcAttributeSplices :: Functor f => (Splices (AttrSplice m) -> f (Splices (AttrSplice m))) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for template locations :: Simple Lens (HeistConfig m)
--   [TemplateLocation]
hcTemplateLocations :: Functor f => ([TemplateLocation] -> f [TemplateLocation]) -> HeistConfig m -> f (HeistConfig m)

-- | Lens for compiled template filter :: Simple Lens (SpliceConfig m)
--   (TBool -&gt; Bool)
hcCompiledTemplateFilter :: Functor f => ((TPath -> Bool) -> f (TPath -> Bool)) -> HeistConfig m -> f (HeistConfig m)

-- | Gets the names of all the templates defined in a HeistState.
templateNames :: HeistState m -> [TPath]

-- | Gets the names of all the templates defined in a HeistState.
compiledTemplateNames :: HeistState m -> [TPath]

-- | Returns <a>True</a> if the given template can be found in the heist
--   state.
hasTemplate :: ByteString -> HeistState n -> Bool

-- | Gets the names of all the interpreted splices defined in a HeistState.
spliceNames :: HeistState m -> [Text]

-- | Gets the names of all the compiled splices defined in a HeistState.
compiledSpliceNames :: HeistState m -> [Text]

-- | Evaluates a template monad as a computation in the underlying monad.
evalHeistT :: (Monad m) => HeistT n m a -> Node -> HeistState n -> m a

-- | 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;= childNodes</tt>
--   returns a list containing one <tt>TextNode</tt> containing part of
--   Hamlet's speech. <tt>liftM (getAttribute "author") getParamNode</tt>
--   would return <tt>Just "Shakespeare"</tt>.
getParamNode :: Monad m => HeistT n m Node

-- | Gets the current context
getContext :: Monad m => HeistT n m TPath

-- | Gets the full path to the file holding the template currently being
--   processed. Returns Nothing if the template is not associated with a
--   file on disk or if there is no template being processed.
getTemplateFilePath :: Monad m => HeistT n m (Maybe FilePath)

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

-- | HeistT's <tt>gets</tt>.
getsHS :: Monad m => (HeistState n -> r) -> HeistT n m r

-- | HeistT's <a>get</a>.
getHS :: Monad m => HeistT n m (HeistState n)

-- | HeistT's <a>put</a>.
putHS :: Monad m => HeistState n -> HeistT n m ()

-- | HeistT's <tt>modify</tt>.
modifyHS :: Monad m => (HeistState n -> HeistState n) -> HeistT n m ()

-- | Restores the HeistState. This function is almost like putHS except it
--   preserves the current doctypes and splice errors. You should use this
--   function instead of <tt>putHS</tt> 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.
restoreHS :: Monad m => HeistState n -> HeistT n m ()

-- | Abstracts the common pattern of running a HeistT computation with a
--   modified heist state.
localHS :: Monad m => (HeistState n -> HeistState n) -> HeistT n m a -> HeistT n m a

-- | Reads an HTML template from disk.
getDoc :: String -> IO (Either String DocumentFile)

-- | Reads an XML template from disk.
getXMLDoc :: String -> IO (Either String DocumentFile)

-- | Adds an error message to the list of splice processing errors.
tellSpliceError :: Monad m => Text -> HeistT n m ()

-- | Transform a SpliceError record to a Text message.
spliceErrorText :: SpliceError -> Text

-- | If Heist is running in fail fast mode, then this function will throw
--   an exception with the second argument as the error message. Otherwise,
--   the first argument will be executed to represent silent failure.
--   
--   This behavior allows us to fail quickly if an error crops up during
--   load-time splice processing or degrade more gracefully if the error
--   occurs while a user request is being processed.
orError :: Monad m => HeistT n m b -> String -> HeistT n m b

-- | Convenient type alies for splices.
type Splices s = MapSyntax Text s


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

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

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

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

-- | Gets the <a>HeistState</a> from a TemplateDirectory.
getDirectoryHS :: (MonadIO n) => TemplateDirectory n -> IO (HeistState n)

-- | Clears the TemplateDirectory's cache tag state.
getDirectoryCTS :: TemplateDirectory n -> IO CacheTagState

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