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

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

-- | Marshal a GVal between carrier monads. Unlike <a>marshalGVal</a>,
--   <a>asFunction</a> information is retained by hoisting them using the
--   provided hoisting functions. For <tt>Run</tt> monads, which is what
--   <a>GVal</a> is typically used with, the <tt>hoistRun</tt> function can
--   be used to construct suitable hoisting functions.
marshalGValEx :: (Functor m, Functor n) => (forall a. m a -> n a) -> (forall a. n a -> m a) -> GVal m -> GVal n
marshalFunction :: (Functor m, Functor n) => (forall a. m a -> n a) -> (forall a. n a -> m a) -> Function m -> Function 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 ()
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 a
Template :: Statement a -> HashMap VarName (Block a) -> Maybe (Template a) -> Template a
[templateBody] :: Template a -> Statement a
[templateBlocks] :: Template a -> HashMap VarName (Block a)
[templateParent] :: Template a -> Maybe (Template a)

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

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

-- | Ginger statements.
data Statement a

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

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

-- | Establish an indented context around the wrapped statement
IndentS :: a -> (Expression a) -> (Statement a) -> Statement a

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

-- | {{ expression }}
InterpolationS :: a -> (Expression a) -> Statement a

-- | Evaluate expression
ExpressionS :: a -> (Expression a) -> Statement a

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

-- | {% switch expression %}{% case expression %}statement{% endcase
--   %}...{% default %}statement{% enddefault %}{% endswitch %}
SwitchS :: a -> (Expression a) -> [(Expression a, Statement a)] -> (Statement a) -> Statement a

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

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

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

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

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

-- | Try <i> catch </i> finally
TryCatchS :: a -> (Statement a) -> [CatchBlock a] -> (Statement a) -> Statement a
stmtAnnotation :: Statement t -> t

-- | A <tt>catch</tt> block
data CatchBlock a
Catch :: Maybe Text -> Maybe VarName -> Statement a -> CatchBlock a
[catchWhat] :: CatchBlock a -> Maybe Text
[catchCaptureAs] :: CatchBlock a -> Maybe VarName
[catchBody] :: CatchBlock a -> Statement a

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

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

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

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

-- | Literal null
NullLiteralE :: a -> Expression a

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

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

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

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

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

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

-- | expr ? expr : expr
TernaryE :: a -> (Expression a) -> (Expression a) -> (Expression a) -> Expression a

-- | do { statement; }
DoE :: a -> (Statement a) -> Expression a
exprAnnotation :: Expression t -> t
class Annotated f
annotation :: Annotated f => f p -> p
instance GHC.Base.Functor Text.Ginger.AST.Block
instance GHC.Show.Show a => GHC.Show.Show (Text.Ginger.AST.Block a)
instance GHC.Base.Functor Text.Ginger.AST.Template
instance GHC.Show.Show a => GHC.Show.Show (Text.Ginger.AST.Template a)
instance GHC.Base.Functor Text.Ginger.AST.Macro
instance GHC.Show.Show a => GHC.Show.Show (Text.Ginger.AST.Macro a)
instance GHC.Base.Functor Text.Ginger.AST.CatchBlock
instance GHC.Show.Show a => GHC.Show.Show (Text.Ginger.AST.CatchBlock a)
instance GHC.Base.Functor Text.Ginger.AST.Statement
instance GHC.Show.Show a => GHC.Show.Show (Text.Ginger.AST.Statement a)
instance GHC.Base.Functor Text.Ginger.AST.Expression
instance GHC.Show.Show a => GHC.Show.Show (Text.Ginger.AST.Expression a)
instance Text.Ginger.AST.Annotated Text.Ginger.AST.Expression
instance Text.Ginger.AST.Annotated Text.Ginger.AST.Statement
instance Text.Ginger.AST.Annotated Text.Ginger.AST.Block
instance Text.Ginger.AST.Annotated Text.Ginger.AST.Macro
instance Text.Ginger.AST.Annotated Text.Ginger.AST.Template


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

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

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

-- | Parse Ginger source from memory.
parseGinger' :: Monad m => ParserOptions m -> Source -> m (Either ParserError (Template SourcePos))

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

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

