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


-- | An implementation of the Jinja2 template language in Haskell
--   
--   Ginger is Jinja, minus the most blatant pythonisms. Wants to be
--   feature complete, but isn't quite there yet.
@package ginger
@version 0.3.5.1

module Text.PrintfA
data PrintfArgT
P :: a -> PrintfArgT
data PrintfTypeT
T :: (forall r. PrintfType r => r) -> PrintfTypeT
[unT] :: PrintfTypeT -> forall r. PrintfType r => r
printfa :: PrintfType t => String -> [PrintfArgT] -> t


-- | A HTML type, useful for implementing type-safe conversion between
--   plain text and HTML. The HTML representation used here assumed Unicode
--   throughout, and UTF-8 should be used as the encoding when sending
--   <tt>Html</tt> objects as responses to a HTTP client.
module Text.Ginger.Html

-- | A chunk of HTML source.
data Html

-- | Convert a chunk of HTML source code into an <tt>Html</tt> value as-is.
--   Note that this bypasses any and all HTML encoding; the caller is
--   responsible for taking appropriate measures against XSS and other
--   potential vulnerabilities. In other words, the input to this function
--   is considered pre-sanitized.
unsafeRawHtml :: Text -> Html

-- | Safely convert plain text to HTML.
html :: Text -> Html

-- | Extract HTML source code from an <tt>Html</tt> value.
htmlSource :: Html -> Text

-- | Types that support conversion to HTML.
class ToHtml s
toHtml :: ToHtml s => s -> Html
instance GHC.Classes.Ord Text.Ginger.Html.Html
instance GHC.Classes.Eq Text.Ginger.Html.Html
instance GHC.Show.Show Text.Ginger.Html.Html
instance GHC.Base.Monoid Text.Ginger.Html.Html
instance Text.Ginger.Html.ToHtml Data.Text.Internal.Text
instance Text.Ginger.Html.ToHtml [GHC.Types.Char]
instance Text.Ginger.Html.ToHtml Text.Ginger.Html.Html


-- | GVal is a generic unitype value, representing the kind of values that
--   Ginger can understand.
--   
--   Most of the types in this module are parametrized over an <tt>m</tt>
--   type, which is the host monad for template execution, as passed to
--   <tt>runGingerT</tt>. For most kinds of values, <tt>m</tt> is
--   transparent, and in many cases a <a>ToGVal</a> instance can be written
--   that works for all possible <tt>m</tt>; the reason we need to
--   parametrize the values themselves over the carrier monad is because we
--   want to support impure functions, which requires access to the
--   underlying carrier monad (e.g. <tt>IO</tt>).
module Text.Ginger.GVal

-- | A variant type designed as the unitype for the template language. Any
--   value referenced in a template, returned from within a template, or
--   used in a template context, will be a <a>GVal</a>. <tt>m</tt>, in most
--   cases, should be a <a>Monad</a>.
--   
--   Some laws apply here, most notably:
--   
--   <ul>
--   <li>when <a>isNull</a> is <a>True</a>, then all of <a>asFunction</a>,
--   <a>asText</a>, <a>asNumber</a>, <a>asHtml</a>, <a>asList</a>,
--   <a>asDictItems</a>, and <a>length</a> should produce
--   <a>Nothing</a></li>
--   <li>when <a>isNull</a> is <a>True</a>, then <a>asBoolean</a> should
--   produce <a>False</a></li>
--   <li>when <a>asNumber</a> is not <a>Nothing</a>, then <a>asBoolean</a>
--   should only return <a>False</a> for exactly zero</li>
--   <li><a>Nothing</a>-ness of <a>length</a> should match one or both of
--   <a>asList</a> / <a>asDictItems</a></li>
--   </ul>
data GVal m
GVal :: Maybe [GVal m] -> Maybe [(Text, GVal m)] -> Maybe (Text -> Maybe (GVal m)) -> Html -> Text -> Bool -> Maybe Scientific -> Maybe (Function m) -> Maybe Int -> Bool -> Maybe Value -> GVal m

-- | Convert value to list, if possible
[asList] :: GVal m -> Maybe [GVal m]

-- | Convert value to association list ("dictionary"), if possible
[asDictItems] :: GVal m -> Maybe [(Text, GVal m)]

