A true monad (transformer) version of the
[blaze-markup](https://hackage.haskell.org/package/blaze-markup) and
[blaze-html](https://hackage.haskell.org/package/blaze-html)
-libraries.
+libraries:
-# Why?
+> BlazeHtml is a blazingly fast HTML combinator library for the
+> Haskell programming language. It embeds HTML templates in Haskell
+> code for optimal efficiency and composability.
+
+— from https://jaspervdj.be/blaze/.
+
+## What’s wrong with blaze?
+
+Blaze’s `Markup` and `Html` **cannot be used as Monads**, let alone Monad transformers.
While blaze's `Markup` and `Html` types have `Monad` instances and can
-leverage the the concise `do` notation, they do not satisfy
-the
-[Monad Laws](https://hackage.haskell.org/package/base-4.8.0.0/docs/Control-Monad.html#t:Monad) and
-thus cannot be used as Monads, let alone Monad transformers.
+leverage the concise `do` notation, they do not satisfy the
+[Monad Laws](https://hackage.haskell.org/package/base-4.8.0.0/docs/Control-Monad.html#t:Monad).
-## Use Cases
+## How do Monads help? - Use Cases
The `MarkupT` Monad Transformer enables us to write Markup (e.g. HTML)
templates that have access to all those Monads you cannot live without
anymore.
-Accessing an environment
-([MonadReader](https://hackage.haskell.org/package/mtl-2.2.1/docs/Control-Monad-Reader-Class.html)),
-accumulating log or other diagnostic output
+The first things that come to mind:
+
+* Accessing an environment
+([MonadReader](https://hackage.haskell.org/package/mtl-2.2.1/docs/Control-Monad-Reader-Class.html))
+* Logging and other diagnostic output
([MonadWriter](https://hackage.haskell.org/package/mtl-2.2.1/docs/Control-Monad-Writer-Class.html)),
-doing `IO` (like database access) are the first things that come to
-mind.
+* `IO` (e.g. for database access)
+
-The initial reason of existence of this library is its use
+The reason for the existence of this library is its use
in [Lykah](http://johannesgerer.com/Lykah), which powers my personal
website
[http://johannesgerer.com](http://johannesgerer.com/johannesgerer.com). In
Lykah, the HTML templates have access to the whole site structure (to
-build things like menus) and automatically check, insert and keep
-track of referenced pages and assets, which turns out to be very
-useful for the task of static website generation.
+build things like menus or blog post lists) and automatically check,
+insert and keep track of referenced pages and assets, which turns out
+to be very useful functionality of a static website generator.
-# How to use it?
+## Usage
-## Backwards compatible
+### Integrating with your existing code
The library is intended to serve as a drop-in replacement for the
`blaze-markup` and `blaze-html` libraries and should be backwards
For usage of blaze check out
their [documentation](https://jaspervdj.be/blaze/).
-## Unleash the monads
+### Unleash the monads
+
+[Text.BlazeT](https://hackage.haskell.org/package/blazeT/docs/Text-BlazeT.html)
+exports `runWith` and `execWith`, which work on any
+`Text.BlazeT.Renderer.*`. The rendered markup will be returned within
+the base monad, whose actions can be
+[`lift`ed](https://hackage.haskell.org/package/transformers-0.5.2.0/docs/Control-Monad-Trans-Class.html)
+into the Markup, as shown in the following example (from
+[here](src/Readme.hs)):
+
+```Haskell
+{-# LANGUAGE OverloadedStrings #-}
+
+import Data.Time (getCurrentTime)
+import Text.BlazeT.Html5 hiding (main)
+import Text.BlazeT.Renderer.String
+import Control.Monad.Trans.Class (lift)
+
+-- Backwords compatible Blaze HTML
+old :: Markup
+old = do
+ p $ "created with blaze-html"
+
+-- BlazeT HTML with lifted IO actions
+new :: MarkupT IO ()
+new = do
+ time <- lift getCurrentTime
+ p $ string $ "created with blazeT at " ++ show time
+
+main :: IO ()
+main = do
+ putStrLn $ renderMarkup old
+ putStrLn =<< execWith renderMarkup new
+
+```
+
+prints:
+```HTML
+<p>created with blaze-html</p>
+<p>created with blazeT at 2016-10-26 01:09:16.969147361 UTC</p>
+```
+
+## Installation
+
+1. To make it available on your system (or sandbox) use `cabal install blazeT`.
+2. To play around with the source, obtain by cloning this repo or use
+ `cabal get blazet`, enter the directory and run:
-# Implementation
+```bash
+cabal sandbox init #optional
+cabal install
+```
+
+## Documentation on [Hackage](https://hackage.haskell.org/package/blazeT)
+
+## Implementation
-... is located
+... is contained
in
[Text.BlazeT.Internals](https://hackage.haskell.org/package/blazeT/docs/Text-BlazeT-Internals.html).
-Everything build around the simple `newtype` definition of the
-`MarkupT` transformer, which makes use of the fact that `Blaze.Markup`
-is
-a
-[Monoid](https://hackage.haskell.org/package/base-4.7.0.2/docs/Data-Monoid.html) and
-which is basically a `WriterT` transformer writing `Blaze.Markup`:
+Everything is build around the simple `newtype` definition of the
+`MarkupT` transformer, which makes use
+the
+[Monoid](https://hackage.haskell.org/package/base-4.7.0.2/docs/Data-Monoid.html) instance
+of `Blaze.Markup` and is simply a `WriterT` writing `Blaze.Markup`:
```Haskell
newtype MarkupT m a = MarkupT { fromMarkupT :: WriterT B.Markup m a }
```
+The old `Text.Blaze.Markup` type is replaced by a rank-2 version of
+the transformer:
+
+```Haskell
+type Markup = forall m . Monad m => MarkupT m ()
+```
+
Wrappers used to lift all `Blaze` entities into `BlazeT` are trivially
-expressible using basic `WriterT` class methods. Wrapping `Blaze.Markup` is simply `WriterT.tell`:
+expressible using basic `WriterT` class methods. Wrapping
+`Blaze.Markup` is simply `WriterT.tell`:
```Haskell
wrapMarkupT :: Monad m => B.Markup -> MarkupT m ()
wrapMarkupT2 = censor
```
-
projects / github / fretlink / blazeT.git / blobdiff