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


-- | StringTemplate implementation in Haskell.
--   
--   A port of the Java library by Terrence Parr.
@package HStringTemplate
@version 0.7.0

module Text.StringTemplate.Classes
data SElem a
STR :: String -> SElem a
BS :: ByteString -> SElem a
TXT :: Text -> SElem a
STSH :: STShow -> SElem a
SM :: (SMap a) -> SElem a
LI :: [SElem a] -> SElem a
SBLE :: a -> SElem a
SNAT :: a -> SElem a
SNull :: SElem a

-- | The StringTemplateShows class should be instantiated for all types
--   that are directly displayed in a StringTemplate, but take an optional
--   format string. Each such type must have an appropriate ToSElem method
--   defined as well.
class Show a => StringTemplateShows a where stringTemplateShow = show stringTemplateFormattedShow = flip $ const . stringTemplateShow
stringTemplateShow :: StringTemplateShows a => a -> String
stringTemplateFormattedShow :: StringTemplateShows a => String -> a -> String

-- | The ToSElem class should be instantiated for all types that can be
--   inserted as attributes into a StringTemplate.
class ToSElem a where toSElemList = LI . map toSElem
toSElem :: (ToSElem a, Stringable b) => a -> SElem b
toSElemList :: (ToSElem a, Stringable b) => [a] -> SElem b
type SMap a = Map String (SElem a)
data STShow
STShow :: a -> STShow
newtype StFirst a
StFirst :: Maybe a -> StFirst a
stGetFirst :: StFirst a -> Maybe a

-- | The Stringable class should be instantiated with care. Generally, the
--   provided instances should be enough for anything.
class Monoid a => Stringable a where stFromByteString = stFromText . decodeUtf8 stFromText = stFromString . unpack mconcatMap m k = foldr (mappend . k) mempty m mintercalate = (mconcat .) . intersperse mlabel x y = mconcat [x, stFromString "[", y, stFromString "]"]
stFromString :: Stringable a => String -> a
stFromByteString :: Stringable a => ByteString -> a
stFromText :: Stringable a => Text -> a
stToString :: Stringable a => a -> String
mconcatMap :: Stringable a => [b] -> (b -> a) -> a
mintercalate :: Stringable a => a -> [a] -> a
mlabel :: Stringable a => a -> a -> a

-- | This method should be used to create ToSElem instances for types
--   defining a custom formatted show function.
stShowsToSE :: (StringTemplateShows a, Stringable b) => a -> SElem b
instance Eq a => Eq (StFirst a)
instance Ord a => Ord (StFirst a)
instance Read a => Read (StFirst a)
instance Show a => Show (StFirst a)
instance Stringable (Endo String)
instance Stringable Builder
instance Stringable Builder
instance Stringable Text
instance Stringable Text
instance Stringable ByteString
instance Stringable ByteString
instance Stringable Doc
instance Stringable String
instance Functor StFirst
instance Monoid (StFirst a)


-- | Generic Instance for ToSElem using standard Data.Generic libraries.
module Text.StringTemplate.GenericStandard
instance [overlap ok] Data a => ToSElem a

module Text.StringTemplate.Base

-- | A String with "holes" in it. StringTemplates may be composed of any
--   <a>Stringable</a> type, which at the moment includes <a>String</a>s,
--   <tt>ByteString</tt>s, PrettyPrinter <tt>Doc</tt>s, and <a>Endo</a>
--   <a>String</a>s, which are actually of type <a>ShowS</a>. When a
--   StringTemplate is composed of a type, its internals are as well, so it
--   is, so to speak "turtles all the way down."
data StringTemplate a
STMP :: SEnv a -> Either String (SEnv a -> a) -> (SEnv a -> (Maybe String, Maybe [String], Maybe [String])) -> StringTemplate a
senv :: StringTemplate a -> SEnv a
runSTMP :: StringTemplate a -> Either String (SEnv a -> a)
chkSTMP :: StringTemplate a -> SEnv a -> (Maybe String, Maybe [String], Maybe [String])

-- | The StringTemplateShows class should be instantiated for all types
--   that are directly displayed in a StringTemplate, but take an optional
--   format string. Each such type must have an appropriate ToSElem method
--   defined as well.
class Show a => StringTemplateShows a where stringTemplateShow = show stringTemplateFormattedShow = flip $ const . stringTemplateShow
stringTemplateShow :: StringTemplateShows a => a -> String
stringTemplateFormattedShow :: StringTemplateShows a => String -> a -> String

