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


-- | Typed templates with jinja like syntax
--   
--   Typed templates with jinja like syntax. Well-typed templates don't go
--   wrong.
@package zinza
@version 0.2


-- | Zinza - a small jinja-syntax-inspired typed-template compiler.
--   
--   Zinza typechecks and compiles a template. We can compile either to
--   Haskell function, or to verbatim Haskell module (planned).
--   
--   Zinza is very minimalistic. Features are added when needed.
--   
--   <h2>Example usage</h2>
--   
--   Given a template
--   
--   <pre>
--   {% for license in licenses %}
--   licenseName {{license.con}} = {{license.name}}
--   {% endfor %}
--   </pre>
--   
--   and data definitions like:
--   
--   <pre>
--   newtype Licenses = Licenses { licenses :: [License] }
--     deriving (<a>Generic</a>)
--   
--   data License = License
--       { licenseCon  :: String
--       , licenseName :: String
--       }
--     deriving (<a>Generic</a>)
--   </pre>
--   
--   We can (generically) derive <a>Zinza</a> instances for
--   <tt>Licenses</tt> and <tt>License</tt>
--   
--   <pre>
--   instance <a>Zinza</a> Licenses where
--       <a>toType</a>    = <a>genericToType</a>    id
--       <a>toValue</a>   = <a>genericToValue</a>   id
--       <a>fromValue</a> = <a>genericFromValue</a> id
--   
--   instance <a>Zinza</a> License where
--       <a>toType</a>    = <a>genericToTypeSFP</a>
--       <a>toValue</a>   = <a>genericToValueSFP</a>
--       <a>fromValue</a> = <a>genericFromValueSFP</a>
--   </pre>
--   
--   Then the example of run-time usage is
--   
--   <pre>
--   example :: IO String
--   example = do
--       -- this might fail, type errors!
--       run &lt;- <a>parseAndCompileTemplateIO</a> "fixtures/licenses.zinza"
--       -- this shouldn't fail (run-time errors are due bugs in zinza)
--       run $ Licenses
--           [ License "Foo" (show "foo-1.0")
--           , License "Bar" (show "bar-1.2")
--           ]
--   </pre>
--   
--   The result of running an <tt>example</tt> is:
--   
--   <pre>
--   licenseName Foo = "foo-1.0"
--   licenseName Bar = "bar-1.2"
--   </pre>
--   
--   <h2>Module generation</h2>
--   
--   Zinza also supports standalone module generation.
--   
--   <pre>
--   <a>parseAndCompileModuleIO</a> (<a>simpleConfig</a> "DemoLicenses" ["Licenses"] :: <a>ModuleConfig</a> Licenses) "fixtures/licenses.zinza" &gt;&gt;= putStr
--   </pre>
--   
--   prints a Haskell module source code:
--   
--   <pre>
--   {--}
--   module DemoLicenses (render) where
--   import Prelude (String, fst, snd, ($), not, return)
--   import Control.Monad (forM_)
--   import Licenses
--   type Writer a = (String, a)
--   tell :: String -&gt; Writer (); tell x = (x, ())
--   execWriter :: Writer a -&gt; String; execWriter = fst
--   render :: Licenses -&gt; String
--   render (z_root) = execWriter $ do
--     forM_ (licenses $ z_root) $ z_var0_license -&gt; do
--       tell "licenseName "
--       tell (licenseCon $ z_var0_license)
--       tell " = "
--       tell (licenseName $ z_var0_license)
--       tell "n"
--   </pre>
--   
--   which is not dependent on Zinza. You are free to use more efficient
--   writer as well.
--   
--   <h3>Expressions</h3>
--   
--   <pre>
--   {{ expression }}
--   </pre>
--   
--   Expression syntax has only few constructions:
--   
--   <ul>
--   <li>field access <tt>foo.bar</tt></li>
--   <li>function application <tt>fun bar</tt> (though function can only be
--   <tt>not</tt>)</li>
--   </ul>
--   
--   <i>Note:</i> you can provide your own <i>Prelude</i> of functions. See
--   <tt>Bools.hs</tt> and <tt>Bools.zinza</tt> in tests for an example.
--   You cannot define new functions in templates, but you can pass them as
--   template arguments.
--   
--   <h3>Control structures</h3>
--   
--   The <b>for</b> and <b>if</b> statements are supported:
--   
--   <pre>
--   {% for value in values %}
--   ...
--   {% endfor %}
--   </pre>
--   
--   <pre>
--   {% if boolExpression %}
--   ...
--   {% elif anotherBoolExpression %}
--   ...
--   {% else %}
--   ...
--   {% endif %}
--   </pre>
--   
--   If a control structure tag starts at the first column, the possible
--   trailing new line feed is stripped. This way full-line control tags
--   don't introduce new lines in the output.
--   
--   <h3>Blocks</h3>
--   
--   It's possible to define blocks to be used (possibly multiple times)
--   later:
--   
--   <pre>
--   {% defblock blockname %}
--   ...
--   {% endblock %}
--   </pre>
--   
--   And the block can be used later with:
--   
--   <pre>
--   {% useblock blockname %}
--   </pre>
--   
--   Blocks follow scopes of <tt>if</tt> and <tt>for</tt> control
--   structures
--   
--   <h3>Comments</h3>
--   
--   <pre>
--   {# Comments are omitted from the output #}
--   </pre>
module Zinza

-- | Parse and compile the template into Haskell function.
parseAndCompileTemplate :: (Zinza a, ThrowRuntime m) => FilePath -> String -> Either CompileOrParseError (a -> m String)

-- | Like <a>parseAndCompileTemplate</a> but reads file and (possibly)
--   throws <a>CompileOrParseError</a>.
parseAndCompileTemplateIO :: (Zinza a, ThrowRuntime m) => FilePath -> IO (a -> m String)

-- | Parse and compile the template into <a>String</a> representing a
--   Haskell module.
parseAndCompileModule :: Zinza a => ModuleConfig a -> FilePath -> String -> Either CompileOrParseError String

-- | Like <a>parseAndCompileModule</a> but reads file and (possibly) throws
--   <a>CompileOrParseError</a>.
parseAndCompileModuleIO :: Zinza a => ModuleConfig a -> FilePath -> IO String

-- | Configuration for module rendering
data ModuleConfig a
ModuleConfig :: [String] -> String -> ModuleConfig a

-- | module header
[mcHeader] :: ModuleConfig a -> [String]

-- | name of the function
[mcRender] :: ModuleConfig a -> String

-- | Simple configuration to use with <a>parseAndCompileModule</a> or
--   <a>parseAndCompileModuleIO</a>.
simpleConfig :: forall a. Typeable a => String -> [String] -> ModuleConfig a

-- | <a>Zinza</a> class tells how to convert the type into template
--   parameters, and their types.
--   
--   Class can be auto-derived for product types.
--   
--   <pre>
--   &gt;&gt;&gt; data R = R { recFoo :: String, recBar :: Char } deriving Generic
--   
--   &gt;&gt;&gt; instance Zinza R where toType = genericToTypeSFP; toValue = genericToValueSFP; fromValue = genericFromValueSFP
--   
--   &gt;&gt;&gt; displayTy $ toType (Proxy :: Proxy R)
--   "{bar: String, foo: String}"
--   </pre>
class Zinza a
toType :: Zinza a => Proxy a -> Ty
toTypeList :: Zinza a => Proxy a -> Ty
toValue :: Zinza a => a -> Value
toValueList :: Zinza a => [a] -> Value
fromValue :: Zinza a => Loc -> Value -> Either RuntimeError a
fromValueList :: Zinza a => Loc -> Value -> Either RuntimeError [a]

-- | Generically derive <a>toType</a> function.
genericToType :: forall a. (Generic a, GZinzaType (Rep a)) => (String -> String) -> Proxy a -> Ty

-- | Generically derive <a>toValue</a> function.
genericToValue :: forall a. (Generic a, GZinzaValue (Rep a)) => (String -> String) -> a -> Value
genericFromValue :: forall a. (Generic a, GZinzaFrom (Rep a)) => (String -> String) -> Loc -> Value -> Either RuntimeError a

-- | <a>genericToType</a> with <a>stripFieldPrefix</a>.
genericToTypeSFP :: forall a. (Generic a, GZinzaType (Rep a), GFieldNames (Rep a)) => Proxy a -> Ty

-- | <a>genericToValue</a> with <a>stripFieldPrefix</a>.
genericToValueSFP :: forall a. (Generic a, GZinzaValue (Rep a), GFieldNames (Rep a)) => a -> Value

-- | <a>genericFromValue</a> with <a>stripFieldPrefix</a>.
genericFromValueSFP :: forall a. (Generic a, GZinzaFrom (Rep a), GFieldNames (Rep a)) => Loc -> Value -> Either RuntimeError a

-- | Field renamer which will automatically strip lowercase prefix from
--   field names.
--   
--   <pre>
--   &gt;&gt;&gt; data R = R { recFoo :: Int, recBar :: Char } deriving Generic
--   
--   &gt;&gt;&gt; stripFieldPrefix (Proxy :: Proxy R) "recFoo"
--   "foo"
--   </pre>
--   
--   If whole field is lower case, it's left intact
--   
--   <pre>
--   &gt;&gt;&gt; newtype Wrapped = Wrap { unwrap :: String } deriving Generic
--   
--   &gt;&gt;&gt; stripFieldPrefix (Proxy :: Proxy Wrapped) "unwrap"
--   "unwrap"
--   </pre>
stripFieldPrefix :: forall a. (Generic a, GFieldNames (Rep a)) => Proxy a -> String -> String
class GZinzaType (f :: Type -> Type)
class GZinzaValue (f :: Type -> Type)
class GZinzaFrom (f :: Type -> Type)
class GFieldNames (f :: Type -> Type)

-- | Template parts.
--   
--   We use polymorphic recursion for de Bruijn indices. See materials on
--   <tt>bound</tt> library.
data Node a

-- | raw text block
NRaw :: String -> Node a

-- | expression <tt>expr : String</tt>
NExpr :: LExpr a -> Node a

-- | conditional block, <tt>expr : Bool</tt>
NIf :: LExpr a -> Nodes a -> Nodes a -> Node a

-- | for loop, <tt>expr : List a</tt>
NFor :: Var -> LExpr a -> Nodes (Maybe a) -> Node a

-- | define block
NDefBlock :: Loc -> Var -> Nodes a -> Node a

-- | use block
NUseBlock :: Loc -> Var -> Node a

-- | comments
NComment :: Node a

-- | A list of <a>Node</a>s.
type Nodes a = [Node a]

-- | Expressions in templates.
--   
--   Note: there are only eliminators; we cannot construct "bigger"
--   expressions.
data Expr a

-- | variable
EVar :: Located a -> Expr a

-- | field accessor
EField :: LExpr a -> Located Var -> Expr a

-- | function application
EApp :: LExpr a -> LExpr a -> Expr a

-- | Located expression.
type LExpr a = Located (Expr a)

-- | Zinza types.
--   
--   The <tt>selector</tt>s tell how the Haskell value can be converted to
--   primitive value. E.g.
--   
--   <pre>
--   &gt;&gt;&gt; toType (Proxy :: Proxy Char)
--   TyString (Just "return")
--   </pre>
--   
--   Here, <a>return</a> converts <a>Char</a> to <a>String</a>.
data Ty

-- | boolean
TyBool :: Ty

-- | string
TyString :: Maybe Selector -> Ty

-- | lists
TyList :: Maybe Selector -> Ty -> Ty

-- | records
TyRecord :: Map Var (Selector, Ty) -> Ty

-- | functions
TyFun :: Ty -> Ty -> Ty

-- | Pretty print <a>Ty</a>.
displayTy :: Ty -> String

-- | Template values.
data Value

-- | booleans
VBool :: Bool -> Value

-- | strings
VString :: String -> Value

-- | lists
VList :: [Value] -> Value

-- | records
VRecord :: Map Var Value -> Value

-- | function
VFun :: (Value -> Either RuntimeError Value) -> Value
newtype ParseError
ParseError :: String -> ParseError
data CompileError
UnboundTopLevelVar :: Loc -> Var -> CompileError
ShadowingBlock :: Loc -> Var -> CompileError
UnboundUseBlock :: Loc -> Var -> CompileError
ARuntimeError :: RuntimeError -> CompileError
data CompileOrParseError
ACompileError :: CompileError -> CompileOrParseError
AParseError :: ParseError -> CompileOrParseError
data RuntimeError
NotBool :: Loc -> Ty -> RuntimeError
NotString :: Loc -> Ty -> RuntimeError
NotRecord :: Loc -> Ty -> RuntimeError
NotList :: Loc -> Ty -> RuntimeError
FieldNotInRecord :: Loc -> Var -> Ty -> RuntimeError
NotFunction :: Loc -> Ty -> RuntimeError
FunArgDontMatch :: Loc -> Ty -> Ty -> RuntimeError
CustomError :: Loc -> String -> Ty -> RuntimeError

-- | Class representing errors containing <a>RuntimeError</a>s.
--   
--   Without bugs, compiled template should not throw any
--   <a>RuntimeError</a>s, as they are prevented statically, i.e. reported
--   already as <a>CompileError</a>s.
class AsRuntimeError e
asRuntimeError :: AsRuntimeError e => RuntimeError -> e
class Monad m => ThrowRuntime m
throwRuntime :: ThrowRuntime m => RuntimeError -> m a

-- | Location, line and column.
data Loc
Loc :: !Int -> !Int -> Loc

-- | Located element.
data Located a
L :: {-# UNPACK #-} !Loc -> a -> Located a

-- | <i>Unknown</i> location.
zeroLoc :: Loc

-- | Pretty-print location.
displayLoc :: Loc -> String

-- | Some containers have location for each element.
class Traversable t => TraversableWithLoc t
traverseWithLoc :: (TraversableWithLoc t, Applicative f) => (Loc -> a -> f b) -> t a -> f (t b)

-- | Variable name, possibly a fieldname in the record.
type Var = String

-- | Haskell selector.
type Selector = String