-- | Human-readable error message
[peErrorMessage] :: ParserError -> String
[peSourcePosition] :: ParserError -> Maybe SourcePos
data ParserOptions m
ParserOptions :: IncludeResolver m -> Maybe SourceName -> Bool -> Bool -> Bool -> ParserOptions m
[poIncludeResolver] :: ParserOptions m -> IncludeResolver m
[poSourceName] :: ParserOptions m -> Maybe SourceName
[poKeepTrailingNewline] :: ParserOptions m -> Bool
[poLStripBlocks] :: ParserOptions m -> Bool
[poTrimBlocks] :: ParserOptions m -> Bool
mkParserOptions :: Monad m => IncludeResolver m -> ParserOptions m
formatParserError :: Maybe String -> ParserError -> String

-- | 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
type SourceName = String

-- | The abstract data type <tt>SourcePos</tt> represents source positions.
--   It contains the name of the source (i.e. file name), a line number and
--   a column number. <tt>SourcePos</tt> is an instance of the <a>Show</a>,
--   <a>Eq</a> and <a>Ord</a> class.
data SourcePos :: *

-- | Extracts the name of the source from a source position.
sourceName :: SourcePos -> SourceName

-- | Extracts the line number from a source position.
sourceLine :: SourcePos -> Line

-- | Extracts the column number from a source position.
sourceColumn :: SourcePos -> Column

-- | Set the name of the source.
setSourceName :: SourcePos -> SourceName -> SourcePos
instance GHC.Generics.Generic Text.Ginger.Parse.ParserError
instance GHC.Show.Show Text.Ginger.Parse.ParserError
instance Text.Ginger.GVal.ToGVal m Text.Parsec.Pos.SourcePos
instance GHC.Exception.Exception Text.Ginger.Parse.ParserError

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

-- | Override the encoder used for converting <a>GVal</a>s to the output
--   type. This can be used for things like temporarily disabling HTML
--   encoding.
withEncoder :: (ContextEncodable h, Monad m) => (GVal (Run p m h) -> h) -> Run p m h a -> Run p m h a
setVar :: Monad m => VarName -> GVal (Run p m h) -> Run p m h ()
getVar :: Monad m => VarName -> Run p m h (GVal (Run p m h))
clearCapture :: (Monoid h, Monad m) => Run p m h ()
appendCapture :: (Monoid h, Monad m) => h -> Run p m h ()
fetchCapture :: Monad m => Run p m h h


-- | Execute Ginger templates in an arbitrary monad.
--   
--   Usage example:
--   
--   <pre>
--   render :: Template -&gt; Text -&gt; Text -&gt; Text
--   render template 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 = makeContextHtml contextLookup
--      in htmlSource $ runGinger context template
--   </pre>
module Text.Ginger.Run

-- | Simplified interface to render a ginger template "into" a monad.
--   
--   <tt>easyRenderM emit context template</tt> renders the
--   <tt>template</tt> with the given <tt>context</tt> object (which should
--   represent some sort of dictionary-like object) by feeding any output
--   to the <tt>emit</tt> function.
easyRenderM :: (Monad m, ContextEncodable h, Monoid h, ToGVal (Run p m h) v, ToGVal (Run p m h) h, ToGVal (Run p m h) p) => (h -> m ()) -> v -> Template p -> m (Either (RuntimeError p) (GVal (Run p m h)))

-- | Simplified interface to render a ginger template in a pure fashion.
--   
--   <tt>easyRender context template</tt> renders the <tt>template</tt>
--   with the given <tt>context</tt> object (which should represent some
--   sort of dictionary-like object) by returning the concatenated output.
easyRender :: (ContextEncodable h, Monoid h, ToGVal (Run p (Writer h) h) v, ToGVal (Run p (Writer h) h) h, ToGVal (Run p (Writer h) h) p) => v -> Template p -> h
easyContext :: (Monad m, ContextEncodable h, ToGVal (Run p m h) v) => (h -> m ()) -> v -> GingerContext p m h

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

-- | 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 p (Writer h) h) h, ToGVal (Run p (Writer h) h) p, Monoid h) => GingerContext p (Writer h) h -> Template p -> h

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