-- | The ToSElem class should be instantiated for all types that can be
--   inserted as attributes into a StringTemplate.
class ToSElem a where toSElemList = LI . map toSElem
toSElem :: (ToSElem a, Stringable b) => a -> SElem b
toSElemList :: (ToSElem a, Stringable b) => [a] -> SElem b

-- | A function that generates StringTemplates. This is conceptually a
--   query function into a "group" of StringTemplates.
type STGroup a = String -> (StFirst (StringTemplate a))

-- | The Stringable class should be instantiated with care. Generally, the
--   provided instances should be enough for anything.
class Monoid a => Stringable a where stFromByteString = stFromText . decodeUtf8 stFromText = stFromString . unpack mconcatMap m k = foldr (mappend . k) mempty m mintercalate = (mconcat .) . intersperse mlabel x y = mconcat [x, stFromString "[", y, stFromString "]"]
stFromString :: Stringable a => String -> a
stFromByteString :: Stringable a => ByteString -> a
stFromText :: Stringable a => Text -> a
stToString :: Stringable a => a -> String
mconcatMap :: Stringable a => [b] -> (b -> a) -> a
mintercalate :: Stringable a => a -> [a] -> a
mlabel :: Stringable a => a -> a -> a

-- | This method should be used to create ToSElem instances for types
--   defining a custom formatted show function.
stShowsToSE :: (StringTemplateShows a, Stringable b) => a -> SElem b
inSGen :: (STGroup a -> STGroup a) -> StringTemplate a -> StringTemplate a

-- | Renders a StringTemplate to a String.
toString :: StringTemplate String -> String

-- | Renders a StringTemplate to a <a>Doc</a>.
toPPDoc :: StringTemplate Doc -> Doc

-- | Generic render function for a StringTemplate of any type.
render :: Stringable a => StringTemplate a -> a

-- | Parses a String to produce a StringTemplate, with '$'s as delimiters.
--   It is constructed with a stub group that cannot look up other
--   templates.
newSTMP :: Stringable a => String -> StringTemplate a

-- | Parses a String to produce a StringTemplate, delimited by angle
--   brackets. It is constructed with a stub group that cannot look up
--   other templates.
newAngleSTMP :: Stringable a => String -> StringTemplate a

-- | Queries an String Template Group and returns Just the appropriate
--   StringTemplate if it exists, otherwise, Nothing.
getStringTemplate :: Stringable a => String -> STGroup a -> Maybe (StringTemplate a)

-- | As with <a>getStringTemplate</a> but never inlined, so appropriate for
--   use with volatile template groups.
getStringTemplate' :: Stringable a => String -> STGroup a -> Maybe (StringTemplate a)

-- | Yields a StringTemplate with the appropriate attribute set. If the
--   attribute already exists, it is appended to a list.
setAttribute :: (ToSElem a, Stringable b) => String -> a -> StringTemplate b -> StringTemplate b

-- | Yields a StringTemplate with the appropriate attributes set. If any
--   attribute already exists, it is appended to a list.
setManyAttrib :: (ToSElem a, Stringable b) => [(String, a)] -> StringTemplate b -> StringTemplate b

-- | Yields a StringTemplate with the appropriate attribute set. If the
--   attribute already exists, it is appended to a list. This will not
--   translate the attribute through any intermediate representation, so is
--   more efficient when, e.g. setting attributes that are large
--   bytestrings in a bytestring template.
setNativeAttribute :: Stringable b => String -> b -> StringTemplate b -> StringTemplate b

-- | Yields a StringTemplate with the appropriate attributes set. If any
--   attribute already exists, it is appended to a list. Attributes are
--   added natively, which may provide efficiency gains.
setManyNativeAttrib :: Stringable b => [(String, b)] -> StringTemplate b -> StringTemplate b

-- | Replaces the attributes of a StringTemplate with those described in
--   the second argument. If the argument does not yield a set of named
--   attributes but only a single one, that attribute is named, as a
--   default, "it".
withContext :: (ToSElem a, Stringable b) => StringTemplate b -> a -> StringTemplate b

-- | Adds a set of global options to a single template
optInsertTmpl :: [(String, String)] -> StringTemplate a -> StringTemplate a

-- | Sets an encoding function of a template that all values are rendered
--   with. For example one useful encoder would be
--   <a>stringToHtmlString</a>. All attributes will be encoded once and
--   only once.
setEncoder :: Stringable a => (a -> a) -> StringTemplate a -> StringTemplate a
paddedTrans :: a -> [[a]] -> [[a]]
data SEnv a
SEnv :: SMap a -> [(String, SEnv a -> SElem a)] -> STGroup a -> (a -> a) -> SEnv a
smp :: SEnv a -> SMap a
sopts :: SEnv a -> [(String, SEnv a -> SElem a)]
sgen :: SEnv a -> STGroup a
senc :: SEnv a -> a -> a
parseSTMP :: Stringable a => (Char, Char) -> String -> Either String (SEnv a -> a)