-- | Convert value to a lookup function
[asLookup] :: GVal m -> Maybe (Text -> Maybe (GVal m))

-- | Render value as HTML
[asHtml] :: GVal m -> Html

-- | Render value as plain-text
[asText] :: GVal m -> Text

-- | Get value's truthiness
[asBoolean] :: GVal m -> Bool

-- | Convert value to a number, if possible
[asNumber] :: GVal m -> Maybe Scientific

-- | Access value as a callable function, if it is one
[asFunction] :: GVal m -> Maybe (Function m)

-- | Get length of value, if it is a collection (list/dict)
[length] :: GVal m -> Maybe Int

-- | Check if the value is null
[isNull] :: GVal m -> Bool

-- | Provide a custom JSON representation of the value
[asJSON] :: GVal m -> Maybe Value

-- | Marshal a GVal between carrier monads. This will lose
--   <a>asFunction</a> information, because functions cannot be transferred
--   to other carrier monads, but it will keep all other data structures
--   intact.
marshalGVal :: GVal m -> GVal n

-- | Convenience wrapper around <a>asDictItems</a> to represent a
--   <a>GVal</a> as a <a>HashMap</a>.
asHashMap :: GVal m -> Maybe (HashMap Text (GVal m))

-- | The default <a>GVal</a> is equivalent to NULL.

-- | Conversion to JSON values attempts the following conversions, in
--   order:
--   
--   <ul>
--   <li>check the <a>isNull</a> property; if it is <a>True</a>, always
--   return <tt>Null</tt>, even if the GVal implements <a>asJSON</a></li>
--   <li><a>asJSON</a></li>
--   <li><a>asList</a></li>
--   <li><a>asDictItems</a> (through <a>asHashMap</a>)</li>
--   <li><a>asNumber</a></li>
--   <li><a>asText</a></li>
--   </ul>
--   
--   Note that the default conversions will never return booleans unless
--   <a>asJSON</a> explicitly does this, because <a>asText</a> will always
--   return *something*.

-- | For convenience, <a>Show</a> is implemented in a way that looks
--   similar to JavaScript / JSON

-- | Converting to HTML hooks into the ToHtml instance for <a>Text</a> for
--   most tags. Tags that have no obvious textual representation render as
--   empty HTML.

-- | A function that can be called from within a template execution
--   context.
type Function m = [(Maybe Text, GVal m)] -> m (GVal m)

-- | Match arguments passed to a function at runtime against a list of
--   declared argument names. <tt>matchFuncArgs argNames argsPassed</tt>
--   returns <tt>(matchedArgs, positionalArgs, namedArgs)</tt>, where
--   <tt>matchedArgs</tt> is a list of arguments matched against declared
--   names (by name or by position), <tt>positionalArgs</tt> are the unused
--   positional (unnamed) arguments, and <tt>namedArgs</tt> are the unused
--   named arguments.
matchFuncArgs :: [Text] -> [(Maybe Text, GVal m)] -> (HashMap Text (GVal m), [GVal m], HashMap Text (GVal m))

-- | Types that implement conversion to <a>GVal</a>.
class ToGVal m a
toGVal :: ToGVal m a => a -> GVal m

-- | Trivial instance for <a>GVal</a> itself.

-- | <a>Nothing</a> becomes NULL, <a>Just</a> unwraps.

-- | Haskell lists become list-like <a>GVal</a>s

-- | <a>HashMap</a> of <a>Text</a> becomes a dictionary-like <a>GVal</a>
dayToDict :: Day -> [(Text, GVal m)]
timeToDict :: TimeOfDay -> [(Text, GVal m)]
localTimeToDict :: LocalTime -> [(Text, GVal m)]
timeZoneToDict :: TimeZone -> [(Text, GVal m)]
timeLocaleToDict :: TimeLocale -> [(Text, GVal m)]
zonedTimeToDict :: ZonedTime -> [(Text, GVal m)]

-- | Silly helper function, needed to bypass the default <a>Show</a>
--   instance of <a>Scientific</a> in order to make integral
--   <a>Scientific</a>s look like integers.
scientificToText :: Scientific -> Text

-- | Booleans render as 1 or empty string, and otherwise behave as
--   expected.

