-- 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 language reference.
--   
--   Implements the mustache spec version 1.1.3.
--   
--   Note: Versions including and beyond 0.4 are compatible with ghc
--   7.8 again.
@package mustache
@version 2.3.0

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 Values
type Key = Text

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

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

-- | Unicode version of ~>
(↝) :: ToMustache ω => Text -> ω -> Pair
infixr 8 ↝

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

-- | Unicode version of ~=
(⥱) :: 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

-- | A list-like structure used in Value
type Array = Vector Value

-- | A map-like structure used in Value
type Object = HashMap Text Value

-- | Source type for constructing Objects
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 substituteValue . toMustache.
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 checkedSubstituteValue . toMustache.
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 innerSearch
--   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 STree rather than just a single
--   Node
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.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
data 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

-- | 
--   #
--   
sectionBegin :: Char

-- | 
--   /
--   
sectionEnd :: Char

-- | 
--   ^
--   
invertedSectionBegin :: Char

-- | { and }
unescape2 :: (Char, Char)

-- | 
--   &
--   
unescape1 :: Char

-- | 
--   =
--   
delimiterChange :: Char

-- | 
--   .
--   
nestingSeparator :: Char

module Text.Mustache.Compile

-- | Compiles a mustache template provided by name including the mentioned
--   partials.
--   
--   The same can be done manually using getFile,
--   mustacheParser and getPartials.
--   
--   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 partials 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 Template directly from Text without checking
--   for missing partials. the result will be a Template with an
--   empty partials cache.
compileTemplate :: String -> Text -> Either ParseError Template

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

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

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

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

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

-- | 
How to use this library
--   
--   This module exposes some of the most convenient functions for dealing
--   with mustache templates.
--   
--   
Compiling with automatic partial discovery
--   
--   The easiest way of compiling a file and its potential includes (called
--   partials) is by using the automaticCompile function.
--   
--   
--   main :: IO ()
--   main = do
--     let searchSpace = [".", "./templates"]
--         templateName = "main.mustache"
--   
--     compiled <- automaticCompile searchSpace templateName
--     case compiled of
--       Left err -> print err
--       Right template -> return () -- this is where you can start using it
--   
--   
--   The searchSpace 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 localAutomaticCompile.
--   
--   The templateName is the relative path of the template to any
--   directory of the search space.
--   
--   automaticCompile 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 partials 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 searchSpace.
--   
--   
Substituting
--   
--   In order to substitute data into the template it must be an instance
--   of the ToMustache typeclass or be of type Value.
--   
--   This libray tries to imitate the API of aeson by allowing you
--   to define conversions of your own custom data types into Value,
--   the type used internally by the substitutor via typeclass and a
--   selection of operators and convenience functions.
--   
--   
Example
--   
--   
--   data Person = { age :: Int, name :: String }
--   
--   instance ToMustache Person where
--     toMustache person = object
--       [ "age" ~> age person
--       , "name" ~> name person
--       ]
--   
--   
--   The values to the left of the ~> operator has to be of type
--   Text, hence the OverloadedStrings can becomes very
--   handy here.
--   
--   Values to the right of the ~> operator must be an instance
--   of the ToMustache typeclass. Alternatively, if your value to
--   the right of the ~> operator is not an instance of
--   ToMustache but an instance of ToJSON you can use the
--   ~= operator, which accepts ToJSON values.
--   
--   
--   data Person = { age :: Int, name :: String, address :: Address }
--   
--   data Address = ...
--   
--   instance ToJSON Address where
--     ...
--   
--   instance ToMustache Person where
--     toMustache person = object
--       [ "age" ~> age person
--       , "name" ~> name person
--       , "address" ~= address person
--       ]
--   
--   
--   All operators are also provided in a unicode form, for those that,
--   like me, enjoy unicode operators.
--   
--   
Manual compiling
--   
--   You can compile templates manually without requiring the IO monad at
--   all, using the compileTemplate function. This is the same
--   function internally used by automaticCompile and does not check
--   if required partial are present.
--   
--   More functions for manual compilation can be found in the
--   Compile module. Including helpers for finding lists of partials
--   in templates.
--   
--   Additionally the compileTemplateWithCache 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.
--   
--   
Fundamentals
--   
--   This library builds on three important data structures/types.
--   
--   
--   
- Value A data structure almost identical to
--   Data.Aeson.Value extended with lambda functions which represents the
--   data the template is being filled with.
--   
- ToMustache A typeclass for converting arbitrary
--   types to Value, similar to Data.Aeson.ToJSON but with support
--   for lambdas.
--   
- Template Contains the STree, the syntax tree,
--   which is basically a list of text blocks and mustache tags. The
--   name of the template and its partials cache.
--   
--   
--   
Compiling
--   
--   During the compilation step the template file is located, read, then
--   parsed in a single pass (compileTemplate), resulting in a
--   Template with an empty partials section.
--   
--   Subsequenty the STree of the template is scanned for included
--   partials, any present TemplateCache is queried for the partial
--   (compileTemplateWithCache), if not found it will be searched
--   for in the searchSpace, 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 partials 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.
--   
--   
Substituting
module Text.Mustache

-- | Compiles a mustache template provided by name including the mentioned
--   partials.
--   
--   The same can be done manually using getFile,
--   mustacheParser and getPartials.
--   
--   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 partials 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 Template directly from Text without checking
--   for missing partials. the result will be a Template with an
--   empty partials 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 substituteValue . toMustache.
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 checkedSubstituteValue . toMustache.
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 STree rather than just a single
--   Node
substituteAST :: STree -> SubM ()

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

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

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

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

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

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