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


-- | A mustache template parser library.
--   
--   Allows parsing and rendering template files with mustache markup. See
--   the mustache <a>language reference</a>.
--   
--   Implements the mustache spec version 1.1.3.
--   
--   <i>Note</i>: Versions including and beyond 0.4 are compatible with ghc
--   7.8 again.
@package mustache
@version 2.4.3.1


module Text.Mustache.Types
type ASTree α = [Node α]

-- | Syntax tree for a mustache template
type STree = ASTree Text

-- | Basic values composing the STree
data Node α
TextBlock :: α -> Node α
Section :: DataIdentifier -> ASTree α -> Node α
InvertedSection :: DataIdentifier -> ASTree α -> Node α
Variable :: Bool -> DataIdentifier -> Node α
Partial :: Maybe α -> FilePath -> Node α

-- | Kinds of identifiers for Variables and sections
data DataIdentifier
NamedData :: [Key] -> DataIdentifier
Implicit :: DataIdentifier

-- | A compiled Template with metadata.
data Template
Template :: String -> STree -> TemplateCache -> Template
[name] :: Template -> String
[ast] :: Template -> STree
[partials] :: Template -> TemplateCache

-- | A collection of templates with quick access via their hashed names
type TemplateCache = HashMap String Template

-- | Internal value representation
data Value
Object :: !Object -> Value
Array :: !Array -> Value
Number :: !Scientific -> Value
String :: !Text -> Value
Lambda :: (STree -> SubM STree) -> Value
Bool :: !Bool -> Value
Null :: Value

-- | Type of key used for retrieving data from <a>Value</a>s
type Key = Text

-- | Convenience function for creating Object values.
--   
--   This function is supposed to be used in conjuction with the
--   <a>~&gt;</a> and <a>~=</a> operators.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   data Address = Address { ... }
--   
--   instance Address ToJSON where
--     ...
--   
--   data Person = Person { name :: String, address :: Address }
--   
--   instance ToMustache Person where
--     toMustache (Person { name, address }) = object
--       [ "name" ~&gt; name
--       , "address" ~= address
--       ]
--   </pre>
--   
--   Here we can see that we can use the <a>~&gt;</a> operator for values
--   that have themselves a <a>ToMustache</a> instance, or alternatively if
--   they lack such an instance but provide an instance for the
--   <tt>ToJSON</tt> typeclass we can use the <a>~=</a> operator.
object :: [Pair] -> Value

-- | Map keys to values that provide a <a>ToMustache</a> instance
--   
--   Recommended in conjunction with the <tt>OverloadedStrings</tt>
--   extension.
(~>) :: ToMustache ω => Text -> ω -> Pair
infixr 8 ~>

-- | Unicode version of <a>~&gt;</a>
(↝) :: ToMustache ω => Text -> ω -> Pair
infixr 8 ↝

-- | Map keys to values that provide a <tt>ToJSON</tt> instance
--   
--   Recommended in conjunction with the <tt>OverloadedStrings</tt>
--   extension.
(~=) :: ToJSON ι => Text -> ι -> Pair
infixr 8 ~=

-- | Unicode version of <a>~=</a>
(⥱) :: ToJSON ι => Text -> ι -> Pair
infixr 8 ⥱

-- | Conversion class
class ToMustache ω
toMustache :: ToMustache ω => ω -> Value

-- | Converts a value that can be represented as JSON to a Value.
mFromJSON :: ToJSON ι => ι -> Value
integralToMustache :: Integral ω => ω -> Value

-- | A list-like structure used in <a>Value</a>
type Array = Vector Value

-- | A map-like structure used in <a>Value</a>
type Object = HashMap Text Value

-- | Source type for constructing <a>Object</a>s
type Pair = (Text, Value)
data SubM a
askContext :: SubM (Context Value)
askPartials :: SubM TemplateCache

-- | Representation of stateful context for the substitution process
data Context α
Context :: [α] -> α -> Context α
[ctxtParents] :: Context α -> [α]
[ctxtFocus] :: Context α -> α


module Text.Mustache.Render

-- | Substitutes all mustache defined tokens (or tags) for values found in
--   the provided data structure.
--   
--   Equivalent to <tt>substituteValue . toMustache</tt>.
substitute :: ToMustache k => Template -> k -> Text

-- | Substitutes all mustache defined tokens (or tags) for values found in
--   the provided data structure.
substituteValue :: Template -> Value -> Text