-- | <tt>String</tt> -&gt; <a>GVal</a> conversion uses the <a>IsString</a>
--   class; because <tt>String</tt> is an alias for '[Char]', there is also
--   a <a>ToGVal</a> instance for <tt>String</tt>, but it marshals strings
--   as lists of characters, i.e., calling <a>toGVal</a> on a string
--   produces a list of characters on the <a>GVal</a> side.

-- | Single characters are treated as length-1 <a>Text</a>s.

-- | This instance is slightly wrong; the <a>asBoolean</a>,
--   <a>asNumber</a>, and <a>asText</a> methods all treat the HTML source
--   as plain text. We do this to avoid parsing the HTML back into a
--   <a>Text</a> (and dealing with possible parser errors); the reason this
--   instance exists at all is that we still want to be able to pass
--   pre-rendered HTML around sometimes, and as long as we don't call any
--   numeric or string functions on it, everything is fine. When such HTML
--   values accidentally do get used as strings, the HTML source will bleed
--   into the visible text, but at least this will not introduce an XSS
--   vulnerability.
--   
--   It is therefore recommended to avoid passing <a>Html</a> values into
--   templates, and also to avoid calling any string functions on
--   <a>Html</a> values inside templates (e.g. capturing macro output and
--   then passing it through a textual filter).

-- | Convert Aeson <tt>Value</tt>s to <a>GVal</a>s over an arbitrary host
--   monad. Because JSON cannot represent functions, this conversion will
--   never produce a <a>Function</a>. Further, the <tt>ToJSON</tt> instance
--   for such a <a>GVal</a> will always produce the exact <tt>Value</tt>
--   that was use to construct the it.
rawJSONToGVal :: Value -> GVal m

-- | Turn a <a>Function</a> into a <a>GVal</a>
fromFunction :: Function m -> GVal m

-- | A key/value pair, used for constructing dictionary GVals using a
--   compact syntax.
type Pair m = (Text, GVal m)

-- | Construct a dictionary GVal from a list of pairs. Internally, this
--   uses a hashmap, so element order will not be preserved.
dict :: [Pair m] -> GVal m

-- | Construct an ordered dictionary GVal from a list of pairs. Internally,
--   this conversion uses both a hashmap (for O(1) lookup) and the original
--   list, so element order is preserved, but there is a bit of a memory
--   overhead.
orderedDict :: [Pair m] -> GVal m

-- | Construct a pair from a key and a value.
(~>) :: ToGVal m a => Text -> a -> Pair m
infixr 8 ~>
type Cons m = [GVal m]

-- | Alias for '(~:)'.
gcons :: ToGVal m a => a -> Cons m -> Cons m

-- | This operator allows constructing heterogenous lists using cons-style
--   syntax, e.g.:
--   
--   <pre>
--   &gt;&gt;&gt; asText $ list ("Found " ~: (6 :: Int) ~: " items" ~: [] :: [GVal IO])
--   "Found 6 items"
--   </pre>
(~:) :: ToGVal m a => a -> Cons m -> Cons m
infixr 5 ~:

-- | Construct a GVal from a list of GVals. This is equivalent to the
--   <a>toGVal</a> implementation of <tt>[GVal m]</tt>, but typed more
--   narrowly for clarity and disambiguation.
list :: Cons m -> GVal m

-- | Check if the given GVal is a list-like object
isList :: GVal m -> Bool

-- | Check if the given GVal is a dictionary-like object
isDict :: GVal m -> Bool

-- | Treat a <a>GVal</a> as a flat list and look up a value by integer
--   index. If the value is not a List, or if the index exceeds the list
--   length, return <a>Nothing</a>.
lookupIndex :: Int -> GVal m -> Maybe (GVal m)

-- | Helper function; look up a value by an integer index when the index
--   may or may not be available. If no index is given, return
--   <a>Nothing</a>.
lookupIndexMay :: Maybe Int -> GVal m -> Maybe (GVal m)

-- | Strictly-typed lookup: treat value as a dictionary-like object and
--   look up the value at a given key.
lookupKey :: Text -> GVal m -> Maybe (GVal m)

