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


-- | Mustache templates for Haskell
--   
--   Mustache templates for Haskell.
--   
--   Based on <tt>stache</tt> library, which uses <tt>megaparsec</tt>. This
--   library uses <tt>parsec</tt>, thus the name: <tt>microstache</tt>.
@package microstache
@version 1


-- | Types used by the package. You don't usually need to import the
--   module, because <a>Text.Microstache</a> re-exports everything you may
--   need, import that module instead.
module Text.Microstache.Type

-- | Mustache template as name of “top-level” template and a collection of
--   all available templates (partials).
--   
--   <a>Template</a> is a <a>Semigroup</a>. This means that you can combine
--   <a>Template</a>s (and their caches) using the
--   <tt>(<a>&lt;&gt;</a>)</tt> operator, the resulting <a>Template</a>
--   will have the same currently selected template as the left one. Union
--   of caches is also left-biased.
data Template
Template :: PName -> Map PName [Node] -> Template

-- | Name of currently “selected” template (top-level one).
[templateActual] :: Template -> PName

-- | Collection of all templates that are available for interpolation (as
--   partials). The top-level one is also contained here and the “focus”
--   can be switched easily by modifying <a>templateActual</a>.
[templateCache] :: Template -> Map PName [Node]

-- | Structural element of template.
data Node

-- | Plain text contained between tags
TextBlock :: Text -> Node

-- | HTML-escaped variable
EscapedVar :: Key -> Node

-- | Unescaped variable
UnescapedVar :: Key -> Node

-- | Mustache section
Section :: Key -> [Node] -> Node

-- | Inverted section
InvertedSection :: Key -> [Node] -> Node

-- | Partial with indentation level (<a>Nothing</a> means it was inlined)
Partial :: PName -> (Maybe Word) -> Node

-- | Identifier for values to interpolate.
--   
--   The representation is the following:
--   
--   <ul>
--   <li><tt>[]</tt> — empty list means implicit iterators;</li>
--   <li><tt>[text]</tt> — single key is a normal identifier;</li>
--   <li><tt>[text1, text2]</tt> — multiple keys represent dotted
--   names.</li>
--   </ul>
newtype Key
Key :: [Text] -> Key
[unKey] :: Key -> [Text]

-- | Pretty-print a key, this is helpful, for example, if you want to
--   display an error message.
showKey :: Key -> Text

-- | Identifier for partials. Note that with the <tt>OverloadedStrings</tt>
--   extension you can use just string literals to create values of this
--   type.
newtype PName
PName :: Text -> PName
[unPName] :: PName -> Text

-- | Exception that is thrown when parsing of a template has failed or
--   referenced values were not provided.
data MustacheException

-- | Template parser has failed. This contains the parse error.
--   
--   <i>Before version 0.2.0 it was called <a>MustacheException</a>.</i>
MustacheParserException :: ParseError -> MustacheException

-- | A referenced value was not provided. The exception provides info about
--   partial in which the issue happened <a>PName</a> and name of the
--   missing key <a>Key</a>.
MustacheRenderException :: PName -> Key -> MustacheException
instance GHC.Generics.Generic Text.Microstache.Type.MustacheException
instance GHC.Show.Show Text.Microstache.Type.MustacheException
instance GHC.Classes.Eq Text.Microstache.Type.MustacheException
instance GHC.Generics.Generic Text.Microstache.Type.Template
instance Data.Data.Data Text.Microstache.Type.Template
instance GHC.Show.Show Text.Microstache.Type.Template
instance GHC.Classes.Ord Text.Microstache.Type.Template
instance GHC.Classes.Eq Text.Microstache.Type.Template
instance GHC.Generics.Generic Text.Microstache.Type.Node
instance Data.Data.Data Text.Microstache.Type.Node
instance GHC.Show.Show Text.Microstache.Type.Node
instance GHC.Classes.Ord Text.Microstache.Type.Node
instance GHC.Classes.Eq Text.Microstache.Type.Node
instance GHC.Generics.Generic Text.Microstache.Type.PName
instance Data.Data.Data Text.Microstache.Type.PName
instance GHC.Show.Show Text.Microstache.Type.PName
instance GHC.Classes.Ord Text.Microstache.Type.PName
instance GHC.Classes.Eq Text.Microstache.Type.PName
instance GHC.Generics.Generic Text.Microstache.Type.Key
instance Data.Data.Data Text.Microstache.Type.Key
instance GHC.Base.Monoid Text.Microstache.Type.Key
instance Data.Semigroup.Semigroup Text.Microstache.Type.Key
instance GHC.Show.Show Text.Microstache.Type.Key
instance GHC.Classes.Ord Text.Microstache.Type.Key
instance GHC.Classes.Eq Text.Microstache.Type.Key
instance Data.Semigroup.Semigroup Text.Microstache.Type.Template
instance Control.DeepSeq.NFData Text.Microstache.Type.Key
instance Data.String.IsString Text.Microstache.Type.PName
instance Control.DeepSeq.NFData Text.Microstache.Type.PName
instance GHC.Exception.Exception Text.Microstache.Type.MustacheException


