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


-- | An implementation of the Jinja2 template language in Haskell
--   
--   An implementation of the Jinja2 template language in Haskell
@package ginger
@version 0.1.1.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 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


-- | 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 ( {% macro %}
data Macro
Macro :: [VarName] -> Statement -> Macro
[macroArgs] :: Macro -> [VarName]
[macroBody] :: Macro -> Statement

-- | A block definition ( {% block %}
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
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


-- | 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>.
module Text.Ginger.GVal

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

-- | Ginger value.
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 -> GVal m
[asList] :: GVal m -> Maybe [GVal m]
[asDictItems] :: GVal m -> Maybe [(Text, GVal m)]
[asLookup] :: GVal m -> Maybe (Text -> Maybe (GVal m))
[asHtml] :: GVal m -> Html
[asText] :: GVal m -> Text
[asBoolean] :: GVal m -> Bool
[asNumber] :: GVal m -> Maybe Scientific
[asFunction] :: GVal m -> Maybe (Function m)
[length] :: GVal m -> Maybe Int
[isNull] :: GVal m -> Bool
isList :: GVal m -> Bool
isDict :: GVal m -> Bool

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

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

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

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

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

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

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

-- | 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>.
instance Data.Default.Class.Default (Text.Ginger.GVal.GVal m)
instance Text.Ginger.GVal.ToGVal m (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.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 GHC.Types.Bool
instance Data.String.IsString (Text.Ginger.GVal.GVal m)
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


-- | Execute Ginger templates in an arbitrary monad.
module Text.Ginger.Run

-- | Monadically run a Ginger template. The <tt>m</tt> parameter is the
--   carrier monad, the <tt>v</tt> parameter is the type for Ginger values.
runGingerT :: (Monad m, Functor m) => GingerContext m -> Template -> m ()

-- | Purely expand a Ginger template. <tt>v</tt> is the type for Ginger
--   values.
runGinger :: GingerContext (Writer Html) -> Template -> Html

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

-- | Create an execution context for runGinger. The argument is a lookup
--   function that maps top-level context keys to ginger values.
makeContext :: (VarName -> GVal (Run (Writer Html))) -> GingerContext (Writer Html)

-- | 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 (GVal (Run m))) -> (Html -> m ()) -> GingerContext m

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

-- | Lift a value from the host monad <tt>m</tt> into the <a>Run</a> monad.
liftRun :: Monad m => m a -> Run m 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 b


-- | 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.Show.Show Text.Ginger.Parse.ParserError


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