-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Builder to efficiently append text.
--   
--   Builder to efficiently append text, optimized for HTML generation.
--   There is a small usage example in the Text.Blaze.Builder.Core module,
--   you should begin by reading that.
@package blaze-builder
@version 0.1


-- | The builder monoid from BlazeHtml.
--   
--   Usage is fairly straightforward. Builders can be constructed from many
--   values, including <a>String</a> and <tt>Text</tt> values.
--   
--   <pre>
--   strings :: [String]
--   strings = replicate 10000 "Hello there!"
--   </pre>
--   
--   Concatenation should happen through the <a>Monoid</a> interface.
--   
--   <pre>
--   concatenation :: Builder
--   concatenation = mconcat $ map fromString strings
--   </pre>
--   
--   There is only one way to efficiently obtain the result: to convert the
--   <a>Builder</a> to a lazy <a>ByteString</a> using
--   <a>toLazyByteString</a>.
--   
--   <pre>
--   result :: L.ByteString
--   result = toLazyByteString concatenation
--   </pre>
module Text.Blaze.Builder.Core

-- | Main builder type. It simply contains a function to extract the actual
--   data.
data Builder

-- | Write abstraction so we can avoid some gory and bloody details. A
--   write abstration holds the exact size of the write in bytes, and a
--   function to carry out the write operation.
data Write
Write :: {-# UNPACK #-} !Int -> (Ptr Word8 -> IO ()) -> Write

-- | Write a single byte.
writeByte :: Word8 -> Write

-- | Write a strict <a>ByteString</a>.
writeByteString :: ByteString -> Write

-- | Construct a <a>Builder</a> from a single <a>Write</a> abstraction.
writeSingleton :: (a -> Write) -> a -> Builder

-- | Construct a builder writing a list of data from a write abstraction.
writeList :: (a -> Write) -> [a] -> Builder

-- | Construct a <a>Builder</a> from a single byte.
singleton :: Word8 -> Builder

-- | <i>O(n).</i> A Builder taking a <a>ByteString</a>, copying it.
fromByteString :: ByteString -> Builder

-- | <i>O(n).</i> Extract the lazy <a>ByteString</a> from the builder.
toLazyByteString :: Builder -> ByteString
instance Monoid Write
instance Monoid Builder


-- | A module that extends the builder monoid from BlazeHtml with a number
--   of functions to insert unicode as UTF-8.
module Text.Blaze.Builder.Utf8

-- | Write a Unicode character, encoding it as UTF-8.
writeChar :: Char -> Write

-- | An unescaped, utf8 encoded character.
fromChar :: Char -> Builder

-- | A list of unescaped, utf8 encoded characters.
fromString :: String -> Builder

-- | Create an UTF-8 encoded <a>Builder</a> from some <a>Text</a>.
fromText :: Text -> Builder


-- | A module that extends the builder monoid from BlazeHtml with function
--   to insert HTML, including HTML escaping and the like.
module Text.Blaze.Builder.Html

-- | Write an unicode character to a <a>Builder</a>, doing HTML escaping.
writeHtmlEscapedChar :: Char -> Write

-- | A HTML escaped <a>Char</a>.
fromHtmlEscapedChar :: Char -> Builder

-- | A HTML escaped <a>String</a>.
fromHtmlEscapedString :: String -> Builder

-- | An HTML escaped piece of <a>Text</a>.
fromHtmlEscapedText :: Text -> Builder