Zinza

SPDX-Identifier-Id: GPL-2.0-or-later AND BSD-3-Clause

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.

Example usage

Given a template

{% for license in licenses %}
licenseName {{license.con}} = {{license.name}}
{% endfor %}

and data definitions like:

newtype Licenses = Licenses { licenses :: [License] }
  deriving (Generic)

data License = License
    { licenseCon  :: String
    , licenseName :: String
    }
  deriving (Generic)

We can (generically) derive Zinza instances for Licenses and License

instance Zinza Licenses where
    toType  = genericToType  id
    toValue = genericToValue id

instance Zinza License where
    toType  = genericToTypeSFP
    toValue = genericToValueSFP

Then the example of run-time usage is

example :: IO String
example = do
    -- this might fail, type errors!
    run <- parseAndCompileTemplateIO "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")
        ]

The result of running an example is:

licenseName Foo = "foo-1.0"
licenseName Bar = "bar-1.2"

Module generation

Zinza also supports standalone module generation.

parseAndCompileModuleIO (simpleConfig "DemoLicenses" ["Licenses"] :: ModuleConfig Licenses) "fixtures/licenses.zinza" >>= putStr

prints a Haskell module source code:

module DemoLicenses (render) where
import Prelude (String, fst, snd, ($))
import Control.Monad (forM_)
import Licenses
type Writer a = (String, a)
tell :: String -> Writer (); tell x = (x, ())
execWriter :: Writer a -> String; execWriter = fst
render :: Licenses -> String
render (z_root) = execWriter $ do
  forM_ (licenses $ z_root) $ z_var0_license -> do
    tell "licenseName "
    tell (licenseCon $ z_var0_license)
    tell " = "
    tell (licenseName $ z_var0_license)
    tell "n"

which is not dependent on Zinza. You are free to use more efficient writer as well.

Expressions

{{ expression }}

Expression syntax has only two structures

• negated: !foo
• field access foo.bar

Control structures

The for and if statements are supported:

{% for value in values %}
...
{% endfor %}

{% if boolExpression %}
...
{% elif anotherBoolExpression %}
...
{% else %}
...
{% endif %}

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.

Comments

