-- 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.4.3

module Text.StringTemplate.Classes
data SElem a
STR :: String -> SElem a
STSH :: STShow -> SElem a
SM :: (SMap a) -> SElem a
LI :: [SElem a] -> SElem a
SBLE :: 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
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
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
stFromString :: (Stringable a) => String -> 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 ByteString
instance Stringable ByteString
instance Monoid Doc
instance Stringable Doc
instance Stringable [Char]
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 -> (SEnv a -> a) -> StringTemplate a
senv :: StringTemplate a -> SEnv a
runSTMP :: StringTemplate a -> SEnv a -> 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
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
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
stFromString :: (Stringable a) => String -> 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 <tt>Text.PrettyPrint.HughesPJ.Doc</tt>.
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

-- | 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
--   <tt>Text.Html.stringToHtmlString</tt>. All attributes will be encoded
--   once and only once.
setEncoder :: (Stringable a) => (String -> String) -> StringTemplate a -> StringTemplate a
paddedTrans :: a -> [[a]] -> [[a]]
data SEnv a
SEnv :: SMap a -> [(String, SEnv a -> SElem a)] -> STGroup a -> (String -> String) -> SEnv a
smp :: SEnv a -> SMap a
sopts :: SEnv a -> [(String, SEnv a -> SElem a)]
sgen :: SEnv a -> STGroup a
senc :: SEnv a -> String -> String
parseSTMP :: (Stringable a) => (Char, Char) -> 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


-- | Generic Instance for ToSElem using syb-with-class. Inspired
--   heavily-to-entirely by Alex Drummond's RJson.
module Text.StringTemplate.GenericWithClass
instance [overlap ok] (Data ToSElemD t) => ToSElem t
instance [overlap ok] (ToSElem a, Data ToSElemD a) => Sat (ToSElemD a)


-- | 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>).
--   
--   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.
--   
--   This library extends the current StringTemplate grammar by allowing
--   the application of alternating attributes to anonymous as well as
--   regular templates, including therefore sets of alternating attributes.
--   
--   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 <tt>Data.Generics.SYB.WithClass.Basics.Data</tt>. 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
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
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
stFromString :: (Stringable a) => String -> 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 <tt>Text.PrettyPrint.HughesPJ.Doc</tt>.
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

-- | 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

-- | 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
--   <tt>Text.Html.stringToHtmlString</tt>. All attributes will be encoded
--   once and only once.
setEncoder :: (Stringable a) => (String -> String) -> StringTemplate a -> StringTemplate a

-- | Sets an encoding function of a group that all values are rendered with
--   in each enclosed template
setEncoderGroup :: (Stringable a) => (String -> String) -> 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 an integral amount of seconds and a path, returns a group
--   generating all files in said directory 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) => String -> Int -> 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. As it 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)

-- | 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