doing `IO` (like database access) are the first things that come to
mind.
-The initial reason of existence of this library is its use
+The reason of 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?
## Unleash the monads
+[Text.BlazeT](https://hackage.haskell.org/package/blazeT/docs/Text-BlazeT.html) exports
+`runWith` and `execWith`, which work on any
+`Text.Blaze.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:
+
+```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 basically a `WriterT` writing `Blaze.Markup`:
```Haskell
newtype MarkupT m a = MarkupT { fromMarkupT :: WriterT B.Markup m a }
--- /dev/null
+{-# 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
+
,runMarkupT
,execMarkup
,execMarkupT
+ ,runWith
+ ,execWith
) where
import qualified Text.Blaze as B
,wrapMarkupT
,wrapMarkup2
,wrapMarkupT2
+ ,runWith
+ ,execWith
) where
+import Control.Arrow
import Control.Monad.Identity
import Control.Monad.Trans.Class
import Control.Monad.Writer.Strict
runMarkupT = runWriterT . fromMarkupT
{-# INLINE runMarkupT #-}
+-- | run the MarkupT and return a pair consisting of the result of the
+-- computation and the blaze markup rendered with a blaze renderer
+-- like 'Text.Blaze.Renderer.Text.renderHtml'
+runWith :: Monad m => (MarkupM () -> c) -> MarkupT m a -> m (a, c)
+runWith renderer = liftM (second $ renderer . wrapMarkup) . runMarkupT
+{-# INLINE runWith #-}
+
execMarkupT :: Monad m => MarkupT m a -> m B.Markup
execMarkupT = liftM snd . runMarkupT
{-# INLINE execMarkupT #-}
+execWith :: Monad m => (MarkupM () -> c) -> MarkupT m a -> m c
+execWith renderer = liftM snd . runWith renderer
+{-# INLINE execWith #-}
+
runMarkup :: MarkupM a -> (a,B.Markup)
runMarkup = runIdentity . runMarkupT
{-# INLINE runMarkup #-}
module Text.BlazeT.Renderer.Pretty
( renderMarkup
, renderHtml
- , renderMarkupT
- , renderHtmlT
) where
-import Control.Monad
-import Control.Monad.Identity
import qualified Text.Blaze.Renderer.Pretty as BU
import Text.BlazeT
renderMarkup :: MarkupM a -> String
-renderMarkup = runIdentity . renderMarkupT
-renderMarkupT :: Monad m => MarkupT m a -> m String
-renderMarkupT = liftM BU.renderMarkup . execMarkupT
+renderMarkup = BU.renderMarkup . execMarkup
renderHtml :: MarkupM a -> String
renderHtml = renderMarkup
-renderHtmlT :: Monad m => MarkupT m a -> m String
-renderHtmlT = renderMarkupT
( fromChoiceString
, renderMarkup
, renderHtml
- , renderMarkupT
- , renderHtmlT
) where
import Control.Monad
fromChoiceString = BU.fromChoiceString
renderMarkup :: MarkupM a -> String
-renderMarkup = runIdentity . renderMarkupT
-renderMarkupT :: Monad m => MarkupT m a -> m String
-renderMarkupT = liftM BU.renderMarkup . execMarkupT
+renderMarkup = BU.renderMarkup . execMarkup
renderHtml :: MarkupM a -> String
renderHtml = renderMarkup
-renderHtmlT :: Monad m => MarkupT m a -> m String
-renderHtmlT = renderMarkupT
module Text.BlazeT.Renderer.Text
- ( renderMarkupBuilderT
- , renderMarkupBuilder
- , renderMarkupBuilderWithT
- , renderMarkupT
- , renderMarkupWithT
- , renderHtmlBuilderT
- , renderHtmlBuilderWithT
- , renderHtmlT
- , renderHtmlWithT
+ ( renderMarkupBuilder
, renderMarkupBuilderWith
, renderMarkup
, renderMarkupWith
, renderHtmlWith
) where
-import Control.Monad
import Data.ByteString (ByteString)
-import Control.Monad.Identity
import Data.Text (Text)
import qualified Data.Text.Lazy as L
import qualified Data.Text.Lazy.Builder as B
import Text.BlazeT
renderMarkupBuilder :: MarkupM a -> B.Builder
-renderMarkupBuilder = runIdentity . renderMarkupBuilderT
-
-renderMarkupBuilderT :: Monad m => MarkupT m a -> m B.Builder
-renderMarkupBuilderT = liftM BU.renderMarkupBuilder . execMarkupT
+renderMarkupBuilder = BU.renderMarkupBuilder . execMarkup
renderHtmlBuilder :: MarkupM a -> B.Builder
renderHtmlBuilder = renderMarkupBuilder
-renderHtmlBuilderT :: Monad m => MarkupT m a -> m B.Builder
-renderHtmlBuilderT = renderMarkupBuilderT
-
renderMarkup :: MarkupM a -> L.Text
-renderMarkup = runIdentity . renderMarkupT
-renderMarkupT :: Monad m => MarkupT m a -> m L.Text
-renderMarkupT = liftM BU.renderMarkup . execMarkupT
+renderMarkup = BU.renderMarkup . execMarkup
renderHtml :: MarkupM a -> L.Text
renderHtml = renderMarkup
-renderHtmlT :: Monad m => MarkupT m a -> m L.Text
-renderHtmlT = renderMarkupT
-
-renderMarkupWithT :: Monad m => (ByteString -> Text) -> MarkupT m a -> m L.Text
-renderMarkupWithT g = liftM (BU.renderMarkupWith g) . execMarkupT
renderMarkupWith :: (ByteString -> Text) -> MarkupM a -> L.Text
-renderMarkupWith g = runIdentity . renderMarkupWithT g
-
-renderHtmlWithT :: Monad m => (ByteString -> Text) -> MarkupT m a -> m L.Text
-renderHtmlWithT g = liftM (BH.renderHtmlWith g) . execMarkupT
+renderMarkupWith g = (BH.renderHtmlWith g) . execMarkup
renderHtmlWith :: (ByteString -> Text) -> MarkupM a -> L.Text
-renderHtmlWith g = runIdentity . renderHtmlWithT g
-
-renderHtmlBuilderWithT :: Monad m => (ByteString -> Text) -> MarkupT m a -> m B.Builder
-renderHtmlBuilderWithT g = liftM (BH.renderHtmlBuilderWith g) . execMarkupT
-
-renderHtmlBuilderWith :: (ByteString -> Text) -> MarkupM a -> B.Builder
-renderHtmlBuilderWith g = runIdentity . renderHtmlBuilderWithT g
+renderHtmlWith = renderMarkupWith
+renderMarkupBuilderWith :: (ByteString -> Text) -> MarkupM a -> B.Builder
+renderMarkupBuilderWith g = (BU.renderMarkupBuilderWith g) . execMarkup
-renderMarkupBuilderWithT :: Monad m => (ByteString -> Text) -> MarkupT m a -> m B.Builder
-renderMarkupBuilderWithT g = liftM (BU.renderMarkupBuilderWith g) . execMarkupT
+renderHtmlBuilderWith :: (ByteString -> Text) -> MarkupM a -> B.Builder
+renderHtmlBuilderWith = renderHtmlBuilderWith
-renderMarkupBuilderWith :: (ByteString -> Text) -> MarkupM a -> B.Builder
-renderMarkupBuilderWith g = runIdentity . renderMarkupBuilderWithT g
, renderHtmlBuilder
, renderHtml
, renderHtmlToByteStringIO
-
- -- * new BlazeT stuff
- , renderMarkupBuilderT
- , renderMarkupT
- , renderMarkupToByteStringIOT
- , renderHtmlToByteStringIOT
- , renderHtmlBuilderT
- , renderHtmlT
) where
import qualified Blaze.ByteString.Builder as B
-import Control.Monad
-import Control.Monad.Identity
import qualified Data.ByteString as BS
import qualified Data.ByteString.Lazy as BL
import qualified Text.Blaze.Renderer.Utf8 as BU
import Text.BlazeT
renderMarkupBuilder :: MarkupM a -> B.Builder
-renderMarkupBuilder = runIdentity . renderMarkupBuilderT
-
-renderMarkupBuilderT :: Monad m => MarkupT m a -> m B.Builder
-renderMarkupBuilderT = liftM BU.renderMarkupBuilder . execMarkupT
+renderMarkupBuilder = BU.renderMarkupBuilder . execMarkup
renderHtmlBuilder :: MarkupM a -> B.Builder
renderHtmlBuilder = renderMarkupBuilder
-renderHtmlBuilderT :: Monad m => MarkupT m a -> m B.Builder
-renderHtmlBuilderT = renderMarkupBuilderT
-
renderMarkup :: MarkupM a -> BL.ByteString
-renderMarkup = runIdentity . renderMarkupT
-renderMarkupT :: Monad m => MarkupT m a -> m BL.ByteString
-renderMarkupT = liftM BU.renderMarkup . execMarkupT
+renderMarkup = BU.renderMarkup . execMarkup
renderHtml :: MarkupM a -> BL.ByteString
renderHtml = renderMarkup
-renderHtmlT :: Monad m => MarkupT m a -> m BL.ByteString
-renderHtmlT = renderMarkupT
renderMarkupToByteStringIO :: (BS.ByteString -> IO ()) -> MarkupM a -> IO ()
-renderMarkupToByteStringIO g = runIdentity . renderMarkupToByteStringIOT g
-renderMarkupToByteStringIOT :: Monad m => (BS.ByteString -> IO ()) ->
- MarkupT m a -> m (IO ())
-renderMarkupToByteStringIOT g = liftM (BU.renderMarkupToByteStringIO g) . execMarkupT
+renderMarkupToByteStringIO g = BU.renderMarkupToByteStringIO g . execMarkup
renderHtmlToByteStringIO :: (BS.ByteString -> IO ()) -> MarkupM a -> IO ()
-renderHtmlToByteStringIO g = runIdentity . renderMarkupToByteStringIOT g
-renderHtmlToByteStringIOT :: Monad m => (BS.ByteString -> IO ()) ->
- MarkupT m a -> m (IO ())
-renderHtmlToByteStringIOT g = liftM (BU.renderMarkupToByteStringIO g) . execMarkupT
+renderHtmlToByteStringIO = renderMarkupToByteStringIO
projects / github / fretlink / blazeT.git / commitdiff
