heterocephalus 1.0.1.0 → 1.0.1.1
raw patch · 4 files changed
+225/−18 lines, 4 filesPVP ok
version bump matches the API change (PVP)
API changes (from Hackage documentation)
Files
- README.md +194/−0
- heterocephalus.cabal +12/−4
- src/Text/Heterocephalus.hs +18/−6
- src/Text/Heterocephalus/Parse.hs +1/−8
+ README.md view
@@ -0,0 +1,194 @@+[](https://travis-ci.org/arowM/heterocephalus)+[](https://hackage.haskell.org/package/heterocephalus)+[](http://stackage.org/lts/package/heterocephalus)+[](http://stackage.org/nightly/package/heterocephalus)++++# Heterocephalus template engine++A type-safe template engine for working with popular front end development tools.++Any PRs are welcome, even for documentation fixes. (The main author of this library is not an English native.)++* [Who should use this?](#who-should-use-this)+* [Features](#features)+* [Usage](#usage)+* [Checking behaviours in `ghci`](#checking-behaviours-in-ghci)+* [Syntax](#syntax)+* [Why "heterocephalus"?](#why-heterocephalus)++## Who should use this?++If you are planning to use Haskell with recent web front-end tools like gulp,+webpack, npm, etc, then this library can help you!++There are many Haskell template engines today.+[Shakespeare](http://hackage.haskell.org/package/shakespeare) is great because+it checks template variables at compile time. Using Shakespeare, it's not+possible to for the template file to cause a runtime-error.++Shakespeare provides its own original ways of writing HTML+([Hamlet](https://hackage.haskell.org/package/shakespeare/docs/Text-Hamlet.html)),+CSS+([Cassius](https://hackage.haskell.org/package/shakespeare/docs/Text-Cassius.html)+/+[Lucius](https://hackage.haskell.org/package/shakespeare/docs/Text-Lucius.html)),+and JavaScript+([Julius](https://hackage.haskell.org/package/shakespeare-2.0.11.2/docs/Text-Julius.html)).+If you use these original markup languages, it is possible to use control+statements like `forall` (for looping) and `if` (for conditionals).++However, if you're using any other markup language (like+[pug](https://pugjs.org), [slim](http://slim-lang.com/),+[haml](http://haml.info/), normal HTML, normal CSS, etc), Shakespeare only+provides you with the+[Text.Shakespeare.Text](https://hackage.haskell.org/package/shakespeare/docs/Text-Shakespeare-Text.html)+module. This gives you variable interpolation, but no control statements like+`forall` or `if`.++[`Haiji`](https://hackage.haskell.org/package/haiji) is another interesting+library. It has all the features we require, but its templates take a very+[long time to compile](https://github.com/blueimpact/kucipong/pull/7) with+GHC >= 7.10.++Hetercephalus fills this missing niche. It gives you variable interpolation+along with control statements that can be used with any markup language. Its+compile times are reasonable.++## Features++Here are the main features of this module.++* __DO__ ensure that all interpolated variables are in scope++* __DO__ ensure that all interpolated variables have proper types for the template++* __DO__ expand the template literal on compile time++* __DO__ provide a way to use `forall` and `if` in the template++ `Text.Shakespeare.Text.text` has a way to do variable interpolation, but no+ way to use these types of control statements.++* __DO NOT__ enforce templates to obey a peculiar syntax++ Shakespeare templates make you use their original style (Hamlet, Cassius,+ Lucius, Julius, etc). The+ [`Text.Shakespeare.Text.text`](https://hackage.haskell.org/package/shakespeare/docs/Text-Shakespeare-Text.html#v:text)+ function does not require you to use any particular style, but it does not+ have control statements like `forall` and `if`.++ This makes it impossible to use Shakespeare with another template engine+ such as `pug` in front end side. It is not suitable for recent rich front+ end tools.++* __DO NOT__ have a long compile time++ `haiji` is another awesome template library. It has many of our required+ features, but it takes too long to compile when used with ghc >= 7.10.++* __DO NOT__ provide unneeded control statements++ Other template engines like [EDE](https://hackage.haskell.org/package/ede)+ provide rich control statements like importing external files.+ Heterocephalus does not provide control statements like this because it is+ supposed to be used with a rich front-end template engine (like pug, slim,+ etc).++## Usage++You can compile external template files with the following four functions:++* `compileTextFile`: A basic function that embeds variables without escaping and without default values.+* `compileTextFileWithDefault`: Same as `compileTextFile` but you can set default template values.+* `compileHtmlFile`: Same as `compileTextFile` but all embeded variables are escaped for html.+* `compileHtmlFileWithDefault`: Same as `compileHtmlFile` but you can set default template values.++For more details, see the [latest haddock+document](https://www.stackage.org/haddock/nightly/heterocephalus/Text-Heterocephalus.html).++## Checking behaviours in `ghci`++To check the behaviour, you can test in `ghci` as follows. Note that+`compileText` and `compileHtml` are used for checking syntaxes.++```haskell+$ stack install heterocephalus # Only first time+$ stack repl --no-build --no-load+Prelude> :m Text.Heterocephalus Text.Blaze.Renderer.String+Prelude> :set -XTemplateHaskell -XQuasiQuotes+Prelude> let a = 34; b = "<script>"; in renderMarkup [compileText|foo #{a} #{b}|]+"foo 34 <script>"+Prelude> let a = 34; b = "<script>"; in renderMarkup [compileHtml|foo #{a} #{b}|]+"foo 34 <script>"+```++## Syntax++The+[Text.Heterocephalus](https://www.stackage.org/haddock/nightly/heterocephalus/Text-Heterocephalus.html)+module provides two major features for use in template files: variable interpolation+and control statements.++### Variable interpolation++A Haskell variable can be embedded in the template file with the `#{foo}`+syntax. The value of the variable will be injected in at run time.++#### Basic usage++All of following are correct (this assumes that you have already declared the+`var` variable in your Haskell program and it is in scope):++```text+#{ var }+#{var}+#{ var}+#{var }+#{ var }+```++The variable must be an instance of+[`Text.Blaze.ToMarkup`](https://hackage.haskell.org/package/blaze-markup/docs/Text-Blaze.html#t:ToMarkup).++#### Advanced usage++You can use functions and data constructors as well.++```text+#{ even num }+#{ num + 3 }+#{ take 3 str }+#{ maybe "" id (Just b) }+```++### Control statements++Only two type of control statements are provided.++#### Forall++```+%{ forall x <- xs }+#{x}+%{ endforall }++%{ forall (k,v) <- kvs }+#{k}: #{v}+%{ endforall }+```++#### If++```+%{ if even num }+#{num} is even number.+%{ else }+#{num} is odd number.+%{ endif }+```++## Why "heterocephalus"?++"Heterocephalus" is the scientific name of the [naked mole-rat](https://en.wikipedia.org/wiki/Naked_mole-rat).
heterocephalus.cabal view
@@ -1,10 +1,17 @@ name: heterocephalus-version: 1.0.1.0-synopsis: A type safe template engine for collaborating with front end development tools+version: 1.0.1.1+synopsis: A type-safe template engine for working with popular front end development tools description:- Recent front end developing tools are growing fast and have created the complicated ecosystem, and few front end developer want to use Shakespeare template instead of commonly used @node@ friendly engines such that @pug@, @slim@, @haml@, though Shakespeare template has great feature of compile time variable interpolation and type checking.+ Recent front end development tools and languages are growing fast and have+ quite a complicated ecosystem. Few front end developers want to be forced+ use Shakespeare templates. Instead, they would rather use @node@ friendly+ engines such that @pug@, @slim@, and @haml@. However, in using these+ template engines, we lose the compile-time variable interpolation and type+ checking from Shakespeare. .- From this observation, Heterocephalus is developed for using with another feature rich template engine and only provides the way to interpolate server side variables into the precompiled template file with @forall@ and @if@ statement.+ Heterocephalus is intended for use with another feature rich template+ engine and provides a way to interpolate server side variables into a+ precompiled template file with @forall@ and @if@ statements. homepage: https://github.com/arowM/heterocephalus#readme license: MIT@@ -15,6 +22,7 @@ category: Web build-type: Simple extra-source-files: templates/*.txt+ README.md cabal-version: >=1.10 library
src/Text/Heterocephalus.hs view
@@ -3,6 +3,18 @@ {-# LANGUAGE CPP #-} {-# OPTIONS_GHC -fno-warn-orphans #-} +{- |+Module : Text.Heterocephalus++Copyright : Kadzuya Okamoto 2016+License : MIT++Stability : experimental+Portability : unknown++This module exports functions for working with frontend templates from Haskell.+-}+ module Text.Heterocephalus ( -- * Core functions@@ -70,7 +82,7 @@ compileTextFile :: FilePath -> Q Exp compileTextFile = compileFile textSetting -{-| Same as 'compileText' but we can specify default scope.+{-| Same as 'compileText' but allows the user to specify default values for template parameters. >>> :set -XOverloadedStrings >>> :{@@ -99,7 +111,7 @@ compileTextFileWithDefault :: FilePath -> DefaultScope -> Q Exp compileTextFileWithDefault fp scope = compileFileWithDefault scope textSetting fp -{-| Same as 'compileTextFile' but escapes template variables for Html.+{-| Same as 'compileTextFile' but escapes template variables in HTML. >>> putStr $ renderMarkup (let as = ["<a>", "b"] in $(compileHtmlFile "templates/sample.txt")) sample@@ -109,7 +121,7 @@ compileHtmlFile :: FilePath -> Q Exp compileHtmlFile fp = compileHtmlFileWithDefault fp [] -{-| Same as 'compileHtmlFile' but we can specify default scope.+{-| Same as 'compileHtmlFile' but allows the user to specify default values for template parameters. >>> :set -XOverloadedStrings >>> :{@@ -139,7 +151,7 @@ compileHtmlFileWithDefault fp scope = compileFileWithDefault scope htmlSetting fp {-| Heterocephalus quasi-quoter.- This function DOES NOT escape template variables.+ This function __DOES NOT__ escape template variables. To render the compiled file, use @'Text.Blaze.Renderer'.*.renderMarkup@. >>> renderMarkup (let as = ["<a>", "b"] in [compileText|sample %{ forall a <- as }key: #{a}, %{ endforall }|])@@ -151,8 +163,8 @@ compileText :: QuasiQuoter compileText = compile textSetting -{-| Heterocephalus quasi-quoter for Html.- Same as 'compileText' but this function do escape template variables for Html.+{-| Heterocephalus quasi-quoter for HTML.+ Same as 'compileText' but this function does escape template variables in HTML. >>> renderMarkup (let as = ["<a>", "b"] in [compileHtml|sample %{ forall a <- as }key: #{a}, %{ endforall }|]) "sample key: <a>, key: b, "
src/Text/Heterocephalus/Parse.hs view
@@ -23,7 +23,6 @@ = ControlForall Deref Binding | ControlEndForall | ControlIf Deref- | ControlElseIf Deref | ControlElse | ControlEndIf | NoControl Content@@ -163,8 +162,7 @@ parseControl' :: UserParser () Control parseControl' =- try parseForall <|> try parseEndForall <|> try parseIf <|> try parseElseIf <|>- try parseElse <|>+ try parseForall <|> try parseEndForall <|> try parseIf <|> try parseElse <|> try parseEndIf where parseForall = do@@ -180,11 +178,6 @@ spaces x <- parseDeref return $ ControlIf x- parseElseIf = do- _ <- try $ string "elseif"- spaces- x <- parseDeref- return $ ControlElseIf x parseElse = do _ <- try $ string "else" return $ ControlElse