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


-- | Templating language with similar syntax and features to Liquid or Jinja2.
--   
--   ED-E is a templating language written in Haskell with a specific set
--   of features:
--   
--   <ul>
--   <li>Logicless within reason. A small set of consistent predicates and
--   expressions for formatting and presentational logic are provided.</li>
--   <li>Secure. No arbitrary code evaluation, with input data required to
--   be fully specified at render time.</li>
--   <li>Stateless. Parsing and rendering are separate steps so that
--   loading, parsing, include resolution, and embedding of the compiled
--   template can optionally be done ahead of time, amortising cost.</li>
--   <li>Markup agnostic. ED-E is used to write out everything from
--   configuration files for system services, to HTML and formatted
--   emails.</li>
--   <li>Control over purity. Users can choose pure or IO-based resolution
--   of <tt>include</tt> expressions.</li>
--   <li>No surprises. All parsing, type assurances, and rendering steps
--   report helpful error messages with line/column metadata. Variable
--   shadowing, unprintable expressions, implicit type coercion, and
--   unbound variable access are all treated as errors.</li>
--   </ul>
@package ede
@version 0.2.8.7


-- | The means to construct your own filters.
module Text.EDE.Filters

-- | A HOAS representation of (possibly partially applied) values in the
--   environment.
data Term
TVal :: !Value -> Term
TLam :: (Term -> Result Term) -> Term
class Quote a where quote _ _ = TVal . toJSON
quote :: Quote a => Id -> Int -> a -> Term
quote :: (Quote a, ToJSON a) => Id -> Int -> a -> Term
class Unquote a where unquote k n = \case { f@(TLam {}) -> typeErr k n (pretty f) "Value" TVal v -> case fromJSON v of { Success x -> pure x Error e -> argumentErr k n e } }
unquote :: Unquote a => Id -> Int -> Term -> Result a
unquote :: (Unquote a, FromJSON a) => Id -> Int -> Term -> Result a
(@:) :: Quote a => Id -> a -> (Id, Term)

-- | Fully apply two <a>Term</a>s.
qapply :: Delta -> Term -> Term -> Result Term

-- | Quote a binary function which takes the most general binding value.
qpoly2 :: Quote a => Id -> (Value -> Value -> a) -> (Id, Term)

-- | Quote an unary numeric function.
qnum1 :: Id -> (Scientific -> Scientific) -> (Id, Term)

-- | Quote a binary numeric function.
qnum2 :: Quote a => Id -> (Scientific -> Scientific -> a) -> (Id, Term)

-- | Quote a comprehensive set of unary functions to create a binding that
--   supports all collection types.
qcol1 :: (Quote a, Quote b, Quote c) => Id -> (Text -> a) -> (Object -> b) -> (Array -> c) -> (Id, Term)
typeErr :: Id -> Int -> Doc -> Doc -> Result a
argumentErr :: Pretty a => Id -> Int -> a -> Result b


-- | A (mostly logicless) textual templating language with similar syntax
--   to <a>Liquid</a> or <a>Jinja2</a>.
--   
--   (ED-E is a character from Fallout New Vegas, pronounced
--   <tt>Eddie</tt>.)
module Text.EDE

-- | A parsed and compiled template.
data Template

-- | Parse Lazy <a>Text</a> into a compiled <a>Template</a>.
--   
--   Because this function is pure and does not resolve <tt>include</tt>s,
--   encountering an <tt>include</tt> expression during parsing will result
--   in an <tt>Error</tt>.
--   
--   See <a>parseFile</a> or <a>parseWith</a> for mechanisms to deal with
--   <tt>include</tt> dependencies.
parse :: ByteString -> Result Template

-- | Parse <a>Text</a> into a compiled <a>Template</a>.
--   
--   This function handles all <tt>include</tt> expressions as
--   <a>FilePath</a>s and performs recursive loading/parsing.
parseIO :: FilePath -> ByteString -> IO (Result Template)

-- | Load and parse a <a>Template</a> from a file.
--   
--   This function handles all <tt>include</tt> expressions as
--   <a>FilePath</a>s and performs recursive loading/parsing, with pathing
--   of <tt>include</tt>s relatively to the target (unless absolute paths
--   are used).
parseFile :: FilePath -> IO (Result Template)

-- | <i>See:</i> <a>parseFile</a>.
parseFileWith :: Syntax -> FilePath -> IO (Result Template)

-- | Parse a <a>Template</a> from a Strict <a>ByteString</a> using a custom
--   function for resolving <tt>include</tt> expressions.
--   
--   Two custom <tt>include</tt> resolvers are supplied:
--   
--   <ul>
--   <li><a>includeMap</a></li>
--   <li><a>includeFile</a></li>
--   </ul>
--   
--   <a>parseFile</a> for example, is defined as: <a>parseWith</a>
--   <a>includeFile</a>.
parseWith :: Monad m => Syntax -> Resolver m -> Text -> ByteString -> m (Result Template)

-- | A function to resolve the target of an <tt>include</tt> expression.
type Resolver m = Syntax -> Id -> Delta -> m (Result Template)
type Id = Text