-- | Megaparsec parser for Mustache templates. You don't usually need to
--   import the module, because <a>Text.Microstache</a> re-exports
--   everything you may need, import that module instead.
module Text.Microstache.Parser

-- | Parse given Mustache template.
parseMustache :: FilePath -> Text -> Either ParseError [Node]


-- | Functions for rendering Mustache templates. You don't usually need to
--   import the module, because <a>Text.Microstache</a> re-exports
--   everything you may need, import that module instead.
module Text.Microstache.Render

-- | Render a Mustache <a>Template</a> using Aeson's <a>Value</a> to get
--   actual values for interpolation.
--   
--   As of version 0.2.0, if referenced values are missing (which almost
--   always indicates some sort of mistake), <a>MustacheRenderException</a>
--   will be thrown. The included <a>Key</a> will indicate full path to
--   missing value and <a>PName</a> will contain the name of active
--   partial.
renderMustache :: Template -> Value -> Text


-- | Mustache <a>Template</a> creation from file or a <a>Text</a> value.
--   You don't usually need to import the module, because
--   <a>Text.Microstache</a> re-exports everything you may need, import
--   that module instead.
module Text.Microstache.Compile

-- | Compile all templates in specified directory and select one. Template
--   files should have extension <tt>mustache</tt>, (e.g.
--   <tt>foo.mustache</tt>) to be recognized. This function <i>does not</i>
--   scan the directory recursively.
--   
--   The action can throw the same exceptions as
--   <a>getDirectoryContents</a>, and <a>readFile</a>.
compileMustacheDir :: PName -> FilePath -> IO Template

-- | Return a list of templates found in given directory. The returned
--   paths are absolute.
getMustacheFilesInDir :: FilePath -> IO [FilePath]

-- | Compile single Mustache template and select it.
--   
--   The action can throw the same exceptions as <a>readFile</a>.
compileMustacheFile :: FilePath -> IO Template

-- | Compile Mustache template from a lazy <a>Text</a> value. The cache
--   will contain only this template named according to given <a>PName</a>.
compileMustacheText :: PName -> Text -> Either ParseError Template


-- | This is a Haskell implementation of Mustache templates. The
--   implementation conforms to the version 1.1.3 of official Mustache
--   specification <a>https://github.com/mustache/spec</a>. It is extremely
--   simple and straightforward to use with minimal but complete API —
--   three functions to compile templates (from directory, from file, and
--   from lazy text) and one to render them.
--   
--   The implementation uses the Megaparsec parsing library to parse the
--   templates which results in superior quality of error messages.
--   
--   For rendering you only need to create Aeson's <a>Value</a> where you
--   put the data to interpolate. Since the library re-uses Aeson's
--   instances and most data types in Haskell ecosystem are instances of
--   classes like <a>ToJSON</a>, the whole process is very simple for end
--   user.
--   
--   Template Haskell helpers for compilation of templates at compile time
--   are available in the <a>Text.Microstache.Compile.TH</a> module. The
--   helpers are currently available only for GHC 8 users though.
--   
--   One feature that is not currently supported is lambdas. The feature is
--   marked as optional in the spec and can be emulated via processing of
--   parsed template representation. The decision to drop lambdas is
--   intentional, for the sake of simplicity and better integration with
--   Aeson.
--   
--   Here is an example of basic usage:
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   module Main (main) where
--   
--   import Data.Aeson
--   import Data.Text
--   import Text.Megaparsec
--   import Text.Microstache
--   import qualified Data.Text.Lazy.IO as TIO
--   
--   main :: IO ()
--   main = do
--     let res = compileMustacheText "foo"
--           "Hi, {{name}}! You have:\n{{#things}}\n  * {{.}}\n{{/things}}\n"
--     case res of
--       Left err -&gt; putStrLn (parseErrorPretty err)
--       Right template -&gt; TIO.putStr $ renderMustache template $ object
--         [ "name"   .= ("John" :: Text)
--         , "things" .= ["pen" :: Text, "candle", "egg"]
--         ]
--   </pre>
--   
--   If I run the program, it prints the following:
--   
--   <pre>
--   Hi, John! You have:
--     * pen
--     * candle
--     * egg
--   </pre>
--   
--   For more information about Mustache templates the following links may
--   be helpful:
--   
--   <ul>
--   <li>The official Mustache site:
--   <a>https://mustache.github.io/</a></li>
--   <li>The manual: <a>https://mustache.github.io/mustache.5.html</a></li>
--   <li>The specification: <a>https://github.com/mustache/spec</a></li>
--   <li>Stack Builders Stache tutorial:
--   <a>https://www.stackbuilders.com/tutorials/haskell/mustache-templates/</a></li>
--   </ul>
module Text.Microstache