-- | Substitutes all mustache defined tokens (or tags) for values found in
--   the provided data structure and report any errors and warnings
--   encountered during substitution.
--   
--   This function always produces results, as in a fully
--   substituted/rendered template, it never halts on errors. It simply
--   reports them in the first part of the tuple. Sites with errors are
--   usually substituted with empty string.
--   
--   The second value in the tuple is a template rendered with errors
--   ignored. Therefore if you must enforce that there were no errors
--   during substitution you must check that the error list in the first
--   tuple value is empty.
--   
--   Equivalent to <tt>checkedSubstituteValue . toMustache</tt>.
checkedSubstitute :: ToMustache k => Template -> k -> ([SubstitutionError], Text)

-- | Substitutes all mustache defined tokens (or tags) for values found in
--   the provided data structure and report any errors and warnings
--   encountered during substitution.
--   
--   This function always produces results, as in a fully
--   substituted/rendered template, it never halts on errors. It simply
--   reports them in the first part of the tuple. Sites with errors are
--   usually substituted with empty string.
--   
--   The second value in the tuple is a template rendered with errors
--   ignored. Therefore if you must enforce that there were no errors
--   during substitution you must check that the error list in the first
--   tuple value is empty.
checkedSubstituteValue :: Template -> Value -> ([SubstitutionError], Text)

-- | Type of errors we may encounter during substitution.
data SubstitutionError

-- | The template contained a variable for which there was no data
--   counterpart in the current context
VariableNotFound :: [Key] -> SubstitutionError

-- | When substituting an implicit section the current context had an
--   unsubstitutable type
InvalidImplicitSectionContextType :: String -> SubstitutionError

-- | Inverted implicit sections should never occur
InvertedImplicitSection :: SubstitutionError

-- | The template contained a section for which there was no data
--   counterpart in the current context
SectionTargetNotFound :: [Key] -> SubstitutionError

-- | The template contained a partial for which there was no data
--   counterpart in the current context
PartialNotFound :: FilePath -> SubstitutionError

-- | A complex value such as an Object or Array was directly rendered into
--   the template (warning)
DirectlyRenderedValue :: Value -> SubstitutionError

-- | Representation of stateful context for the substitution process
data Context α
Context :: [α] -> α -> Context α
[ctxtParents] :: Context α -> [α]
[ctxtFocus] :: Context α -> α

-- | Search for a key in the current context.
--   
--   The search is conducted inside out mening the current focus is
--   searched first. If the key is not found the outer scopes are
--   recursively searched until the key is found, then <a>innerSearch</a>
--   is called on the result.
search :: [Key] -> SubM (Maybe Value)

-- | Searches nested scopes navigating inward. Fails if it encunters
--   something other than an object before the key is expended.
innerSearch :: [Key] -> Value -> Maybe Value
data SubM a

-- | Main substitution function
substituteNode :: Node Text -> SubM ()

-- | Substitute an entire <a>STree</a> rather than just a single
--   <a>Node</a>
substituteAST :: STree -> SubM ()

-- | Catch the results of running the inner substitution.
catchSubstitute :: SubM a -> SubM (a, Text)

-- | Converts values to Text as required by the mustache standard
toString :: Value -> SubM Text
instance Text.Mustache.Internal.Types.ToMustache (Text.Mustache.Internal.Types.Context Text.Mustache.Internal.Types.Value -> Text.Mustache.Internal.Types.STree -> Text.Mustache.Internal.Types.STree)
instance Text.Mustache.Internal.Types.ToMustache (Text.Mustache.Internal.Types.Context Text.Mustache.Internal.Types.Value -> Text.Mustache.Internal.Types.STree -> Data.Text.Internal.Text)
instance Text.Mustache.Internal.Types.ToMustache (Text.Mustache.Internal.Types.Context Text.Mustache.Internal.Types.Value -> Text.Mustache.Internal.Types.STree -> Data.Text.Internal.Lazy.Text)
instance Text.Mustache.Internal.Types.ToMustache (Text.Mustache.Internal.Types.Context Text.Mustache.Internal.Types.Value -> Text.Mustache.Internal.Types.STree -> GHC.Internal.Base.String)
instance Text.Mustache.Internal.Types.ToMustache (Text.Mustache.Internal.Types.STree -> Text.Mustache.Internal.Types.SubM Data.Text.Internal.Text)


module Text.Mustache.Parser

-- | Runs the parser for a mustache template, returning the syntax tree.
parse :: FilePath -> Text -> Either ParseError STree

-- | Parse using a custom initial configuration
parseWithConf :: MustacheConf -> FilePath -> Text -> Either ParseError STree

-- | Initial configuration for the parser
newtype MustacheConf
MustacheConf :: (String, String) -> MustacheConf
[delimiters] :: MustacheConf -> (String, String)

