-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Mustache templates for Haskell -- -- Mustache templates for Haskell. -- -- Based on stache library, which uses megaparsec. This -- library uses parsec, thus the name: microstache. @package microstache @version 1 -- | Types used by the package. You don't usually need to import the -- module, because Text.Microstache 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). -- -- Template is a Semigroup. This means that you can combine -- Templates (and their caches) using the -- (<>) operator, the resulting Template -- 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 templateActual. [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 (Nothing means it was inlined) Partial :: PName -> (Maybe Word) -> Node -- | Identifier for values to interpolate. -- -- The representation is the following: -- -- 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 OverloadedStrings -- 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. -- -- Before version 0.2.0 it was called MustacheException. MustacheParserException :: ParseError -> MustacheException -- | A referenced value was not provided. The exception provides info about -- partial in which the issue happened PName and name of the -- missing key Key. 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 -- | Functions for rendering Mustache templates. You don't usually need to -- import the module, because Text.Microstache re-exports -- everything you may need, import that module instead. module Text.Microstache.Render -- | Render a Mustache Template using Aeson's Value 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), MustacheRenderException -- will be thrown. The included Key will indicate full path to -- missing value and PName will contain the name of active -- partial. renderMustache :: Template -> Value -> Text -- | Megaparsec parser for Mustache templates. You don't usually need to -- import the module, because Text.Microstache re-exports -- everything you may need, import that module instead. module Text.Microstache.Parser -- | Parse given Mustache template. parseMustache :: FilePath -> Text -> Either ParseError [Node] -- | Mustache Template creation from file or a Text value. -- You don't usually need to import the module, because -- Text.Microstache 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 mustache, (e.g. -- foo.mustache) to be recognized. This function does not -- scan the directory recursively. -- -- The action can throw the same exceptions as -- getDirectoryContents, and readFile. 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 readFile. compileMustacheFile :: FilePath -> IO Template -- | Compile Mustache template from a lazy Text value. The cache -- will contain only this template named according to given PName. 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 https://github.com/mustache/spec. 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 Value 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 ToJSON, the whole process is very simple for end -- user. -- -- Template Haskell helpers for compilation of templates at compile time -- are available in the Text.Microstache.Compile.TH 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: -- -- 
--   {-# 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 -> putStrLn (parseErrorPretty err)
--       Right template -> TIO.putStr $ renderMustache template $ object
--         [ "name"   .= ("John" :: Text)
--         , "things" .= ["pen" :: Text, "candle", "egg"]
--         ]
--
-- -- If I run the program, it prints the following: -- -- 
--   Hi, John! You have:
--     * pen
--     * candle
--     * egg
--
-- -- For more information about Mustache templates the following links may -- be helpful: -- -- module Text.Microstache -- | Mustache template as name of “top-level” template and a collection of -- all available templates (partials). -- -- Template is a Semigroup. This means that you can combine -- Templates (and their caches) using the -- (<>) operator, the resulting Template -- 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 templateActual. [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 (Nothing means it was inlined) Partial :: PName -> (Maybe Word) -> Node -- | Identifier for values to interpolate. -- -- The representation is the following: -- -- newtype Key Key :: [Text] -> Key [unKey] :: Key -> [Text] -- | Identifier for partials. Note that with the OverloadedStrings -- 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. -- -- Before version 0.2.0 it was called MustacheException. MustacheParserException :: ParseError -> MustacheException -- | A referenced value was not provided. The exception provides info about -- partial in which the issue happened PName and name of the -- missing key Key. MustacheRenderException :: PName -> Key -> MustacheException -- | Compile all templates in specified directory and select one. Template -- files should have extension mustache, (e.g. -- foo.mustache) to be recognized. This function does not -- scan the directory recursively. -- -- The action can throw the same exceptions as -- getDirectoryContents, and readFile. compileMustacheDir :: PName -> FilePath -> IO Template -- | Compile single Mustache template and select it. -- -- The action can throw the same exceptions as readFile. compileMustacheFile :: FilePath -> IO Template -- | Compile Mustache template from a lazy Text value. The cache -- will contain only this template named according to given PName. compileMustacheText :: PName -> Text -> Either ParseError Template -- | Render a Mustache Template using Aeson's Value 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), MustacheRenderException -- will be thrown. The included Key will indicate full path to -- missing value and PName will contain the name of active -- partial. renderMustache :: Template -> Value -> Text