-- | <a>HashMap</a> resolver for <tt>include</tt> expressions.
--   
--   The <tt>identifier</tt> component of the <tt>include</tt> expression
--   is treated as a lookup key into the supplied <a>HashMap</a>. If the
--   <tt>identifier</tt> doesn't exist in the <a>HashMap</a>, an
--   <tt>Error</tt> is returned.
includeMap :: Monad m => HashMap Id Template -> Resolver m

-- | <a>FilePath</a> resolver for <tt>include</tt> expressions.
--   
--   The <tt>identifier</tt> component of the <tt>include</tt> expression
--   is treated as a relative <a>FilePath</a> and the template is loaded
--   and parsed using <a>parseFile</a>. If the <tt>identifier</tt> doesn't
--   exist as a valid <a>FilePath</a>, an <tt>Error</tt> is returned.
includeFile :: FilePath -> Resolver IO

-- | Render an <a>Object</a> using the supplied <a>Template</a>.
render :: Template -> Object -> Result Text

-- | Render an <a>Object</a> using the supplied <a>Template</a>.
renderWith :: HashMap Id Term -> Template -> Object -> Result Text

-- | <i>See:</i> <a>parse</a>
eitherParse :: ByteString -> Either String Template

-- | <i>See:</i> <a>parseFile</a>
eitherParseFile :: FilePath -> IO (Either String Template)

-- | <i>See:</i> <a>parseWith</a>
eitherParseWith :: (Functor m, Monad m) => Syntax -> Resolver m -> Text -> ByteString -> m (Either String Template)

-- | <i>See:</i> <a>render</a>
eitherRender :: Template -> Object -> Either String Text

-- | <i>See:</i> <a>renderWith</a>
eitherRenderWith :: HashMap Id Term -> Template -> Object -> Either String Text
data Delta :: *
Columns :: {-# UNPACK #-} ~Int64 -> {-# UNPACK #-} ~Int64 -> Delta
Tab :: {-# UNPACK #-} ~Int64 -> {-# UNPACK #-} ~Int64 -> {-# UNPACK #-} ~Int64 -> Delta
Lines :: {-# UNPACK #-} ~Int64 -> {-# UNPACK #-} ~Int64 -> {-# UNPACK #-} ~Int64 -> {-# UNPACK #-} ~Int64 -> Delta
Directed :: ~ByteString -> {-# UNPACK #-} ~Int64 -> {-# UNPACK #-} ~Int64 -> {-# UNPACK #-} ~Int64 -> {-# UNPACK #-} ~Int64 -> Delta

-- | The result of running parsing or rendering steps.
data Result a
Success :: a -> Result a
Failure :: Doc -> Result a

-- | Convert a <a>Result</a> to an <a>Either</a> with the <a>Left</a> case
--   holding a formatted error message, and <a>Right</a> being the
--   successful result over which <a>Result</a> is paramterised.
eitherResult :: Result a -> Either String a

-- | Perform a case analysis on a <a>Result</a>.
result :: (Doc -> b) -> (a -> b) -> Result a -> b

-- | Convenience for returning a successful <a>Result</a>.
success :: Monad m => a -> m (Result a)

-- | Convenience for returning an error <a>Result</a>.
failure :: Monad m => Doc -> m (Result a)

-- | Unwrap a <a>Value</a> to an <a>Object</a> safely.
--   
--   See <tt>Aeson'</tt>s documentation for more details.
fromValue :: Value -> Maybe Object

-- | Create an <a>Object</a> from a list of name/value <a>Pair</a>s.
--   
--   See <tt>Aeson'</tt>s documentation for more details.
fromPairs :: [Pair] -> Object
(.=) :: KeyValue kv => forall v. ToJSON v => Text -> v -> kv

-- | ED-E Version.
version :: Version
type Delim = (String, String)
data Syntax
delimPragma :: HasSyntax c_avj6 => Lens' c_avj6 Delim
delimInline :: HasSyntax c_avj6 => Lens' c_avj6 Delim
delimComment :: HasSyntax c_avj6 => Lens' c_avj6 Delim
delimBlock :: HasSyntax c_avj6 => Lens' c_avj6 Delim

-- | The default ED-E syntax.
--   
--   Delimiters:
--   
--   <ul>
--   <li>Pragma: <tt>{! ... !}</tt></li>
--   <li>Inline: <tt>{{ ... }}</tt></li>
--   <li>Comments: <tt>{}</tt></li>
--   <li>Blocks: <tt>{% ... %}</tt></li>
--   </ul>
defaultSyntax :: Syntax

-- | An alternate syntax (based on Play/Scala templates) designed to be
--   used when the default is potentially ambiguous due to another
--   encountered smarty based syntax.
--   
--   Delimiters:
--   
--   <ul>
--   <li>Inline: <tt>&lt;@ ... @&gt;</tt></li>
--   <li>Comments: <tt>@* ... *@</tt></li>
--   <li>Blocks: <tt>@( ... )@</tt></li>
--   </ul>
alternateSyntax :: Syntax