-- | A special template that simply dumps the values of all the attributes
--   set in it. This may be made available to any template as a function by
--   adding it to its group. I.e. <tt> myNewGroup = addSuperGroup myGroup $
--   groupStringTemplates [(<a>dumpAttribs</a>, dumpAttribs)] </tt>
dumpAttribs :: Stringable a => StringTemplate a

-- | Returns a tuple of three Maybes. The first is set if there is a parse
--   error in the template. The next is set to a list of attributes that
--   have not been set, or Nothing if all attributes are set. The last is
--   set to a list of invoked templates that cannot be looked up, or
--   Nothing if all invoked templates can be found. Note that this check is
--   shallow -- i.e. missing attributes and templates are only caught in
--   the top level template, not any invoked subtemplate.
checkTemplate :: Stringable a => StringTemplate a -> (Maybe String, Maybe [String], Maybe [String])

-- | Returns a tuple of three lists. The first is of templates with parse
--   errors, and their erros. The next is of missing attributes, and the
--   last is of missing templates. If there are no errors, then all lists
--   will be empty.
checkTemplateDeep :: (Stringable a, NFData a) => StringTemplate a -> ([(String, String)], [String], [String])

-- | Gets all quasiquoted names, normal names &amp; templates used in a
--   given template. Must be passed a pair of chars denoting the delimeters
--   to be used.
parseSTMPNames :: (Char, Char) -> String -> Either ParseError ([String], [String], [String])
instance Typeable TmplException
instance Show TmplException
instance Exception TmplException


-- | This module provides stmp, a quasi-quoter for StringTemplate
--   expressions. Quoted templates are guaranteed syntactically well-formed
--   at compile time, and antiquotation (of identifiers only) is provided
--   by backticks. Usage: <tt> let var = [0,1,2] in toString
--   [$stmp|($`var`; separator = ', '$)|] === "(0, 1, 2)"</tt>
module Text.StringTemplate.QQ
stmp :: QuasiQuoter