-- | Default configuration (delimiters = ("{{", "}}"))
defaultConf :: MustacheConf

-- | The parser monad in use
type Parser = Parsec Text MustacheState

-- | User state for the parser
data MustacheState

-- | <pre>
--   #
--   </pre>
sectionBegin :: Char

-- | <pre>
--   /
--   </pre>
sectionEnd :: Char

-- | <pre>
--   ^
--   </pre>
invertedSectionBegin :: Char

-- | <tt>{</tt> and <tt>}</tt>
unescape2 :: (Char, Char)

-- | <pre>
--   &amp;
--   </pre>
unescape1 :: Char

-- | <pre>
--   =
--   </pre>
delimiterChange :: Char

-- | <pre>
--   .
--   </pre>
nestingSeparator :: Char


module Text.Mustache.Compile

-- | Compiles a mustache template provided by name including the mentioned
--   partials.
--   
--   The same can be done manually using <a>getFile</a>,
--   <tt>mustacheParser</tt> and <a>getPartials</a>.
--   
--   This function also ensures each partial is only compiled once even
--   though it may be included by other partials including itself.
--   
--   A reference to the included template will be found in each including
--   templates <a>partials</a> section.
automaticCompile :: [FilePath] -> FilePath -> IO (Either ParseError Template)

-- | Compile the template with the search space set to only the current
--   directory
localAutomaticCompile :: FilePath -> IO (Either ParseError Template)

-- | A collection of templates with quick access via their hashed names
type TemplateCache = HashMap String Template

-- | Compile a mustache template providing a list of precompiled templates
--   that do not have to be recompiled.
compileTemplateWithCache :: [FilePath] -> TemplateCache -> FilePath -> IO (Either ParseError Template)

-- | Compiles a <a>Template</a> directly from <a>Text</a> without checking
--   for missing partials. the result will be a <a>Template</a> with an
--   empty <a>partials</a> cache.
compileTemplate :: String -> Text -> Either ParseError Template

-- | Flatten a list of Templates into a single <a>TemplateCache</a>
cacheFromList :: [Template] -> TemplateCache

-- | Find the names of all included partials in a mustache STree.
--   
--   Same as <tt>join . fmap getPartials'</tt>
getPartials :: STree -> [FilePath]