{# Comments are omitted from the output #}

Documentation

parseAndCompileTemplate

Arguments

:: (Zinza a, ThrowRuntime m)

=> FilePath

name of the template

-> String

contents of the template

-> Either CompileOrParseError (a -> m String)

Parse and compile the template into Haskell function.

parseAndCompileTemplateIO :: (Zinza a, ThrowRuntime m) => FilePath -> IO (a -> m String)

Like parseAndCompileTemplate but reads file and (possibly) throws CompileOrParseError.

Compilation to Haskell module

parseAndCompileModule :: Zinza a => ModuleConfig a -> FilePath -> String -> Either CompileOrParseError String

Parse and compile the template into String representing a Haskell module.

parseAndCompileModuleIO :: Zinza a => ModuleConfig a -> FilePath -> IO String

Like parseAndCompileModule but reads file and (possibly) throws CompileOrParseError.

data ModuleConfig a

Configuration for module rendering

Constructors

ModuleConfig

Fields

• mcHeader :: [String]

  module header

• mcRender :: String

  name of the function

Instances

Show (ModuleConfig a)

Defined in Zinza.Module

Methods

showsPrec :: Int -> ModuleConfig a -> ShowS

show :: ModuleConfig a -> String

showList :: [ModuleConfig a] -> ShowS

simpleConfig

Arguments

:: Typeable a

=> String

module name

-> [String]

imports

-> ModuleConfig a

Simple configuration to use with parseAndCompileModule or parseAndCompileModuleIO.

Input class

class Zinza a where

Zinza class tells how to convert the type into template parameters, and their types.

Class can be auto-derived for product types.

>>> data R = R { recFoo :: String, recBar :: Char } deriving Generic
>>> instance Zinza R where toType = genericToTypeSFP; toValue = genericToValueSFP
>>> displayTy $ toType (Proxy :: Proxy R)
"{bar: String, foo: String}"

Minimal complete definition

toType, toValue

Methods

toType :: Proxy a -> Ty

toTypeList :: Proxy a -> Ty

toValue :: a -> Value

toValueList :: [a] -> Value

Instances

Zinza Bool

Defined in Zinza.Class

Methods

toType :: Proxy Bool -> Ty

toTypeList :: Proxy Bool -> Ty

toValue :: Bool -> Value

toValueList :: [Bool] -> Value

Zinza Char

Defined in Zinza.Class

Methods

toType :: Proxy Char -> Ty

toTypeList :: Proxy Char -> Ty

toValue :: Char -> Value

toValueList :: [Char] -> Value

Zinza ()

Defined in Zinza.Class

Methods

toType :: Proxy () -> Ty

toTypeList :: Proxy () -> Ty

toValue :: () -> Value

toValueList :: [()] -> Value

Zinza Text

Defined in Zinza.Class

Methods

toType :: Proxy Text -> Ty

toTypeList :: Proxy Text -> Ty

toValue :: Text -> Value

toValueList :: [Text] -> Value

Zinza Text

Defined in Zinza.Class

Methods

toType :: Proxy Text -> Ty

toTypeList :: Proxy Text -> Ty

toValue :: Text -> Value

toValueList :: [Text] -> Value

Zinza a => Zinza [a]

Defined in Zinza.Class

Methods

toType :: Proxy [a] -> Ty

toTypeList :: Proxy [a] -> Ty

toValue :: [a] -> Value

toValueList :: [[a]] -> Value

Zinza a => Zinza (NonEmpty a)

Defined in Zinza.Class

Methods

toType :: Proxy (NonEmpty a) -> Ty

toTypeList :: Proxy (NonEmpty a) -> Ty

toValue :: NonEmpty a -> Value

toValueList :: [NonEmpty a] -> Value

Zinza a => Zinza (Set a)

Defined in Zinza.Class

Methods

toType :: Proxy (Set a) -> Ty

toTypeList :: Proxy (Set a) -> Ty

toValue :: Set a -> Value

toValueList :: [Set a] -> Value

(Zinza a, Zinza b) => Zinza (a, b)

Defined in Zinza.Class

Methods

toType :: Proxy (a, b) -> Ty

toTypeList :: Proxy (a, b) -> Ty

toValue :: (a, b) -> Value

toValueList :: [(a, b)] -> Value

(Zinza k, Zinza v) => Zinza (Map k v)

Pairs are encoded as {key: k, val: v }

Defined in Zinza.Class

Methods

toType :: Proxy (Map k v) -> Ty

toTypeList :: Proxy (Map k v) -> Ty

toValue :: Map k v -> Value

toValueList :: [Map k v] -> Value

Generic deriving

genericToType

Arguments

:: (Generic a, GZinzaType (Rep a))

=> (String -> String)

field renamer

-> Proxy a

-> Ty

Generically derive toType function.

genericToValue

Arguments

:: (Generic a, GZinzaValue (Rep a))

=> (String -> String)

field renamer

-> a

-> Value

Generically derive toValue function.

genericToTypeSFP :: forall a. (Generic a, GZinzaType (Rep a), GFieldNames (Rep a)) => Proxy a -> Ty

genericToType with stripFieldPrefix.

genericToValueSFP :: forall a. (Generic a, GZinzaValue (Rep a), GFieldNames (Rep a)) => a -> Value

genericToValue with stripFieldPrefix.

stripFieldPrefix :: forall a. (Generic a, GFieldNames (Rep a)) => Proxy a -> String -> String

Field renamer which will automatically strip lowercase prefix from field names.

>>> data R = R { recFoo :: Int, recBar :: Char } deriving Generic
>>> stripFieldPrefix (Proxy :: Proxy R) "recFoo"
"foo"

If whole field is lower case, it's left intact

>>> newtype Wrapped = Wrap { unwrap :: String } deriving Generic
>>> stripFieldPrefix (Proxy :: Proxy Wrapped) "unwrap"
"unwrap"

class GZinzaType (f :: Type -> Type)

Minimal complete definition

gtoType

Instances

(i ~ D, GZinzaTypeSum f) => GZinzaType (M1 i c f)

Defined in Zinza.Generic

Methods

gtoType :: Proxy (M1 i c f) -> [(String, Ty)]

class GZinzaValue (f :: Type -> Type)

Minimal complete definition

gtoValue

Instances

(i ~ D, GZinzaValueSum f) => GZinzaValue (M1 i c f)

Defined in Zinza.Generic

Methods

gtoValue :: M1 i c f () -> [(Var, Value)]

class GFieldNames (f :: Type -> Type)

Minimal complete definition

fieldNames

Instances

(i ~ D, GFieldNamesSum f) => GFieldNames (M1 i c f)

Defined in Zinza.Generic

Methods

fieldNames :: Proxy (M1 i c f) -> [String]

Templates

data Node a

Template parts.

We use polymorphic recursion for de Bruijn indices. See materials on bound library.

Constructors

NRaw String

raw text block

NExpr (LExpr a)

expression expr : String

NIf (LExpr a) (Nodes a) (Nodes a)

conditional block, expr : Bool

NFor Var (LExpr a) (Nodes (Maybe a))

for loop, expr : List a

NComment

comments

Instances

Functor Node

Defined in Zinza.Node

Methods

fmap :: (a -> b) -> Node a -> Node b

(<$) :: a -> Node b -> Node a

Foldable Node

Defined in Zinza.Node

Methods

fold :: Monoid m => Node m -> m

foldMap :: Monoid m => (a -> m) -> Node a -> m

foldr :: (a -> b -> b) -> b -> Node a -> b

foldr' :: (a -> b -> b) -> b -> Node a -> b

foldl :: (b -> a -> b) -> b -> Node a -> b

foldl' :: (b -> a -> b) -> b -> Node a -> b

foldr1 :: (a -> a -> a) -> Node a -> a

foldl1 :: (a -> a -> a) -> Node a -> a

toList :: Node a -> [a]

null :: Node a -> Bool

length :: Node a -> Int

elem :: Eq a => a -> Node a -> Bool

maximum :: Ord a => Node a -> a

minimum :: Ord a => Node a -> a

sum :: Num a => Node a -> a

product :: Num a => Node a -> a

Traversable Node

Defined in Zinza.Node

Methods

traverse :: Applicative f => (a -> f b) -> Node a -> f (Node b)

sequenceA :: Applicative f => Node (f a) -> f (Node a)

mapM :: Monad m => (a -> m b) -> Node a -> m (Node b)

sequence :: Monad m => Node (m a) -> m (Node a)

TraversableWithLoc Node

Defined in Zinza.Node

Methods

traverseWithLoc :: Applicative f => (Loc -> a -> f b) -> Node a -> f (Node b)

Show a => Show (Node a)

Defined in Zinza.Node

Methods

showsPrec :: Int -> Node a -> ShowS

show :: Node a -> String

showList :: [Node a] -> ShowS

type Nodes a = [Node a]

A list of Nodes.

data Expr a

Expressions in templates.

Note: there are only eliminators; we cannot construct "bigger" expressions.

Constructors

EVar (Located a)

variable

EField (LExpr a) (Located Var)

field accessor

ENot (LExpr a)

negation

Instances

Monad Expr

Monad instance gives substitution.

Defined in Zinza.Expr

Methods

(>>=) :: Expr a -> (a -> Expr b) -> Expr b

(>>) :: Expr a -> Expr b -> Expr b

return :: a -> Expr a

fail :: String -> Expr a

Functor Expr

Defined in Zinza.Expr

Methods

fmap :: (a -> b) -> Expr a -> Expr b

(<$) :: a -> Expr b -> Expr a

Applicative Expr

Defined in Zinza.Expr

Methods

pure :: a -> Expr a

(<*>) :: Expr (a -> b) -> Expr a -> Expr b

liftA2 :: (a -> b -> c) -> Expr a -> Expr b -> Expr c

(*>) :: Expr a -> Expr b -> Expr b

(<*) :: Expr a -> Expr b -> Expr a

Foldable Expr

Defined in Zinza.Expr

Methods

fold :: Monoid m => Expr m -> m

foldMap :: Monoid m => (a -> m) -> Expr a -> m

foldr :: (a -> b -> b) -> b -> Expr a -> b

foldr' :: (a -> b -> b) -> b -> Expr a -> b

foldl :: (b -> a -> b) -> b -> Expr a -> b

foldl' :: (b -> a -> b) -> b -> Expr a -> b

foldr1 :: (a -> a -> a) -> Expr a -> a

foldl1 :: (a -> a -> a) -> Expr a -> a

toList :: Expr a -> [a]

null :: Expr a -> Bool

length :: Expr a -> Int

elem :: Eq a => a -> Expr a -> Bool

maximum :: Ord a => Expr a -> a

minimum :: Ord a => Expr a -> a

sum :: Num a => Expr a -> a

product :: Num a => Expr a -> a

Traversable Expr

Defined in Zinza.Expr

Methods

traverse :: Applicative f => (a -> f b) -> Expr a -> f (Expr b)

sequenceA :: Applicative f => Expr (f a) -> f (Expr a)

mapM :: Monad m => (a -> m b) -> Expr a -> m (Expr b)

sequence :: Monad m => Expr (m a) -> m (Expr a)

TraversableWithLoc Expr

Defined in Zinza.Expr

Methods

traverseWithLoc :: Applicative f => (Loc -> a -> f b) -> Expr a -> f (Expr b)

Show a => Show (Expr a)

Defined in Zinza.Expr

Methods

showsPrec :: Int -> Expr a -> ShowS

show :: Expr a -> String

showList :: [Expr a] -> ShowS

type LExpr a = Located (Expr a)

Located expression.

Types

Zinza's type-system is delibarately extremely simple.

data Ty

Zinza types.

The selectors tell how the Haskell value can be converted to primitive value. E.g.

>>> toType (Proxy :: Proxy Char)
TyString (Just "return")

Here, return converts Char to String.

Constructors

TyBool

boolean

TyString (Maybe Selector)

string

TyList (Maybe Selector) Ty

lists

TyRecord (Map Var (Selector, Ty))

records

Instances

Eq Ty

Defined in Zinza.Type

Methods

(==) :: Ty -> Ty -> Bool

(/=) :: Ty -> Ty -> Bool

Ord Ty

Defined in Zinza.Type

Methods

compare :: Ty -> Ty -> Ordering

(<) :: Ty -> Ty -> Bool

(<=) :: Ty -> Ty -> Bool

(>) :: Ty -> Ty -> Bool

(>=) :: Ty -> Ty -> Bool

max :: Ty -> Ty -> Ty

min :: Ty -> Ty -> Ty

Show Ty

Defined in Zinza.Type

Methods

showsPrec :: Int -> Ty -> ShowS

show :: Ty -> String

showList :: [Ty] -> ShowS

displayTy :: Ty -> String

Pretty print Ty.

Values

Values are passed at run-time, when the template is interpreted. When compiled to the Haskell module, Values aren't used.

data Value

Template values.

Constructors

VBool Bool

booleans

VString String

strings

VList [Value]

lists

VRecord (Map Var Value)

records

Instances

Show Value

Defined in Zinza.Value

Methods

showsPrec :: Int -> Value -> ShowS

show :: Value -> String

showList :: [Value] -> ShowS

Errors

newtype ParseError

Constructors

ParseError String

Instances

Show ParseError

Defined in Zinza.Errors

Methods

showsPrec :: Int -> ParseError -> ShowS

show :: ParseError -> String

showList :: [ParseError] -> ShowS

Exception ParseError

Defined in Zinza.Errors

Methods

toException :: ParseError -> SomeException

fromException :: SomeException -> Maybe ParseError

displayException :: ParseError -> String

data CompileError

Constructors

UnboundTopLevelVar Loc Var

ARuntimeError RuntimeError

Instances

Show CompileError

Defined in Zinza.Errors

Methods

showsPrec :: Int -> CompileError -> ShowS

show :: CompileError -> String

showList :: [CompileError] -> ShowS

Exception CompileError

Defined in Zinza.Errors

Methods

toException :: CompileError -> SomeException

fromException :: SomeException -> Maybe CompileError

displayException :: CompileError -> String

AsRuntimeError CompileError

Defined in Zinza.Errors

Methods

asRuntimeError :: RuntimeError -> CompileError

data CompileOrParseError

Constructors

ACompileError CompileError

AParseError ParseError

Instances

Show CompileOrParseError

Defined in Zinza.Errors

Methods

showsPrec :: Int -> CompileOrParseError -> ShowS

show :: CompileOrParseError -> String

showList :: [CompileOrParseError] -> ShowS

Exception CompileOrParseError

Defined in Zinza.Errors

Methods

toException :: CompileOrParseError -> SomeException

fromException :: SomeException -> Maybe CompileOrParseError

displayException :: CompileOrParseError -> String

data RuntimeError

Constructors

NotBool Loc Ty

NotString Loc Ty

NotRecord Loc Ty

NotList Loc Ty

FieldNotInRecord Loc Var Ty

Instances

Show RuntimeError

Defined in Zinza.Errors

Methods

showsPrec :: Int -> RuntimeError -> ShowS

show :: RuntimeError -> String

showList :: [RuntimeError] -> ShowS

Exception RuntimeError

Defined in Zinza.Errors

Methods

toException :: RuntimeError -> SomeException

fromException :: SomeException -> Maybe RuntimeError

displayException :: RuntimeError -> String

AsRuntimeError RuntimeError

Defined in Zinza.Errors

Methods

asRuntimeError :: RuntimeError -> RuntimeError

class AsRuntimeError e where

Class representing errors containing RuntimeErrors.

Without bugs, compiled template should not throw any RuntimeErrors, as they are prevented statically, i.e. reported already as CompileErrors.

Methods

asRuntimeError :: RuntimeError -> e

Instances

AsRuntimeError RuntimeError

Defined in Zinza.Errors

Methods

asRuntimeError :: RuntimeError -> RuntimeError

AsRuntimeError CompileError

Defined in Zinza.Errors

Methods

asRuntimeError :: RuntimeError -> CompileError

class Monad m => ThrowRuntime m where

Methods

throwRuntime :: RuntimeError -> m a

Instances

ThrowRuntime IO

Defined in Zinza.Errors

Methods

throwRuntime :: RuntimeError -> IO a

AsRuntimeError e => ThrowRuntime (Either e)

Defined in Zinza.Errors

Methods

throwRuntime :: RuntimeError -> Either e a

Location

data Loc

Location, line and column.

Constructors

Loc !Int !Int

Instances

Eq Loc

Defined in Zinza.Pos

Methods

(==) :: Loc -> Loc -> Bool

(/=) :: Loc -> Loc -> Bool

Show Loc

Defined in Zinza.Pos

Methods

showsPrec :: Int -> Loc -> ShowS

show :: Loc -> String

showList :: [Loc] -> ShowS

data Located a

Located element.

Constructors

L !Loc a

Instances

Functor Located

Defined in Zinza.Pos

Methods

fmap :: (a -> b) -> Located a -> Located b

(<$) :: a -> Located b -> Located a

Foldable Located

Defined in Zinza.Pos

Methods

fold :: Monoid m => Located m -> m

foldMap :: Monoid m => (a -> m) -> Located a -> m

foldr :: (a -> b -> b) -> b -> Located a -> b

foldr' :: (a -> b -> b) -> b -> Located a -> b

foldl :: (b -> a -> b) -> b -> Located a -> b

foldl' :: (b -> a -> b) -> b -> Located a -> b

foldr1 :: (a -> a -> a) -> Located a -> a

foldl1 :: (a -> a -> a) -> Located a -> a

toList :: Located a -> [a]

null :: Located a -> Bool

length :: Located a -> Int

elem :: Eq a => a -> Located a -> Bool

maximum :: Ord a => Located a -> a

minimum :: Ord a => Located a -> a

sum :: Num a => Located a -> a

product :: Num a => Located a -> a

Traversable Located

Defined in Zinza.Pos

Methods

traverse :: Applicative f => (a -> f b) -> Located a -> f (Located b)

sequenceA :: Applicative f => Located (f a) -> f (Located a)

mapM :: Monad m => (a -> m b) -> Located a -> m (Located b)

sequence :: Monad m => Located (m a) -> m (Located a)

Eq a => Eq (Located a)

Defined in Zinza.Pos

Methods

(==) :: Located a -> Located a -> Bool

(/=) :: Located a -> Located a -> Bool

Show a => Show (Located a)

Defined in Zinza.Pos

Methods

showsPrec :: Int -> Located a -> ShowS

show :: Located a -> String

showList :: [Located a] -> ShowS

zeroLoc :: Loc

Unknown location.

displayLoc :: Loc -> String

Pretty-print location.

class Traversable t => TraversableWithLoc t where

Some containers have location for each element.

Methods

traverseWithLoc :: Applicative f => (Loc -> a -> f b) -> t a -> f (t b)

Instances

TraversableWithLoc Expr

Defined in Zinza.Expr

Methods

traverseWithLoc :: Applicative f => (Loc -> a -> f b) -> Expr a -> f (Expr b)

TraversableWithLoc Node

Defined in Zinza.Node

Methods

traverseWithLoc :: Applicative f => (Loc -> a -> f b) -> Node a -> f (Node b)

Variables

type Var = String

Variable name, possibly a fieldname in the record.

type Selector = String

Haskell selector.