-- | Loosely-typed lookup: try dictionary-style lookup first (treat index
--   as a string, and container as a dictionary), if that doesn't yield
--   anything (either because the index is not string-ish, or because the
--   container doesn't provide dictionary-style access), try index-based
--   lookup.
lookupLoose :: GVal m -> GVal m -> Maybe (GVal m)

-- | Like <a>lookupLoose</a>, but fall back to the given default value if
--   the key is not in the dictionary, or if the indexee is not a
--   dictionary-like object.
lookupLooseDef :: GVal m -> GVal m -> GVal m -> GVal m
(~!) :: (FromGVal m v) => GVal m -> GVal m -> Maybe v

-- | Treat a <a>GVal</a> as a dictionary and list all the keys, with no
--   particular ordering.
keys :: GVal m -> Maybe [Text]

-- | Convert a <a>GVal</a> to a number.
toNumber :: GVal m -> Maybe Scientific

-- | Convert a <a>GVal</a> to an <a>Int</a>. The conversion will fail when
--   the value is not numeric, and also if it is too large to fit in an
--   <a>Int</a>.
toInt :: GVal m -> Maybe Int

-- | Convert a <a>GVal</a> to an <a>Int</a>, falling back to the given
--   default if the conversion fails.
toIntDef :: Int -> GVal m -> Int

-- | Convert a <a>GVal</a> to an <a>Int</a>, falling back to zero (0) if
--   the conversion fails.
toInt0 :: GVal m -> Int

-- | Loose cast to boolean.
--   
--   Numeric zero, empty strings, empty lists, empty objects,
--   <tt>Null</tt>, and boolean <a>False</a> are considered falsy, anything
--   else (including functions) is considered true-ish.
toBoolean :: GVal m -> Bool

-- | Dynamically cast to a function. This yields <a>Just</a> a
--   <a>Function</a> if the value is a function, <a>Nothing</a> if it's
--   not.
toFunction :: GVal m -> Maybe (Function m)
picoToScientific :: Pico -> Scientific
scientificToPico :: Scientific -> Pico
class FromGVal m a where fromGValEither = maybe (Left "Conversion from GVal failed") Right . fromGVal fromGVal = either (const Nothing) Just . fromGValEither
fromGValEither :: FromGVal m a => GVal m -> Either String a
fromGVal :: FromGVal m a => GVal m -> Maybe a
fromGValM :: (Monad m, FromGVal m a) => GVal m -> m a
pairwise :: (a -> b) -> (a, a) -> (b, b)
packPair :: ([Char], [Char]) -> (Text, Text)
unpackPair :: (Text, Text) -> ([Char], [Char])
instance Data.Default.Class.Default (Text.Ginger.GVal.GVal m)
instance Data.Aeson.Types.ToJSON.ToJSON (Text.Ginger.GVal.GVal m)
instance GHC.Show.Show (Text.Ginger.GVal.GVal m)
instance Text.Ginger.Html.ToHtml (Text.Ginger.GVal.GVal m)
instance Text.Printf.PrintfArg (Text.Ginger.GVal.GVal m)
instance Text.Ginger.GVal.ToGVal m (Text.Ginger.GVal.GVal m)
instance Text.Ginger.GVal.ToGVal m v => Text.Ginger.GVal.ToGVal m (GHC.Base.Maybe v)
instance Text.Ginger.GVal.ToGVal m v => Text.Ginger.GVal.ToGVal m [v]
instance Text.Ginger.GVal.ToGVal m v => Text.Ginger.GVal.ToGVal m (Data.HashMap.Base.HashMap Data.Text.Internal.Text v)
instance Text.Ginger.GVal.ToGVal m GHC.Types.Int
instance Text.Ginger.GVal.ToGVal m GHC.Integer.Type.Integer
instance Text.Ginger.GVal.ToGVal m Data.Scientific.Scientific
instance Text.Ginger.GVal.ToGVal m Data.Time.Calendar.Days.Day
instance Text.Ginger.GVal.ToGVal m Data.Time.LocalTime.TimeOfDay.TimeOfDay
instance Text.Ginger.GVal.ToGVal m Data.Time.LocalTime.LocalTime.LocalTime
instance Text.Ginger.GVal.ToGVal m Data.Time.LocalTime.TimeZone.TimeZone
instance Text.Ginger.GVal.ToGVal m Data.Time.Format.Locale.TimeLocale
instance Text.Ginger.GVal.ToGVal m Data.Time.LocalTime.LocalTime.ZonedTime
instance (Text.Ginger.GVal.ToGVal m a, Text.Ginger.GVal.ToGVal m b) => Text.Ginger.GVal.ToGVal m (a, b)
instance (Text.Ginger.GVal.ToGVal m a, Text.Ginger.GVal.ToGVal m b, Text.Ginger.GVal.ToGVal m c) => Text.Ginger.GVal.ToGVal m (a, b, c)
instance (Text.Ginger.GVal.ToGVal m a, Text.Ginger.GVal.ToGVal m b, Text.Ginger.GVal.ToGVal m c, Text.Ginger.GVal.ToGVal m d) => Text.Ginger.GVal.ToGVal m (a, b, c, d)
instance Text.Ginger.GVal.ToGVal m GHC.Types.Bool
instance Data.String.IsString (Text.Ginger.GVal.GVal m)
instance Text.Ginger.GVal.ToGVal m GHC.Types.Char
instance Text.Ginger.GVal.ToGVal m Data.Text.Internal.Text
instance Text.Ginger.GVal.ToGVal m Data.Text.Internal.Lazy.Text
instance Text.Ginger.GVal.ToGVal m Text.Ginger.Html.Html
instance Text.Ginger.GVal.ToGVal m Data.Aeson.Types.Internal.Value
instance Text.Ginger.GVal.FromGVal m GHC.Types.Int
instance Text.Ginger.GVal.FromGVal m Data.Scientific.Scientific
instance Text.Ginger.GVal.FromGVal m Data.Text.Internal.Text
instance Text.Ginger.GVal.FromGVal m (Text.Ginger.GVal.GVal m)
instance Text.Ginger.GVal.FromGVal m a => Text.Ginger.GVal.FromGVal m (GHC.Base.Maybe a)
instance Text.Ginger.GVal.FromGVal m GHC.Types.Bool
instance Text.Ginger.GVal.FromGVal m Data.Aeson.Types.Internal.Value
instance Text.Ginger.GVal.FromGVal m ()
instance Text.Ginger.GVal.FromGVal m a => Text.Ginger.GVal.FromGVal m [a]
instance (Text.Ginger.GVal.FromGVal m a, Text.Ginger.GVal.FromGVal m b) => Text.Ginger.GVal.FromGVal m (a, b)
instance (Text.Ginger.GVal.FromGVal m a, Text.Ginger.GVal.FromGVal m b, Text.Ginger.GVal.FromGVal m c) => Text.Ginger.GVal.FromGVal m (a, b, c)
instance (Text.Ginger.GVal.FromGVal m a, Text.Ginger.GVal.FromGVal m b, Text.Ginger.GVal.FromGVal m c, Text.Ginger.GVal.FromGVal m d) => Text.Ginger.GVal.FromGVal m (a, b, c, d)
instance Text.Ginger.GVal.FromGVal m Data.Time.Calendar.Days.Day
instance Text.Ginger.GVal.FromGVal m Data.Time.LocalTime.TimeOfDay.TimeOfDay
instance Text.Ginger.GVal.FromGVal m Data.Time.LocalTime.LocalTime.LocalTime
instance Text.Ginger.GVal.FromGVal m Data.Time.LocalTime.LocalTime.ZonedTime
instance Text.Ginger.GVal.FromGVal m Data.Time.LocalTime.TimeZone.TimeZone
instance Text.Ginger.GVal.FromGVal m Data.Time.Format.Locale.TimeLocale


-- | Implements Ginger's Abstract Syntax Tree.
module Text.Ginger.AST

-- | A context variable name.
type VarName = Text

-- | Top-level data structure, representing a fully parsed template.
data Template
Template :: Statement -> HashMap VarName Block -> Maybe Template -> Template
[templateBody] :: Template -> Statement
[templateBlocks] :: Template -> HashMap VarName Block
[templateParent] :: Template -> Maybe Template

-- | A macro definition ( <tt>{% macro %}</tt> )
data Macro
Macro :: [VarName] -> Statement -> Macro
[macroArgs] :: Macro -> [VarName]
[macroBody] :: Macro -> Statement

-- | A block definition ( <tt>{% block %}</tt> )
data Block
Block :: Statement -> Block
[blockBody] :: Block -> Statement

-- | Ginger statements.
data Statement

-- | A sequence of multiple statements
MultiS :: [Statement] -> Statement

-- | Run wrapped statement in a local scope
ScopedS :: Statement -> Statement

-- | Literal output (anything outside of any tag)
LiteralS :: Html -> Statement

-- | {{ expression }}
InterpolationS :: Expression -> Statement

-- | {% if expression %}statement{% else %}statement{% endif %}
IfS :: Expression -> Statement -> Statement -> Statement

-- | {% for index, varname in expression %}statement{% endfor %}
ForS :: (Maybe VarName) -> VarName -> Expression -> Statement -> Statement

-- | {% set varname = expr %}
SetVarS :: VarName -> Expression -> Statement

-- | {% macro varname %}statements{% endmacro %}
DefMacroS :: VarName -> Macro -> Statement
BlockRefS :: VarName -> Statement

-- | {% include "template" %}
PreprocessedIncludeS :: Template -> Statement

-- | The do-nothing statement (NOP)
NullS :: Statement

-- | Expressions, building blocks for the expression minilanguage.
data Expression

-- | String literal expression: "foobar"
StringLiteralE :: Text -> Expression

-- | Numeric literal expression: 123.4
NumberLiteralE :: Scientific -> Expression

-- | Boolean literal expression: true
BoolLiteralE :: Bool -> Expression

-- | Literal null
NullLiteralE :: Expression

-- | Variable reference: foobar
VarE :: VarName -> Expression

-- | List construct: [ expr, expr, expr ]
ListE :: [Expression] -> Expression

-- | Object construct: { expr: expr, expr: expr, ... }
ObjectE :: [(Expression, Expression)] -> Expression

-- | foo[bar] (also dot access)
MemberLookupE :: Expression -> Expression -> Expression

-- | foo(bar=baz, quux)
CallE :: Expression -> [(Maybe Text, Expression)] -> Expression

-- | (foo, bar) -&gt; expr
LambdaE :: [Text] -> Expression -> Expression

-- | expr ? expr : expr
TernaryE :: Expression -> Expression -> Expression -> Expression
instance GHC.Show.Show Text.Ginger.AST.Block
instance GHC.Show.Show Text.Ginger.AST.Template
instance GHC.Show.Show Text.Ginger.AST.Macro
instance GHC.Show.Show Text.Ginger.AST.Statement
instance GHC.Show.Show Text.Ginger.AST.Expression


-- | A syntax tree optimizer
module Text.Ginger.Optimizer
class Optimizable a
optimize :: Optimizable a => a -> a
instance Text.Ginger.Optimizer.Optimizable Text.Ginger.AST.Template
instance Text.Ginger.Optimizer.Optimizable Text.Ginger.AST.Statement
instance Text.Ginger.Optimizer.Optimizable Text.Ginger.AST.Block
instance Text.Ginger.Optimizer.Optimizable Text.Ginger.AST.Macro
instance Text.Ginger.Optimizer.Optimizable Text.Ginger.AST.Expression


-- | Ginger parser.
module Text.Ginger.Parse

-- | Parse Ginger source from memory.
parseGinger :: Monad m => IncludeResolver m -> Maybe SourceName -> Source -> m (Either ParserError Template)

-- | Parse Ginger source from a file.
parseGingerFile :: Monad m => IncludeResolver m -> SourceName -> m (Either ParserError Template)

-- | Error information for Ginger parser errors.
data ParserError
ParserError :: String -> Maybe SourceName -> Maybe Int -> Maybe Int -> ParserError

-- | Human-readable error message
[peErrorMessage] :: ParserError -> String

-- | Source name, if any
[peSourceName] :: ParserError -> Maybe SourceName

-- | Line number, if available
[peSourceLine] :: ParserError -> Maybe Int

-- | Column number, if available
[peSourceColumn] :: ParserError -> Maybe Int

-- | Used to resolve includes. Ginger will call this function whenever it
--   encounters an {% include %}, {% import %}, or {% extends %} directive.
--   If the required source code is not available, the resolver should
--   return <tt>Nothing</tt>, else <tt>Just</tt> the source.
type IncludeResolver m = SourceName -> m (Maybe Source)

-- | Input type for the parser (source code).
type Source = String

-- | A source identifier (typically a filename).
type SourceName = String
instance GHC.Generics.Generic Text.Ginger.Parse.ParserError
instance GHC.Show.Show Text.Ginger.Parse.ParserError
instance GHC.Exception.Exception Text.Ginger.Parse.ParserError

module Text.Ginger.Run.FuncUtils
unaryFunc :: forall m h. (Monad m) => (GVal (Run m h) -> GVal (Run m h)) -> Function (Run m h)
ignoreArgNames :: ([a] -> b) -> ([(c, a)] -> b)
variadicNumericFunc :: Monad m => Scientific -> ([Scientific] -> Scientific) -> [(Maybe Text, GVal (Run m h))] -> Run m h (GVal (Run m h))
unaryNumericFunc :: Monad m => Scientific -> (Scientific -> Scientific) -> [(Maybe Text, GVal (Run m h))] -> Run m h (GVal (Run m h))
variadicStringFunc :: Monad m => ([Text] -> Text) -> [(Maybe Text, GVal (Run m h))] -> Run m h (GVal (Run m h))

-- | Match args according to a given arg spec, Python style. The return
--   value is a triple of <tt>(matched, args, kwargs, unmatchedNames)</tt>,
--   where <tt>matches</tt> is a hash map of named captured arguments, args
--   is a list of remaining unmatched positional arguments, kwargs is a
--   list of remaining unmatched named arguments, and
--   <tt>unmatchedNames</tt> contains the argument names that haven't been
--   matched.
extractArgs :: [Text] -> [(Maybe Text, a)] -> (HashMap Text a, [a], HashMap Text a, [Text])

-- | Parse argument list into type-safe argument structure.
extractArgsT :: ([Maybe a] -> b) -> [Text] -> [(Maybe Text, a)] -> Either ([a], HashMap Text a, [Text]) b

-- | Parse argument list into flat list of matched arguments.
extractArgsL :: [Text] -> [(Maybe Text, a)] -> Either ([a], HashMap Text a, [Text]) [Maybe a]
extractArgsDefL :: [(Text, a)] -> [(Maybe Text, a)] -> Either ([a], HashMap Text a, [Text]) [a]
injectDefaults :: [a] -> [Maybe a] -> [a]

module Text.Ginger.Run.VM

-- | Helper function to run a State action with a temporary state,
--   reverting to the old state after the action has finished.
withLocalState :: (Monad m, MonadState s m) => m a -> m a

-- | Helper function to run a Scope action with a temporary scope,
--   reverting to the old scope after the action has finished.
withLocalScope :: (Monad m) => Run m h a -> Run m h a
setVar :: Monad m => VarName -> GVal (Run m h) -> Run m h ()
getVar :: Monad m => VarName -> Run m h (GVal (Run m h))
clearCapture :: (Monoid h, Monad m) => Run m h ()
appendCapture :: (Monoid h, Monad m) => h -> Run m h ()
fetchCapture :: Monad m => Run m h h


-- | Execute Ginger templates in an arbitrary monad.
--   
--   Usage example:
--   
--   <pre>
--   render :: Template -&gt; Text -&gt; Text -&gt; Text
--   render template -&gt; username imageURL = do
--      let contextLookup varName =
--              case varName of
--                  "username" -&gt; toGVal username
--                  "imageURL" -&gt; toGVal imageURL
--                  _ -&gt; def -- def for GVal is equivalent to a NULL value
--          context = makeContext contextLookup
--      in htmlSource $ runGinger context template
--   </pre>
module Text.Ginger.Run

-- | Monadically run a Ginger template. The <tt>m</tt> parameter is the
--   carrier monad.
runGingerT :: (ToGVal (Run m h) h, Monoid h, Monad m, Functor m) => GingerContext m h -> Template -> m ()

-- | Purely expand a Ginger template. The underlying carrier monad is
--   <a>Writer</a> <tt>h</tt>, which is used to collect the output and
--   render it into a <tt>h</tt> value.
runGinger :: (ToGVal (Run (Writer h) h) h, Monoid h) => GingerContext (Writer h) h -> Template -> h

-- | Execution context. Determines how to look up variables from the
--   environment, and how to write out template output.
data GingerContext m h

-- | <i>Deprecated: Compatibility alias for makeContextHtml</i>
makeContext :: (VarName -> GVal (Run (Writer Html) Html)) -> GingerContext (Writer Html) Html

-- | <i>Deprecated: Compatibility alias for makeContextHtmlM</i>
makeContextM :: (Monad m, Functor m) => (VarName -> Run m Html (GVal (Run m Html))) -> (Html -> m ()) -> GingerContext m Html

-- | Create an execution context for runGinger. The argument is a lookup
--   function that maps top-level context keys to ginger values.
--   <a>makeContext</a> is a specialized version of <a>makeContextM</a>,
--   targeting the <a>Writer</a> <a>Html</a> monad (which is what is used
--   for the non-monadic template interpreter <tt>runGinger</tt>).
--   
--   The type of the lookup function may look intimidating, but in most
--   cases, marshalling values from Haskell to Ginger is a matter of
--   calling <a>toGVal</a> on them, so the 'GVal (Run (Writer Html))' part
--   can usually be ignored. See the <a>GVal</a> module for details.
makeContext' :: Monoid h => (VarName -> GVal (Run (Writer h) h)) -> (GVal (Run (Writer h) h) -> h) -> GingerContext (Writer h) h

-- | Create an execution context for runGingerT. Takes a lookup function,
--   which returns ginger values into the carrier monad based on a lookup
--   key, and a writer function (outputting HTML by whatever means the
--   carrier monad provides, e.g. <tt>putStr</tt> for <tt>IO</tt>, or
--   <tt>tell</tt> for <tt>Writer</tt>s).
makeContextM' :: (Monad m, Functor m) => (VarName -> Run m h (GVal (Run m h))) -> (h -> m ()) -> (GVal (Run m h) -> h) -> GingerContext m h
makeContextHtml :: (VarName -> GVal (Run (Writer Html) Html)) -> GingerContext (Writer Html) Html
makeContextHtmlM :: (Monad m, Functor m) => (VarName -> Run m Html (GVal (Run m Html))) -> (Html -> m ()) -> GingerContext m Html
makeContextText :: (VarName -> GVal (Run (Writer Text) Text)) -> GingerContext (Writer Text) Text
makeContextTextM :: (Monad m, Functor m) => (VarName -> Run m Text (GVal (Run m Text))) -> (Text -> m ()) -> GingerContext m Text

-- | Internal type alias for our template-runner monad stack.
type Run m h = StateT (RunState m h) (ReaderT (GingerContext m h) m)

-- | Lift a value from the host monad <tt>m</tt> into the <a>Run</a> monad.
liftRun :: Monad m => m a -> Run m h a

-- | Lift a function from the host monad <tt>m</tt> into the <a>Run</a>
--   monad.
liftRun2 :: Monad m => (a -> m b) -> a -> Run m h b

-- | Match args according to a given arg spec, Python style. The return
--   value is a triple of <tt>(matched, args, kwargs, unmatchedNames)</tt>,
--   where <tt>matches</tt> is a hash map of named captured arguments, args
--   is a list of remaining unmatched positional arguments, kwargs is a
--   list of remaining unmatched named arguments, and
--   <tt>unmatchedNames</tt> contains the argument names that haven't been
--   matched.
extractArgs :: [Text] -> [(Maybe Text, a)] -> (HashMap Text a, [a], HashMap Text a, [Text])

-- | Parse argument list into type-safe argument structure.
extractArgsT :: ([Maybe a] -> b) -> [Text] -> [(Maybe Text, a)] -> Either ([a], HashMap Text a, [Text]) b

-- | Parse argument list into flat list of matched arguments.
extractArgsL :: [Text] -> [(Maybe Text, a)] -> Either ([a], HashMap Text a, [Text]) [Maybe a]
extractArgsDefL :: [(Text, a)] -> [(Maybe Text, a)] -> Either ([a], HashMap Text a, [Text]) [a]


-- | A Haskell implementation of the <a>Jinja2</a> template language.
--   
--   Ginger aims to be as close to the original Jinja language as possible,
--   but avoiding blatant pythonisms and features that make little sense
--   outside of an impure dynamic host language context, especially when
--   this would require sacrificing runtime performance.
module Text.Ginger