-- | Compile a mustache <a>Template</a> at compile time. Usage:
--   
--   <pre>
--   {-# LANGUAGE QuasiQuotes #-}
--   import Text.Mustache.Compile (mustache)
--   
--   foo :: Template
--   foo = [mustache|This is my inline {{ template }} created at compile time|]
--   </pre>
--   
--   Partials are not supported in the QuasiQuoter
mustache :: QuasiQuoter

-- | Compile a mustache <a>Template</a> at compile time providing a search
--   space for any partials. Usage:
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell #-}
--   import Text.Mustache.Compile (embedTemplate)
--   
--   foo :: Template
--   foo = $(embedTemplate ["dir", "dir/partials"] "file.mustache")
--   </pre>
embedTemplate :: [FilePath] -> FilePath -> Q Exp

-- | Compile a mustache <a>Template</a> at compile time. Usage:
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell #-}
--   import Text.Mustache.Compile (embedSingleTemplate)
--   
--   foo :: Template
--   foo = $(embedSingleTemplate "dir/file.mustache")
--   </pre>
--   
--   Partials are not supported in embedSingleTemplate
embedSingleTemplate :: FilePath -> Q Exp


-- | <h1>How to use this library</h1>
--   
--   This module exposes some of the most convenient functions for dealing
--   with mustache templates.
--   
--   <h2>Compiling with automatic partial discovery</h2>
--   
--   The easiest way of compiling a file and its potential includes (called
--   partials) is by using the <a>automaticCompile</a> function.
--   
--   <pre>
--   main :: IO ()
--   main = do
--     let searchSpace = [".", "./templates"]
--         templateName = "main.mustache"
--   
--     compiled &lt;- automaticCompile searchSpace templateName
--     case compiled of
--       Left err -&gt; print err
--       Right template -&gt; pure () -- this is where you can start using it
--   </pre>
--   
--   The <tt>searchSpace</tt> encompasses all directories in which the
--   compiler should search for the template source files. The search
--   itself is conducted in order, from left to right.
--   
--   Should your search space be only the current working directory, you
--   can use <a>localAutomaticCompile</a>.
--   
--   The <tt>templateName</tt> is the relative path of the template to any
--   directory of the search space.
--   
--   <a>automaticCompile</a> not only finds and compiles the template for
--   you, it also recursively finds any partials included in the template
--   as well, compiles them and stores them in the <a>partials</a> hash
--   attached to the resulting template.
--   
--   The compiler will throw errors if either the template is malformed or
--   the source file for a partial or the template itself could not be
--   found in any of the directories in <tt>searchSpace</tt>.
--   
--   <h2>Substituting</h2>
--   
--   In order to substitute data into the template it must be an instance
--   of the <a>ToMustache</a> typeclass or be of type <a>Value</a>.
--   
--   This libray tries to imitate the API of <a>aeson</a> by allowing you
--   to define conversions of your own custom data types into <a>Value</a>,
--   the type used internally by the substitutor via typeclass and a
--   selection of operators and convenience functions.
--   
--   <h3>Example</h3>
--   
--   <pre>
--   data Person = { age :: Int, name :: String }
--   
--   instance ToMustache Person where
--     toMustache person = object
--       [ "age" ~&gt; age person
--       , "name" ~&gt; name person
--       ]
--   </pre>
--   
--   The values to the left of the <a>~&gt;</a> operator has to be of type
--   <tt>Text</tt>, hence the <tt>OverloadedStrings</tt> can becomes very
--   handy here.
--   
--   Values to the right of the <a>~&gt;</a> operator must be an instance
--   of the <a>ToMustache</a> typeclass. Alternatively, if your value to
--   the right of the <a>~&gt;</a> operator is not an instance of
--   <a>ToMustache</a> but an instance of <tt>ToJSON</tt> you can use the
--   <a>~=</a> operator, which accepts <tt>ToJSON</tt> values.
--   
--   <pre>
--   data Person = { age :: Int, name :: String, address :: Address }
--   
--   data Address = ...
--   
--   instance ToJSON Address where
--     ...
--   
--   instance ToMustache Person where
--     toMustache person = object
--       [ "age" ~&gt; age person
--       , "name" ~&gt; name person
--       , "address" ~= address person
--       ]
--   </pre>
--   
--   All operators are also provided in a unicode form, for those that,
--   like me, enjoy unicode operators.
--   
--   <h2>Manual compiling</h2>
--   
--   You can compile templates manually without requiring the IO monad at
--   all, using the <a>compileTemplate</a> function. This is the same
--   function internally used by <a>automaticCompile</a> and does not check
--   if required partial are present.
--   
--   More functions for manual compilation can be found in the
--   <a>Compile</a> module. Including helpers for finding lists of partials
--   in templates.
--   
--   Additionally the <a>compileTemplateWithCache</a> function is exposed
--   here which you may use to automatically compile a template but avoid
--   some of the compilation overhead by providing already compiled
--   partials as well.
--   
--   <h2>Fundamentals</h2>
--   
--   This library builds on three important data structures/types.
--   
--   <ul>
--   <li><i><a>Value</a></i> A data structure almost identical to
--   Data.Aeson.Value extended with lambda functions which represents the
--   data the template is being filled with.</li>
--   <li><i><a>ToMustache</a></i> A typeclass for converting arbitrary
--   types to <a>Value</a>, similar to Data.Aeson.ToJSON but with support
--   for lambdas.</li>
--   <li><i><a>Template</a></i> Contains the <tt>STree</tt>, the syntax
--   tree, which is basically a list of text blocks and mustache tags. The
--   <a>name</a> of the template and its <a>partials</a> cache.</li>
--   </ul>
--   
--   <h3>Compiling</h3>
--   
--   During the compilation step the template file is located, read, then
--   parsed in a single pass (<a>compileTemplate</a>), resulting in a
--   <a>Template</a> with an empty <a>partials</a> section.
--   
--   Subsequenty the <tt>STree</tt> of the template is scanned for included
--   partials, any present <tt>TemplateCache</tt> is queried for the
--   partial (<a>compileTemplateWithCache</a>), if not found it will be
--   searched for in the <tt>searchSpace</tt>, compiled and inserted into
--   the template's own cache as well as the global cache for the
--   compilation process.
--   
--   Internally no partial is compiled twice, as long as the names stay
--   consistent.
--   
--   Once compiled templates may be used multiple times for substitution or
--   as partial for other templates.
--   
--   Partials are not being embedded into the templates during compilation,
--   but during substitution, hence the <a>partials</a> cache is vital to
--   the template even after compilation has been completed. Any non
--   existent partial in the cache will rsubstitute to an empty string.
--   
--   <h3>Substituting</h3>
module Text.Mustache

-- | Compiles a mustache template provided by name including the mentioned
--   partials.
--   
--   The same can be done manually using <a>getFile</a>,
--   <tt>mustacheParser</tt> and <a>getPartials</a>.
--   
--   This function also ensures each partial is only compiled once even
--   though it may be included by other partials including itself.
--   
--   A reference to the included template will be found in each including
--   templates <a>partials</a> section.
automaticCompile :: [FilePath] -> FilePath -> IO (Either ParseError Template)

-- | Compile the template with the search space set to only the current
--   directory
localAutomaticCompile :: FilePath -> IO (Either ParseError Template)

-- | Compile a mustache template providing a list of precompiled templates
--   that do not have to be recompiled.
compileTemplateWithCache :: [FilePath] -> TemplateCache -> FilePath -> IO (Either ParseError Template)

-- | Compiles a <a>Template</a> directly from <a>Text</a> without checking
--   for missing partials. the result will be a <a>Template</a> with an
--   empty <a>partials</a> cache.
compileTemplate :: String -> Text -> Either ParseError Template

-- | A compiled Template with metadata.
data Template
Template :: String -> STree -> TemplateCache -> Template
[name] :: Template -> String
[ast] :: Template -> STree
[partials] :: Template -> TemplateCache

-- | Substitutes all mustache defined tokens (or tags) for values found in
--   the provided data structure.
--   
--   Equivalent to <tt>substituteValue . toMustache</tt>.
substitute :: ToMustache k => Template -> k -> Text

-- | Substitutes all mustache defined tokens (or tags) for values found in
--   the provided data structure and report any errors and warnings
--   encountered during substitution.
--   
--   This function always produces results, as in a fully
--   substituted/rendered template, it never halts on errors. It simply
--   reports them in the first part of the tuple. Sites with errors are
--   usually substituted with empty string.
--   
--   The second value in the tuple is a template rendered with errors
--   ignored. Therefore if you must enforce that there were no errors
--   during substitution you must check that the error list in the first
--   tuple value is empty.
--   
--   Equivalent to <tt>checkedSubstituteValue . toMustache</tt>.
checkedSubstitute :: ToMustache k => Template -> k -> ([SubstitutionError], Text)

-- | Substitutes all mustache defined tokens (or tags) for values found in
--   the provided data structure.
substituteValue :: Template -> Value -> Text

-- | Substitutes all mustache defined tokens (or tags) for values found in
--   the provided data structure and report any errors and warnings
--   encountered during substitution.
--   
--   This function always produces results, as in a fully
--   substituted/rendered template, it never halts on errors. It simply
--   reports them in the first part of the tuple. Sites with errors are
--   usually substituted with empty string.
--   
--   The second value in the tuple is a template rendered with errors
--   ignored. Therefore if you must enforce that there were no errors
--   during substitution you must check that the error list in the first
--   tuple value is empty.
checkedSubstituteValue :: Template -> Value -> ([SubstitutionError], Text)

-- | Main substitution function
substituteNode :: Node Text -> SubM ()

-- | Substitute an entire <a>STree</a> rather than just a single
--   <a>Node</a>
substituteAST :: STree -> SubM ()

-- | Catch the results of running the inner substitution.
catchSubstitute :: SubM a -> SubM (a, Text)

-- | Conversion class
class ToMustache ω
toMustache :: ToMustache ω => ω -> Value
integralToMustache :: Integral ω => ω -> Value

-- | Convenience function for creating Object values.
--   
--   This function is supposed to be used in conjuction with the
--   <a>~&gt;</a> and <a>~=</a> operators.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   data Address = Address { ... }
--   
--   instance Address ToJSON where
--     ...
--   
--   data Person = Person { name :: String, address :: Address }
--   
--   instance ToMustache Person where
--     toMustache (Person { name, address }) = object
--       [ "name" ~&gt; name
--       , "address" ~= address
--       ]
--   </pre>
--   
--   Here we can see that we can use the <a>~&gt;</a> operator for values
--   that have themselves a <a>ToMustache</a> instance, or alternatively if
--   they lack such an instance but provide an instance for the
--   <tt>ToJSON</tt> typeclass we can use the <a>~=</a> operator.
object :: [Pair] -> Value

-- | Map keys to values that provide a <a>ToMustache</a> instance
--   
--   Recommended in conjunction with the <tt>OverloadedStrings</tt>
--   extension.
(~>) :: ToMustache ω => Text -> ω -> Pair
infixr 8 ~>

-- | Map keys to values that provide a <tt>ToJSON</tt> instance
--   
--   Recommended in conjunction with the <tt>OverloadedStrings</tt>
--   extension.
(~=) :: ToJSON ι => Text -> ι -> Pair
infixr 8 ~=

-- | Creates a <tt>Lambda</tt> which first renders the contained section
--   and then applies the supplied function
overText :: (Text -> Text) -> Value
