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


-- | 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 GHC.Base.Semigroup 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
gappend :: GVal m -> GVal m -> GVal m

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

-- | 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
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
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>Integer</a> The conversion will fail
--   when the value is not an integer
toInteger :: GVal m -> Maybe Integer

-- | 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
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 Text.Ginger.GVal.FromGVal m GHC.Types.Int
instance Text.Ginger.GVal.FromGVal m Data.Scientific.Scientific
instance Text.Ginger.GVal.FromGVal m GHC.Integer.Type.Integer
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.Internal.TimeOfDay.TimeOfDay
instance Text.Ginger.GVal.FromGVal m Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Text.Ginger.GVal.FromGVal m Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Text.Ginger.GVal.FromGVal m Data.Time.LocalTime.Internal.TimeZone.TimeZone
instance Text.Ginger.GVal.FromGVal m Data.Time.Format.Locale.TimeLocale
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.Internal.TimeOfDay.TimeOfDay
instance Text.Ginger.GVal.ToGVal m Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Text.Ginger.GVal.ToGVal m Data.Time.LocalTime.Internal.TimeZone.TimeZone
instance Text.Ginger.GVal.ToGVal m Data.Time.Format.Locale.TimeLocale
instance Text.Ginger.GVal.ToGVal m Data.Time.LocalTime.Internal.ZonedTime.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 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 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 Data.String.IsString (Text.Ginger.GVal.GVal m)


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

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

module Text.Ginger.PHP
type LText = Text

-- | Concrete PHP syntax (or rather, the subset we use)
data PHP

-- | whatever
RawSyntax :: Text -> PHP

-- | <pre>
--   foobar
--   </pre>
Bareword :: Text -> PHP

-- | <pre>
--   $foobar
--   </pre>
Variable :: Text -> PHP

-- | <pre>
--   <tt>foobar</tt>
--   </pre>
SQString :: Text -> PHP

-- | <pre>
--   23
--   </pre>
Int :: Int -> PHP

-- | <pre>
--   23.42
--   </pre>
Float :: Double -> PHP

-- | <pre>
--   +
--   </pre>
Operator :: Text -> PHP
Parenthesized :: PHP -> PHP
StmtBlock :: [PHP] -> PHP
List :: [PHP] -> PHP
Dict :: [(PHP, PHP)] -> PHP
Assign :: PHP -> PHP -> PHP
Binop :: PHP -> PHP -> PHP -> PHP
Call :: PHP -> [PHP] -> PHP
Lookup :: PHP -> PHP -> PHP
Lambda :: [Text] -> [PHP] -> PHP
Ternary :: PHP -> PHP -> PHP -> PHP
Statement :: PHP -> PHP
Return :: PHP -> PHP
writeBuilder :: PHP -> Builder
writeText :: PHP -> LText
escapeSQ :: Text -> Text
escapeCharSQ :: Char -> Text
exprToPHP :: Expression a -> PHP


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

-- | Parse Ginger source from memory. The initial template is taken
--   directly from the provided <a>Source</a>, while all subsequent
--   includes are loaded through the provided <a>IncludeResolver</a>.
parseGinger :: forall m. Monad m => IncludeResolver m -> Maybe SourceName -> Source -> m (Either ParserError (Template SourcePos))

-- | Parse Ginger source from a file. Both the initial template and all
--   subsequent includes are loaded through the provided
--   <a>IncludeResolver</a>. A consequence of this is that if you pass a
--   "null resolver" (like `const (return Nothing)`), this function will
--   always fail.
parseGingerFile :: forall m. Monad m => IncludeResolver m -> SourceName -> m (Either ParserError (Template SourcePos))

-- | Parse Ginger source from memory. Flavor of <a>parseGinger</a> that
--   takes additional <a>ParserOptions</a>.
parseGinger' :: Monad m => ParserOptions m -> Source -> m (Either ParserError (Template SourcePos))

-- | Parse Ginger source from a file. Flavor of <a>parseGingerFile</a> that
--   takes additional <a>ParserOptions</a>.
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 -> Delimiters -> ParserOptions m

-- | How to load templates / includes
[poIncludeResolver] :: ParserOptions m -> IncludeResolver m

-- | Current source file name, if any
[poSourceName] :: ParserOptions m -> Maybe SourceName

-- | Disable newline stripping
[poKeepTrailingNewline] :: ParserOptions m -> Bool

-- | Enable auto-stripping of <tt>{% block %}</tt>s
[poLStripBlocks] :: ParserOptions m -> Bool

-- | Enable auto-trimming of <tt>{% block %}</tt>s
[poTrimBlocks] :: ParserOptions m -> Bool

-- | Interpolation, tag, and comment delimiters
[poDelimiters] :: ParserOptions m -> Delimiters

-- | Default parser options for a given resolver
mkParserOptions :: Monad m => IncludeResolver m -> ParserOptions m

-- | Delimiter configuration.
data Delimiters
Delimiters :: String -> String -> String -> String -> String -> String -> Delimiters
[delimOpenInterpolation] :: Delimiters -> String
[delimCloseInterpolation] :: Delimiters -> String
[delimOpenTag] :: Delimiters -> String
[delimCloseTag] :: Delimiters -> String
[delimOpenComment] :: Delimiters -> String
[delimCloseComment] :: Delimiters -> String

-- | Default delimiter configuration: <tt>{{ }}</tt> for interpolation,
--   <tt>{% %}</tt> for tags, <tt>{}</tt> for comments.
defDelimiters :: Delimiters

-- | Formats a parser errror into something human-friendly. If template
--   source code is not provided, only the line and column numbers and the
--   error message are printed. If template source code is provided, the
--   offending source line is also printed, with a caret (<tt>^</tt>)
--   marking the exact location of the error.
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 GHC.Exception.Exception Text.Ginger.Parse.ParserError
instance Text.Ginger.GVal.ToGVal m Text.Parsec.Pos.SourcePos

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

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)
binaryFunc :: forall m h p. (Monad m) => (GVal (Run p m h) -> 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.Base.Semigroup 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.GVal.ToGVal m Text.Ginger.Optimizer.Collected
instance GHC.Base.Semigroup Text.Ginger.Optimizer.Purity
instance GHC.Base.Monoid 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)


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