aboutsummaryrefslogtreecommitdiffhomepage
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md85
1 files changed, 72 insertions, 13 deletions
diff --git a/README.md b/README.md
index 0169fab..37e4be5 100644
--- a/README.md
+++ b/README.md
@@ -26,14 +26,14 @@ accumulating log or other diagnostic output
26doing `IO` (like database access) are the first things that come to 26doing `IO` (like database access) are the first things that come to
27mind. 27mind.
28 28
29The initial reason of existence of this library is its use 29The reason of existence of this library is its use
30in [Lykah](http://johannesgerer.com/Lykah), which powers my personal 30in [Lykah](http://johannesgerer.com/Lykah), which powers my personal
31website 31website
32[http://johannesgerer.com](http://johannesgerer.com/johannesgerer.com). In 32[http://johannesgerer.com](http://johannesgerer.com/johannesgerer.com). In
33Lykah, the HTML templates have access to the whole site structure (to 33Lykah, the HTML templates have access to the whole site structure (to
34build things like menus) and automatically check, insert and keep 34build things like menus or blog post lists) and automatically check,
35track of referenced pages and assets, which turns out to be very 35insert and keep track of referenced pages and assets, which turns out
36useful for the task of static website generation. 36to be very useful functionality of a static website generator.
37 37
38# How to use it? 38# How to use it?
39 39
@@ -51,27 +51,87 @@ their [documentation](https://jaspervdj.be/blaze/).
51 51
52## Unleash the monads 52## Unleash the monads
53 53
54[Text.BlazeT](https://hackage.haskell.org/package/blazeT/docs/Text-BlazeT.html)
55exports `runWith` and `execWith`, which work on any
56`Text.BlazeT.Renderer.*`. The rendered markup will be returned within
57the base monad, whose actions can be
58[`lift`ed](https://hackage.haskell.org/package/transformers-0.5.2.0/docs/Control-Monad-Trans-Class.html)
59into the Markup, as shown in the following example (from
60[here](src/Readme.hs)):
54 61
62```Haskell
63{-# LANGUAGE OverloadedStrings #-}
64
65import Data.Time (getCurrentTime)
66import Text.BlazeT.Html5 hiding (main)
67import Text.BlazeT.Renderer.String
68import Control.Monad.Trans.Class (lift)
69
70-- Backwords compatible Blaze HTML
71old :: Markup
72old = do
73 p $ "created with blaze-html"
74
75-- BlazeT HTML with lifted IO actions
76new :: MarkupT IO ()
77new = do
78 time <- lift getCurrentTime
79 p $ string $ "created with blazeT at " ++ show time
80
81main :: IO ()
82main = do
83 putStrLn $ renderMarkup old
84 putStrLn =<< execWith renderMarkup new
85
86```
87
88prints:
89
90```HTML
91<p>created with blaze-html</p>
92<p>created with blazeT at 2016-10-26 01:09:16.969147361 UTC</p>
93```
94
95# Installation
96
971. To make it available on your system (or sandbox) use `cabal install blazeT`.
98
992. To play around with the source, obtain by cloning this repo or use
100 `cabal get blazet`, enter the directory and run:
101
102```bash
103cabal sandbox init #optional
104cabal install
105```
106
107# Documentation on [Hackage](https://hackage.haskell.org/package/blazeT)
55 108
56# Implementation 109# Implementation
57 110
58... is located 111... is contained
59in 112in
60[Text.BlazeT.Internals](https://hackage.haskell.org/package/blazeT/docs/Text-BlazeT-Internals.html). 113[Text.BlazeT.Internals](https://hackage.haskell.org/package/blazeT/docs/Text-BlazeT-Internals.html).
61 114
62Everything build around the simple `newtype` definition of the 115Everything is build around the simple `newtype` definition of the
63`MarkupT` transformer, which makes use of the fact that `Blaze.Markup` 116`MarkupT` transformer, which makes use
64is 117the
65a 118[Monoid](https://hackage.haskell.org/package/base-4.7.0.2/docs/Data-Monoid.html) instance
66[Monoid](https://hackage.haskell.org/package/base-4.7.0.2/docs/Data-Monoid.html) and 119of `Blaze.Markup` and is basically a `WriterT` writing `Blaze.Markup`:
67which is basically a `WriterT` transformer writing `Blaze.Markup`:
68 120
69```Haskell 121```Haskell
70newtype MarkupT m a = MarkupT { fromMarkupT :: WriterT B.Markup m a } 122newtype MarkupT m a = MarkupT { fromMarkupT :: WriterT B.Markup m a }
71``` 123```
72 124
125The old `Text.Blaze.Markup` type is replaced by a rank-2 version of
126the transformer:
127
128```Haskell
129type Markup = forall m . Monad m => MarkupT m ()
130```
131
73Wrappers used to lift all `Blaze` entities into `BlazeT` are trivially 132Wrappers used to lift all `Blaze` entities into `BlazeT` are trivially
74expressible using basic `WriterT` class methods. Wrapping `Blaze.Markup` is simply `WriterT.tell`: 133expressible using basic `WriterT` class methods. Wrapping
134`Blaze.Markup` is simply `WriterT.tell`:
75 135
76```Haskell 136```Haskell
77wrapMarkupT :: Monad m => B.Markup -> MarkupT m () 137wrapMarkupT :: Monad m => B.Markup -> MarkupT m ()
@@ -84,4 +144,3 @@ wrapMarkupT2 :: Monad m => (B.Markup -> B.Markup) -> MarkupT m a -> MarkupT m a
84wrapMarkupT2 = censor 144wrapMarkupT2 = censor
85``` 145```
86 146
87