-- | <i>Deprecated: Compatibility alias for makeContextHtmlM</i>
makeContextM :: (Monad m, Functor m) => (VarName -> Run p m Html (GVal (Run p m Html))) -> (Html -> m ()) -> GingerContext p 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 p (Writer h) h)) -> (GVal (Run p (Writer h) h) -> h) -> Maybe (Newlines h) -> GingerContext p (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 p m h (GVal (Run p m h))) -> (h -> m ()) -> (GVal (Run p m h) -> h) -> Maybe (Newlines h) -> GingerContext p m h
makeContextExM' :: (Monad m, Functor m) => (VarName -> Run p m h (GVal (Run p m h))) -> (h -> m ()) -> (RuntimeError p -> m ()) -> (GVal (Run p m h) -> h) -> Maybe (Newlines h) -> GingerContext p m h
makeContextHtml :: (VarName -> GVal (Run p (Writer Html) Html)) -> GingerContext p (Writer Html) Html
makeContextHtmlM :: (Monad m, Functor m) => (VarName -> Run p m Html (GVal (Run p m Html))) -> (Html -> m ()) -> GingerContext p m Html
makeContextHtmlExM :: (Monad m, Functor m) => (VarName -> Run p m Html (GVal (Run p m Html))) -> (Html -> m ()) -> (RuntimeError p -> m ()) -> GingerContext p m Html
makeContextText :: (VarName -> GVal (Run p (Writer Text) Text)) -> GingerContext p (Writer Text) Text
makeContextTextM :: (Monad m, Functor m) => (VarName -> Run p m Text (GVal (Run p m Text))) -> (Text -> m ()) -> GingerContext p m Text
makeContextTextExM :: (Monad m, Functor m) => (VarName -> Run p m Text (GVal (Run p m Text))) -> (Text -> m ()) -> (RuntimeError p -> m ()) -> GingerContext p m Text

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

-- | Internal type alias for our template-runner monad stack.
type Run p m h = ExceptT (RuntimeError p) (StateT (RunState p m h) (ReaderT (GingerContext p 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 p 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 p 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]

-- | Hoist a context onto a different output type. <tt>hoistContext fwd rev
--   context</tt> returns a context over a different output type, applying
--   the <tt>fwd</tt> and <tt>rev</tt> projections to convert between the
--   original and desired output types.
hoistContext :: Monad m => (h -> t) -> (t -> h) -> GingerContext p m h -> GingerContext p m t

-- | Hoist a <a>Run</a> action onto a different output type. <tt>hoistRun
--   fwd rev action</tt> hoists the <tt>action</tt> from <tt>Run p m h
--   a</tt> to <tt>Run p m t a</tt>, applying <tt>fwd</tt> and <tt>rev</tt>
--   to convert between the output types.
hoistRun :: Monad m => (h -> t) -> (t -> h) -> Run p m h a -> Run p m t a

-- | Hoist a <a>Newlines</a> onto a different output type. You don't
--   normally need to use this directly; see <a>hoistRun</a> and/or
--   <a>hoistContext</a>.
hoistNewlines :: (h -> t) -> (t -> h) -> Newlines h -> Newlines t

-- | Hoist a <a>RunState</a> onto a different output type. You don't
--   normally need to use this directly; see <a>hoistRun</a> and/or
--   <a>hoistContext</a>.
hoistRunState :: Monad m => (h -> t) -> (t -> h) -> RunState p m h -> RunState p m t


-- | A syntax tree optimizer
module Text.Ginger.Optimizer
class Optimizable a
optimize :: Optimizable a => a -> a
instance GHC.Base.Monoid Text.Ginger.Optimizer.Collected
instance GHC.Enum.Bounded Text.Ginger.Optimizer.Purity
instance GHC.Classes.Ord Text.Ginger.Optimizer.Purity
instance GHC.Read.Read Text.Ginger.Optimizer.Purity
instance GHC.Enum.Enum Text.Ginger.Optimizer.Purity
instance GHC.Classes.Eq Text.Ginger.Optimizer.Purity
instance GHC.Show.Show Text.Ginger.Optimizer.Purity
instance Text.Ginger.Optimizer.Optimizable (Text.Ginger.AST.Template a)
instance Text.Ginger.Optimizer.Optimizable (Text.Ginger.AST.Statement a)
instance Text.Ginger.Optimizer.Optimizable (Text.Ginger.AST.Block a)
instance Text.Ginger.Optimizer.Optimizable (Text.Ginger.AST.Macro a)
instance Text.Ginger.Optimizer.Optimizable (Text.Ginger.AST.Expression a)
instance GHC.Base.Monoid Text.Ginger.Optimizer.Purity
instance Text.Ginger.GVal.ToGVal m Text.Ginger.Optimizer.Collected


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