-- | Mustache template as name of “top-level” template and a collection of
--   all available templates (partials).
--   
--   <a>Template</a> is a <a>Semigroup</a>. This means that you can combine
--   <a>Template</a>s (and their caches) using the
--   <tt>(<a>&lt;&gt;</a>)</tt> operator, the resulting <a>Template</a>
--   will have the same currently selected template as the left one. Union
--   of caches is also left-biased.
data Template
Template :: PName -> Map PName [Node] -> Template

-- | Name of currently “selected” template (top-level one).
[templateActual] :: Template -> PName

-- | Collection of all templates that are available for interpolation (as
--   partials). The top-level one is also contained here and the “focus”
--   can be switched easily by modifying <a>templateActual</a>.
[templateCache] :: Template -> Map PName [Node]

-- | Structural element of template.
data Node

-- | Plain text contained between tags
TextBlock :: Text -> Node

-- | HTML-escaped variable
EscapedVar :: Key -> Node

-- | Unescaped variable
UnescapedVar :: Key -> Node

-- | Mustache section
Section :: Key -> [Node] -> Node

-- | Inverted section
InvertedSection :: Key -> [Node] -> Node

-- | Partial with indentation level (<a>Nothing</a> means it was inlined)
Partial :: PName -> (Maybe Word) -> Node

-- | Identifier for values to interpolate.
--   
--   The representation is the following:
--   
--   <ul>
--   <li><tt>[]</tt> — empty list means implicit iterators;</li>
--   <li><tt>[text]</tt> — single key is a normal identifier;</li>
--   <li><tt>[text1, text2]</tt> — multiple keys represent dotted
--   names.</li>
--   </ul>
newtype Key
Key :: [Text] -> Key
[unKey] :: Key -> [Text]

-- | Identifier for partials. Note that with the <tt>OverloadedStrings</tt>
--   extension you can use just string literals to create values of this
--   type.
newtype PName
PName :: Text -> PName
[unPName] :: PName -> Text

-- | Exception that is thrown when parsing of a template has failed or
--   referenced values were not provided.
data MustacheException

-- | Template parser has failed. This contains the parse error.
--   
--   <i>Before version 0.2.0 it was called <a>MustacheException</a>.</i>
MustacheParserException :: ParseError -> MustacheException

-- | A referenced value was not provided. The exception provides info about
--   partial in which the issue happened <a>PName</a> and name of the
--   missing key <a>Key</a>.
MustacheRenderException :: PName -> Key -> MustacheException

-- | Compile all templates in specified directory and select one. Template
--   files should have extension <tt>mustache</tt>, (e.g.
--   <tt>foo.mustache</tt>) to be recognized. This function <i>does not</i>
--   scan the directory recursively.
--   
--   The action can throw the same exceptions as
--   <a>getDirectoryContents</a>, and <a>readFile</a>.
compileMustacheDir :: PName -> FilePath -> IO Template

-- | Compile single Mustache template and select it.
--   
--   The action can throw the same exceptions as <a>readFile</a>.
compileMustacheFile :: FilePath -> IO Template

-- | Compile Mustache template from a lazy <a>Text</a> value. The cache
--   will contain only this template named according to given <a>PName</a>.
compileMustacheText :: PName -> Text -> Either ParseError Template

-- | Render a Mustache <a>Template</a> using Aeson's <a>Value</a> to get
--   actual values for interpolation.
--   
--   As of version 0.2.0, if referenced values are missing (which almost
--   always indicates some sort of mistake), <a>MustacheRenderException</a>
--   will be thrown. The included <a>Key</a> will indicate full path to
--   missing value and <a>PName</a> will contain the name of active
--   partial.
renderMustache :: Template -> Value -> Text
