aboutsummaryrefslogtreecommitdiffhomepage
path: root/README.md
diff options
context:
space:
mode:
authorJohannes Gerer <oss@johannesgerer.com>2016-10-26 02:07:02 +0200
committerJohannes Gerer <oss@johannesgerer.com>2016-10-26 02:07:02 +0200
commit675085c2e0b0b851378da08b7d73024766107c87 (patch)
tree5a927de4a9576aef7e6129b96e74aa5c96f9ffb6 /README.md
downloadblazeT-675085c2e0b0b851378da08b7d73024766107c87.tar.gz
blazeT-675085c2e0b0b851378da08b7d73024766107c87.tar.zst
blazeT-675085c2e0b0b851378da08b7d73024766107c87.zip
Initial
Diffstat (limited to 'README.md')
-rw-r--r--README.md87
1 files changed, 87 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0169fab
--- /dev/null
+++ b/README.md
@@ -0,0 +1,87 @@
1# blazeT [![Build Status](https://travis-ci.org/johannesgerer/blazeT.svg?branch=master)](https://travis-ci.org/johannesgerer/blazeT) [![Hackage](https://img.shields.io/hackage/v/blazeT.svg)](https://hackage.haskell.org/package/blazeT)
2
3A true monad (transformer) version of the
4[blaze-markup](https://hackage.haskell.org/package/blaze-markup) and
5[blaze-html](https://hackage.haskell.org/package/blaze-html)
6libraries.
7
8# Why?
9
10While blaze's `Markup` and `Html` types have `Monad` instances and can
11leverage the the concise `do` notation, they do not satisfy
12the
13[Monad Laws](https://hackage.haskell.org/package/base-4.8.0.0/docs/Control-Monad.html#t:Monad) and
14thus cannot be used as Monads, let alone Monad transformers.
15
16## Use Cases
17
18The `MarkupT` Monad Transformer enables us to write Markup (e.g. HTML)
19templates that have access to all those Monads you cannot live without
20anymore.
21
22Accessing an environment
23([MonadReader](https://hackage.haskell.org/package/mtl-2.2.1/docs/Control-Monad-Reader-Class.html)),
24accumulating log or other diagnostic output
25([MonadWriter](https://hackage.haskell.org/package/mtl-2.2.1/docs/Control-Monad-Writer-Class.html)),
26doing `IO` (like database access) are the first things that come to
27mind.
28
29The initial reason of existence of this library is its use
30in [Lykah](http://johannesgerer.com/Lykah), which powers my personal
31website
32[http://johannesgerer.com](http://johannesgerer.com/johannesgerer.com). In
33Lykah, the HTML templates have access to the whole site structure (to
34build things like menus) and automatically check, insert and keep
35track of referenced pages and assets, which turns out to be very
36useful for the task of static website generation.
37
38# How to use it?
39
40## Backwards compatible
41
42The library is intended to serve as a drop-in replacement for the
43`blaze-markup` and `blaze-html` libraries and should be backwards
44compatible:
45
46Simply replace your `module Text.Blaze.*` imports with `module
47Text.BlazeT.*` and it should give the same results.
48
49For usage of blaze check out
50their [documentation](https://jaspervdj.be/blaze/).
51
52## Unleash the monads
53
54
55
56# Implementation
57
58... is located
59in
60[Text.BlazeT.Internals](https://hackage.haskell.org/package/blazeT/docs/Text-BlazeT-Internals.html).
61
62Everything build around the simple `newtype` definition of the
63`MarkupT` transformer, which makes use of the fact that `Blaze.Markup`
64is
65a
66[Monoid](https://hackage.haskell.org/package/base-4.7.0.2/docs/Data-Monoid.html) and
67which is basically a `WriterT` transformer writing `Blaze.Markup`:
68
69```Haskell
70newtype MarkupT m a = MarkupT { fromMarkupT :: WriterT B.Markup m a }
71```
72
73Wrappers used to lift all `Blaze` entities into `BlazeT` are trivially
74expressible using basic `WriterT` class methods. Wrapping `Blaze.Markup` is simply `WriterT.tell`:
75
76```Haskell
77wrapMarkupT :: Monad m => B.Markup -> MarkupT m ()
78wrapMarkupT = tell
79```
80Wrapping functions that modify `Blaze.Markup` is simply `WriterT.censor`:
81
82```Haskell
83wrapMarkupT2 :: Monad m => (B.Markup -> B.Markup) -> MarkupT m a -> MarkupT m a
84wrapMarkupT2 = censor
85```
86
87