Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

205 lines (181 sloc) 7.113 kB
-----------------------------------------------------------------------------
-- |
-- Module : Text.Blaze.Builder
-- Copyright : (c) 2010 Jasper Van der Jeugt & Simon Meier
-- License : BSD3-style (see LICENSE)
--
-- Maintainer : Simon Meier <iridcode@gmail.com>
-- Stability : experimental
-- Portability : tested on GHC only
--
-- "Text.Blaze.Builder" is the main module, which you should import as a user
-- of the @blaze-builder@ library.
--
-- > import Text.Blaze.Builder
--
-- It provides you with a type 'Builder' that allows to efficiently construct
-- lazy bytestrings with a large average chunk size.
--
-- Intuitively, a 'Builder' denotes the construction of a part of a lazy
-- bytestring. Builders can either be created using one of the primitive
-- combinators in "Text.Blaze.Builder.Write" or by using one of the predefined
-- combinators for standard Haskell values (see the exposed modules of this
-- package). Concatenation of builders is done using 'mappend' from the
-- 'Monoid' typeclass.
--
-- Here is a small example that serializes a list of strings using the UTF-8
-- encoding.
--
-- @ import "Text.Blaze.Builder.Char.Utf8"@
--
-- > strings :: [String]
-- > strings = replicate 10000 "Hello there!"
--
-- The function @'fromString'@ creates a 'Builder' denoting the UTF-8 encoded
-- argument. Hence, UTF-8 encoding and concatenating all @strings@ can be done
-- follows.
--
-- > concatenation :: Builder
-- > concatenation = mconcat $ map fromString strings
--
-- The function 'toLazyByteString' can be used to execute a 'Builder' and
-- obtain the resulting lazy bytestring.
--
-- > result :: L.ByteString
-- > result = toLazyByteString concatenation
--
-- The @result@ is a lazy bytestring containing 10000 repetitions of the string
-- @\"Hello there!\"@ encoded using UTF-8. The corresponding 120000 bytes are
-- distributed among three chunks of 32kb and a last chunk of 6kb.
--
-- /A note on history./ This serialization library was inspired by the
-- @Data.Binary.Builder@ module provided by the @binary@ package. It was
-- originally developed with the specific needs of the @blaze-html@ package in
-- mind. Since then it has been restructured to serve as a drop-in replacement
-- for @Data.Binary.Builder@, which it improves upon both in speed as well as
-- expressivity.
-----------------------------------------------------------------------------
module Text.Blaze.Builder
(
-- * The @Builder@ type
Builder
-- * Creating builders
, module Text.Blaze.Builder.Write
, module Text.Blaze.Builder.Int
, module Text.Blaze.Builder.Word
, module Text.Blaze.Builder.ByteString
, flush
-- * Executing builders
, toLazyByteString
, toLazyByteStringWith
, toByteStringIO
, toByteStringIOWith
-- * Compatibility to Data.Binary.Builder from the binary package
--
-- | The following functions ensure that @"Text.Blaze.Builder"@ is a
-- drop-in replacement for @Data.Binary.Builder@ from the @binary@
-- package. Note that these functions are deprecated and may be removed
-- in future versions of the @blaze-builder@ package.
--
, empty -- DEPRECATED: use 'mempty' instead
, singleton -- DEPRECATED: use 'fromByte' instead
, append -- DEPRECATED: use 'mappend' instead
, putWord16be -- DEPRECATED: use 'fromWord<n><endian>' instead
, putWord32be --
, putWord64be --
, putWord16le --
, putWord32le --
, putWord64le -- for all these functions
, putWordhost --
, putWord16host --
, putWord32host --
, putWord64host --
) where
import Text.Blaze.Builder.Internal
import Text.Blaze.Builder.Write
import Text.Blaze.Builder.Int
import Text.Blaze.Builder.Word
import Text.Blaze.Builder.ByteString
import Data.Monoid
import Data.Word
------------------------------------------------------------------------------
-- API Compatibility to Data.Binary.Builder from 'binary'
------------------------------------------------------------------------------
-- | /O(1)/. An empty builder.
--
-- /Deprecated:/ use 'mempty' instead.
empty :: Builder
empty = mempty
{-# DEPRECATED empty "Use 'mempty' instead." #-}
-- | /O(1)/. Append two builders.
--
-- /Deprecated:/ use 'mappend' instead.
append :: Builder -> Builder -> Builder
append = mappend
{-# DEPRECATED append "Use 'mappend' instead." #-}
-- | /O(1)/. Serialize a single byte.
--
-- /Deprecated:/ use 'fromWord8' instead.
singleton :: Word8 -> Builder
singleton = fromWriteSingleton writeWord8
{-# DEPRECATED singleton "Use 'fromWord8' instead." #-}
-- | /O(1)/. Serialize a 'Word16' in big endian format.
--
-- /Deprecated:/ use 'fromWord16be' instead.
putWord16be :: Word16 -> Builder
putWord16be = fromWord16be
{-# DEPRECATED putWord16be "Use 'fromWord16be' instead." #-}
-- | /O(1)/. Serialize a 'Word32' in big endian format.
--
-- /Deprecated:/ use 'fromWord32be' instead.
putWord32be :: Word32 -> Builder
putWord32be = fromWord32be
{-# DEPRECATED putWord32be "Use 'fromWord32be' instead." #-}
-- | /O(1)/. Serialize a 'Word64' in big endian format.
--
-- /Deprecated:/ use 'fromWord64be' instead.
putWord64be :: Word64 -> Builder
putWord64be = fromWord64be
{-# DEPRECATED putWord64be "Use 'fromWord64be' instead." #-}
-- | /O(1)/. Serialize a 'Word16' in little endian format.
--
-- /Deprecated:/ use 'fromWord16le' instead.
putWord16le :: Word16 -> Builder
putWord16le = fromWord16le
{-# DEPRECATED putWord16le "Use 'fromWord16le' instead." #-}
-- | /O(1)/. Serialize a 'Word32' in little endian format.
--
-- /Deprecated:/ use 'fromWord32le' instead.
putWord32le :: Word32 -> Builder
putWord32le = fromWord32le
{-# DEPRECATED putWord32le "Use 'fromWord32le' instead." #-}
-- | /O(1)/. Serialize a 'Word64' in little endian format.
--
-- /Deprecated:/ use 'fromWord64le' instead.
putWord64le :: Word64 -> Builder
putWord64le = fromWord64le
{-# DEPRECATED putWord64le "Use 'fromWord64le' instead." #-}
-- | /O(1)/. Serialize a 'Word' in host endian format.
--
-- /Deprecated:/ use 'fromWordhost' instead.
putWordhost :: Word -> Builder
putWordhost = fromWordhost
{-# DEPRECATED putWordhost "Use 'fromWordhost' instead." #-}
-- | /O(1)/. Serialize a 'Word16' in host endian format.
--
-- /Deprecated:/ use 'fromWord16host' instead.
putWord16host :: Word16 -> Builder
putWord16host = fromWord16host
{-# DEPRECATED putWord16host "Use 'fromWord16host' instead." #-}
-- | /O(1)/. Serialize a 'Word32' in host endian format.
--
-- /Deprecated:/ use 'fromWord32host' instead.
putWord32host :: Word32 -> Builder
putWord32host = fromWord32host
{-# DEPRECATED putWord32host "Use 'fromWord32host' instead." #-}
-- | /O(1)/. Serialize a 'Word64' in host endian format.
--
-- /Deprecated:/ use 'fromWord64host' instead.
putWord64host :: Word64 -> Builder
putWord64host = fromWord64host
{-# DEPRECATED putWord64host "Use 'fromWord64host' instead." #-}
Jump to Line
Something went wrong with that request. Please try again.