-- | A StringTemplate is a String with "holes" in it. This is a port of the
--   Java StringTemplate library written by Terrence Parr.
--   (<a>http://www.stringtemplate.org</a>). User-contributed documentation
--   available at
--   <a>http://www.haskell.org/haskellwiki/HStringTemplate</a>.
--   
--   This library implements the basic 3.1 grammar, lacking group files
--   (though not groups themselves), Regions, and Interfaces. The goal is
--   not to blindly copy the StringTemplate API, but rather to take its
--   central ideas and implement them in a Haskellish manner. Indentation
--   and wrapping, for example, are implemented through the HughesPJ Pretty
--   Printing library. Calling toPPDoc on a StringTemplate yields a Doc
--   with appropriate paragraph-fill wrapping that can be rendered in the
--   usual fashion.
--   
--   Basic instances are provided of the StringTemplateShows and ToSElem
--   class. Any type deriving ToSElem can be passed automatically as a
--   StringTemplate attribute. This package can be installed with
--   syb-with-class bindings that provide a ToSElem instance for anything
--   deriving <a>Data</a>. When defining an instance of ToSElem that can
--   take a format parameter, you should first define an instance of
--   StringTemplateShows, and then define an instance of ToSElem where <tt>
--   toSElem = stShowsToSE</tt>.
module Text.StringTemplate

-- | A String with "holes" in it. StringTemplates may be composed of any
--   <a>Stringable</a> type, which at the moment includes <a>String</a>s,
--   <tt>ByteString</tt>s, PrettyPrinter <tt>Doc</tt>s, and <a>Endo</a>
--   <a>String</a>s, which are actually of type <a>ShowS</a>. When a
--   StringTemplate is composed of a type, its internals are as well, so it
--   is, so to speak "turtles all the way down."
data StringTemplate a

-- | A function that generates StringTemplates. This is conceptually a
--   query function into a "group" of StringTemplates.
type STGroup a = String -> (StFirst (StringTemplate a))

-- | The ToSElem class should be instantiated for all types that can be
--   inserted as attributes into a StringTemplate.
class ToSElem a where toSElemList = LI . map toSElem
toSElem :: (ToSElem a, Stringable b) => a -> SElem b
toSElemList :: (ToSElem a, Stringable b) => [a] -> SElem b

-- | The StringTemplateShows class should be instantiated for all types
--   that are directly displayed in a StringTemplate, but take an optional
--   format string. Each such type must have an appropriate ToSElem method
--   defined as well.
class Show a => StringTemplateShows a where stringTemplateShow = show stringTemplateFormattedShow = flip $ const . stringTemplateShow
stringTemplateShow :: StringTemplateShows a => a -> String
stringTemplateFormattedShow :: StringTemplateShows a => String -> a -> String

-- | This method should be used to create ToSElem instances for types
--   defining a custom formatted show function.
stShowsToSE :: (StringTemplateShows a, Stringable b) => a -> SElem b

-- | The Stringable class should be instantiated with care. Generally, the
--   provided instances should be enough for anything.
class Monoid a => Stringable a where stFromByteString = stFromText . decodeUtf8 stFromText = stFromString . unpack mconcatMap m k = foldr (mappend . k) mempty m mintercalate = (mconcat .) . intersperse mlabel x y = mconcat [x, stFromString "[", y, stFromString "]"]
stFromString :: Stringable a => String -> a
stFromByteString :: Stringable a => ByteString -> a
stFromText :: Stringable a => Text -> a
stToString :: Stringable a => a -> String
mconcatMap :: Stringable a => [b] -> (b -> a) -> a
mintercalate :: Stringable a => a -> [a] -> a
mlabel :: Stringable a => a -> a -> a
class Stringable b => SEType b a
renderf :: SEType b a => StringTemplate b -> a

-- | Parses a String to produce a StringTemplate, with '$'s as delimiters.
--   It is constructed with a stub group that cannot look up other
--   templates.
newSTMP :: Stringable a => String -> StringTemplate a

-- | Parses a String to produce a StringTemplate, delimited by angle
--   brackets. It is constructed with a stub group that cannot look up
--   other templates.
newAngleSTMP :: Stringable a => String -> StringTemplate a

-- | Queries an String Template Group and returns Just the appropriate
--   StringTemplate if it exists, otherwise, Nothing.
getStringTemplate :: Stringable a => String -> STGroup a -> Maybe (StringTemplate a)

-- | As with <a>getStringTemplate</a> but never inlined, so appropriate for
--   use with volatile template groups.
getStringTemplate' :: Stringable a => String -> STGroup a -> Maybe (StringTemplate a)

-- | Renders a StringTemplate to a String.
toString :: StringTemplate String -> String

-- | Renders a StringTemplate to a <a>Doc</a>.
toPPDoc :: StringTemplate Doc -> Doc

-- | Generic render function for a StringTemplate of any type.
render :: Stringable a => StringTemplate a -> a

-- | A special template that simply dumps the values of all the attributes
--   set in it. This may be made available to any template as a function by
--   adding it to its group. I.e. <tt> myNewGroup = addSuperGroup myGroup $
--   groupStringTemplates [(<a>dumpAttribs</a>, dumpAttribs)] </tt>
dumpAttribs :: Stringable a => StringTemplate a

-- | Returns a tuple of three Maybes. The first is set if there is a parse
--   error in the template. The next is set to a list of attributes that
--   have not been set, or Nothing if all attributes are set. The last is
--   set to a list of invoked templates that cannot be looked up, or
--   Nothing if all invoked templates can be found. Note that this check is
--   shallow -- i.e. missing attributes and templates are only caught in
--   the top level template, not any invoked subtemplate.
checkTemplate :: Stringable a => StringTemplate a -> (Maybe String, Maybe [String], Maybe [String])

-- | Returns a tuple of three lists. The first is of templates with parse
--   errors, and their erros. The next is of missing attributes, and the
--   last is of missing templates. If there are no errors, then all lists
--   will be empty.
checkTemplateDeep :: (Stringable a, NFData a) => StringTemplate a -> ([(String, String)], [String], [String])

-- | Yields a StringTemplate with the appropriate attribute set. If the
--   attribute already exists, it is appended to a list.
setAttribute :: (ToSElem a, Stringable b) => String -> a -> StringTemplate b -> StringTemplate b
(|=) :: Monad m => a -> m a1 -> m (a, a1)

-- | Yields a StringTemplate with the appropriate attributes set. If any
--   attribute already exists, it is appended to a list.
setManyAttrib :: (ToSElem a, Stringable b) => [(String, a)] -> StringTemplate b -> StringTemplate b

-- | Yields a StringTemplate with the appropriate attribute set. If the
--   attribute already exists, it is appended to a list. This will not
--   translate the attribute through any intermediate representation, so is
--   more efficient when, e.g. setting attributes that are large
--   bytestrings in a bytestring template.
setNativeAttribute :: Stringable b => String -> b -> StringTemplate b -> StringTemplate b

-- | Yields a StringTemplate with the appropriate attributes set. If any
--   attribute already exists, it is appended to a list. Attributes are
--   added natively, which may provide efficiency gains.
setManyNativeAttrib :: Stringable b => [(String, b)] -> StringTemplate b -> StringTemplate b

-- | Replaces the attributes of a StringTemplate with those described in
--   the second argument. If the argument does not yield a set of named
--   attributes but only a single one, that attribute is named, as a
--   default, "it".
withContext :: (ToSElem a, Stringable b) => StringTemplate b -> a -> StringTemplate b

-- | Adds a set of global options to a single template
optInsertTmpl :: [(String, String)] -> StringTemplate a -> StringTemplate a

-- | Adds a set of global options to a group
optInsertGroup :: [(String, String)] -> STGroup a -> STGroup a

-- | Sets an encoding function of a template that all values are rendered
--   with. For example one useful encoder would be
--   <a>stringToHtmlString</a>. All attributes will be encoded once and
--   only once.
setEncoder :: Stringable a => (a -> a) -> StringTemplate a -> StringTemplate a

-- | Sets an encoding function of a group that all values are rendered with
--   in each enclosed template
setEncoderGroup :: Stringable a => (a -> a) -> STGroup a -> STGroup a

-- | Given a list of named of StringTemplates, returns a group which
--   generates them such that they can call one another.
groupStringTemplates :: [(String, StringTemplate a)] -> STGroup a

-- | Adds a supergroup to any StringTemplate group such that templates from
--   the original group are now able to call ones from the supergroup as
--   well.
addSuperGroup :: STGroup a -> STGroup a -> STGroup a

-- | Adds a "subgroup" to any StringTemplate group such that templates from
--   the original group now have template calls "shadowed" by the subgroup.
addSubGroup :: STGroup a -> STGroup a -> STGroup a

-- | Merges two groups into a single group. This function is left-biased,
--   prefering bindings from the first group when there is a conflict.
mergeSTGroups :: STGroup a -> STGroup a -> STGroup a

-- | Given a path, returns a group which generates all files in said
--   directory which have the proper "st" extension. This function is
--   strict, with all files read once. As it performs file IO, expect it to
--   throw the usual exceptions.
directoryGroup :: Stringable a => FilePath -> IO (STGroup a)

-- | Given a path, returns a group which generates all files in said
--   directory which have the supplied extension.
directoryGroupExt :: Stringable a => FilePath -> FilePath -> IO (STGroup a)

-- | Given an integral amount of seconds and a path, returns a group
--   generating all files in said directory and subdirectories with the
--   proper "st" extension, cached for that amount of seconds. IO errors
--   are "swallowed" by this so that exceptions don't arise in unexpected
--   places. This violates referential transparency, but can be very useful
--   in developing templates for any sort of server application. It should
--   be swapped out for production purposes. The dumpAttribs template is
--   added to the returned group by default, as it should prove useful for
--   debugging and developing templates.
unsafeVolatileDirectoryGroup :: Stringable a => FilePath -> Int -> IO (STGroup a)

-- | As with <a>directoryGroup</a>, but traverses subdirectories as well. A
--   template named "foo<i>bar.st\" may be referenced by \"foo</i>bar" in
--   the returned group.
directoryGroupRecursive :: Stringable a => FilePath -> IO (STGroup a)

-- | See documentation for <a>directoryGroupRecursive</a>.
directoryGroupRecursiveLazy :: Stringable a => FilePath -> IO (STGroup a)

-- | As with <a>directoryGroupRecursive</a>, but a template extension is
--   supplied.
directoryGroupRecursiveExt :: Stringable a => FilePath -> FilePath -> IO (STGroup a)

-- | As with <a>directoryGroupRecursiveLazy</a>, but a template extension
--   is supplied.
directoryGroupRecursiveLazyExt :: Stringable a => FilePath -> FilePath -> IO (STGroup a)

-- | Given a path, returns a group which generates all files in said
--   directory which have the proper "st" extension. This function is lazy
--   in the same way that readFile is lazy, with all files read on demand,
--   but no more than once. The list of files, however, is generated at the
--   time the function is called. As this performs file IO, expect it to
--   throw the usual exceptions. And, as it is lazy, expect these
--   exceptions in unexpected places.
directoryGroupLazy :: Stringable a => FilePath -> IO (STGroup a)

-- | Given a path, returns a group which generates all files in said
--   directory which have the supplied extension.
directoryGroupLazyExt :: Stringable a => FilePath -> FilePath -> IO (STGroup a)

-- | For any requested template, returns a message that the template was
--   unable to be found. Useful to add as a super group for a set of
--   templates under development, to aid in debugging.
nullGroup :: Stringable a => STGroup a