libghc-blaze-builder-doc 0.3.3.2-1 / usr / share / doc / libghc-blaze-builder-doc / html / blaze-builder.txt

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


-- | Efficient buffered output.
--   
--   This library provides an abstraction of buffered output of byte
--   streams and several convenience functions to exploit it. For example,
--   it allows to efficiently serialize Haskell values to lazy bytestrings
--   with a large average chunk size. The large average chunk size allows
--   to make good use of cache prefetching in later processing steps (e.g.
--   compression) and reduces the system call overhead when writing the
--   resulting lazy bytestring to a file or sending it over the network.
@package blaze-builder
@version 0.3.3.2


-- | Core types and functions for the <a>Builder</a> monoid and the
--   <a>Put</a> monad based based on the 'blaze-builder' library by Jasper
--   van der Jeugt and Simon Meier.
module Blaze.ByteString.Builder.Internal.Types
data BufRange
BufRange :: {-# UNPACK #-} !(Ptr Word8) -> {-# UNPACK #-} !(Ptr Word8) -> BufRange
data BuildSignal a
Done :: {-# UNPACK #-} !(Ptr Word8) -> a -> BuildSignal a
BufferFull :: {-# UNPACK #-} !Int -> {-# UNPACK #-} !(Ptr Word8) -> !(BuildStep a) -> BuildSignal a
InsertByteString :: {-# UNPACK #-} !(Ptr Word8) -> !ByteString -> !(BuildStep a) -> BuildSignal a
newtype BuildStep a
BuildStep :: (BufRange -> IO (BuildSignal a)) -> BuildStep a
runBuildStep :: BuildStep a -> BufRange -> IO (BuildSignal a)
done :: Ptr Word8 -> a -> BuildSignal a
bufferFull :: Int -> Ptr Word8 -> (BufRange -> IO (BuildSignal a)) -> BuildSignal a
insertByteString :: Ptr Word8 -> ByteString -> (BufRange -> IO (BuildSignal a)) -> BuildSignal a
buildStep :: (BufRange -> IO (BuildSignal a)) -> BuildStep a
newtype Builder
Builder :: (forall r. BuildStep r -> BuildStep r) -> Builder
unBuilder :: Builder -> forall r. BuildStep r -> BuildStep r
newtype Put a
Put :: (forall r. (a -> BuildStep r) -> BuildStep r) -> Put a
unPut :: Put a -> forall r. (a -> BuildStep r) -> BuildStep r
putBuildStepCont :: (forall r. (a -> BufRange -> IO (BuildSignal r)) -> (BufRange -> IO (BuildSignal r))) -> Put a
fromBuildStepCont :: (forall r. (BufRange -> IO (BuildSignal r)) -> (BufRange -> IO (BuildSignal r))) -> Builder

-- | Put the given builder.
putBuilder :: Builder -> Put ()

-- | Ignore the value of a put and only exploit its output side effect.
fromPut :: Put a -> Builder

-- | Lift the given IO action.
putLiftIO :: IO a -> Put a
instance Monad Put
instance Functor Put
instance Monoid Builder


-- | A general and efficient write type that allows for the easy
--   construction of builders for (smallish) bounded size writes to a
--   buffer.
--   
--   FIXME: Improve documentation.
module Blaze.ByteString.Builder.Internal.Write

-- | Changing a sequence of bytes starting from the given pointer.
--   <a>Poke</a>s are the most primitive buffer manipulation. In most
--   cases, you don't use the explicitely but as part of a <a>Write</a>,
--   which also tells how many bytes will be changed at most.
data Poke
runPoke :: Poke -> Ptr Word8 -> IO (Ptr Word8)

-- | <tt>pokeN size io</tt> creates a write that denotes the writing of
--   <tt>size</tt> bytes to a buffer using the IO action <tt>io</tt>. Note
--   that <tt>io</tt> MUST write EXACTLY <tt>size</tt> bytes to the buffer!
pokeN :: Int -> (Ptr Word8 -> IO ()) -> Poke

-- | A write of a bounded number of bytes.
--   
--   When defining a function <tt>write :: a -&gt; Write</tt> for some
--   <tt>a</tt>, then it is important to ensure that the bound on the
--   number of bytes written is data-independent. Formally,
--   
--   <pre>
--   forall x y. getBound (write x) = getBound (write y)
--   </pre>
--   
--   The idea is that this data-independent bound is specified such that
--   the compiler can optimize the check, if there are enough free bytes in
--   the buffer, to a single subtraction between the pointer to the next
--   free byte and the pointer to the end of the buffer with this constant
--   bound of the maximal number of bytes to be written.
data Write

-- | Run the <a>Poke</a> action of a write.
runWrite :: Write -> Ptr Word8 -> IO (Ptr Word8)

-- | Extract the maximal number of bytes that this write could write.
getBound :: Write -> Int

-- | Extract the maximal number of bytes that this write could write in any
--   case. Assumes that the bound of the write is data-independent.
getBound' :: String -> (a -> Write) -> Int

-- | Extract the <a>Poke</a> action of a write.
getPoke :: Write -> Poke

-- | <tt>exactWrite size io</tt> creates a bounded write that can later be
--   converted to a builder that writes exactly <tt>size</tt> bytes. Note
--   that <tt>io</tt> MUST write EXACTLY <tt>size</tt> bytes to the buffer!
exactWrite :: Int -> (Ptr Word8 -> IO ()) -> Write

-- | <tt>boundedWrite size write</tt> creates a bounded write from a
--   <tt>write</tt> that does not write more than <tt>size</tt> bytes.
boundedWrite :: Int -> Poke -> Write

-- | <tt>writeLiftIO io write</tt> creates a write executes the <tt>io</tt>
--   action to compute the value that is then written.
writeLiftIO :: (a -> Write) -> IO a -> Write

-- | <tt>writeIf p wTrue wFalse x</tt> creates a <a>Write</a> with a
--   <a>Poke</a> equal to <tt>wTrue x</tt>, if <tt>p x</tt> and equal to
--   <tt>wFalse x</tt> otherwise. The bound of this new <a>Write</a> is the
--   maximum of the bounds for either <a>Write</a>. This yields a data
--   independent bound, if the bound for <tt>wTrue</tt> and <tt>wFalse</tt>
--   is already data independent.
writeIf :: (a -> Bool) -> (a -> Write) -> (a -> Write) -> (a -> Write)

-- | Compare the value to a test value and use the first write action for
--   the equal case and the second write action for the non-equal case.
writeEq :: Eq a => a -> (a -> Write) -> (a -> Write) -> (a -> Write)

-- | TODO: Test this. It might well be too difficult to use. FIXME: Better
--   name required!
writeOrdering :: (a -> Ordering) -> (a -> Write) -> (a -> Write) -> (a -> Write) -> (a -> Write)

-- | A write combinator useful to build decision trees for deciding what
--   value to write with a constant bound on the maximal number of bytes
--   written.
writeOrd :: Ord a => a -> (a -> Write) -> (a -> Write) -> (a -> Write) -> (a -> Write)

-- | Create a builder that execute a single <a>Write</a>.
fromWrite :: Write -> Builder
fromWriteSingleton :: (a -> Write) -> (a -> Builder)

-- | Construct a <a>Builder</a> writing a list of data one element at a
--   time.
fromWriteList :: (a -> Write) -> [a] -> Builder

-- | Write a storable value.
writeStorable :: Storable a => a -> Write

-- | A builder that serializes a storable value. No alignment is done.
fromStorable :: Storable a => a -> Builder

-- | A builder that serializes a list of storable values by writing them
--   consecutively. No alignment is done. Parsing information needs to be
--   provided externally.
fromStorables :: Storable a => [a] -> Builder
instance Monoid Write
instance Monoid Poke


-- | Execution of the <a>Put</a> monad and hence also <a>Builder</a>s with
--   respect to buffers.
module Blaze.ByteString.Builder.Internal.Buffer

-- | A buffer <tt>Buffer fpbuf p0 op ope</tt> describes a buffer with the
--   underlying byte array <tt>fpbuf..ope</tt>, the currently written slice
--   <tt>p0..op</tt> and the free space <tt>op..ope</tt>.
data Buffer
Buffer :: {-# UNPACK #-} !(ForeignPtr Word8) -> {-# UNPACK #-} !(Ptr Word8) -> {-# UNPACK #-} !(Ptr Word8) -> {-# UNPACK #-} !(Ptr Word8) -> Buffer

-- | The size of the free space of the buffer.
freeSize :: Buffer -> Int

-- | The size of the written slice in the buffer.
sliceSize :: Buffer -> Int

-- | The size of the whole byte array underlying the buffer.
bufferSize :: Buffer -> Int

-- | <tt>allocBuffer size</tt> allocates a new buffer of size
--   <tt>size</tt>.
allocBuffer :: Int -> IO Buffer

-- | Resets the beginning of the next slice and the next free byte such
--   that the whole buffer can be filled again.
reuseBuffer :: Buffer -> Buffer

-- | Move the beginning of the slice to the next free byte such that the
--   remaining free space of the buffer can be filled further. This
--   operation is safe and can be used to fill the remaining part of the
--   buffer after a direct insertion of a bytestring or a flush.
nextSlice :: Int -> Buffer -> Maybe Buffer

-- | Update the end of slice pointer.
updateEndOfSlice :: Buffer -> Ptr Word8 -> Buffer

-- | Execute a build step on the given buffer.
execBuildStep :: BuildStep a -> Buffer -> IO (BuildSignal a)

-- | Convert the buffer to a bytestring. This operation is unsafe in the
--   sense that created bytestring shares the underlying byte array with
--   the buffer. Hence, depending on the later use of this buffer (e.g., if
--   it gets reset and filled again) referential transparency may be lost.
unsafeFreezeBuffer :: Buffer -> ByteString

-- | Convert a buffer to a non-empty bytestring. See
--   <a>unsafeFreezeBuffer</a> for the explanation of why this operation
--   may be unsafe.
unsafeFreezeNonEmptyBuffer :: Buffer -> Maybe ByteString

-- | A buffer allocation strategy <tt>(buf0, nextBuf)</tt> specifies the
--   initial buffer to use and how to compute a new buffer <tt>nextBuf
--   minSize buf</tt> with at least size <tt>minSize</tt> from a filled
--   buffer <tt>buf</tt>. The double nesting of the <tt>IO</tt> monad helps
--   to ensure that the reference to the filled buffer <tt>buf</tt> is lost
--   as soon as possible, but the new buffer doesn't have to be allocated
--   too early.
type BufferAllocStrategy = (IO Buffer, Int -> Buffer -> IO (IO Buffer))

-- | The simplest buffer allocation strategy: whenever a buffer is
--   requested, allocate a new one that is big enough for the next build
--   step to execute.
--   
--   NOTE that this allocation strategy may spill quite some memory upon
--   direct insertion of a bytestring by the builder. Thats no problem for
--   garbage collection, but it may lead to unreasonably high memory
--   consumption in special circumstances.
allNewBuffersStrategy :: Int -> BufferAllocStrategy

-- | An unsafe, but possibly more efficient buffer allocation strategy:
--   reuse the buffer, if it is big enough for the next build step to
--   execute.
reuseBufferStrategy :: IO Buffer -> BufferAllocStrategy

-- | Execute a put on a buffer.
--   
--   TODO: Generalize over buffer allocation strategy.
runPut :: Monad m => (IO (BuildSignal a) -> m (BuildSignal a)) -> (Int -> Buffer -> m Buffer) -> (ByteString -> m ()) -> Put a -> Buffer -> m (a, Buffer)


-- | Core types and functions for the <a>Builder</a> monoid and the
--   <a>Put</a> monad.
module Blaze.ByteString.Builder.Internal
data BufRange
BufRange :: {-# UNPACK #-} !(Ptr Word8) -> {-# UNPACK #-} !(Ptr Word8) -> BufRange
data BuildSignal a
data BuildStep a
done :: Ptr Word8 -> a -> BuildSignal a
bufferFull :: Int -> Ptr Word8 -> (BufRange -> IO (BuildSignal a)) -> BuildSignal a
insertByteString :: Ptr Word8 -> ByteString -> (BufRange -> IO (BuildSignal a)) -> BuildSignal a
data Builder
fromBuildStepCont :: (forall r. (BufRange -> IO (BuildSignal r)) -> (BufRange -> IO (BuildSignal r))) -> Builder

-- | Ignore the value of a put and only exploit its output side effect.
fromPut :: Put a -> Builder

-- | Output all data written in the current buffer and start a new chunk.
--   
--   The use of this function depends on how the resulting bytestrings are
--   consumed. <a>flush</a> is possibly not very useful in non-interactive
--   scenarios. However, it is kept for compatibility with the builder
--   provided by Data.Binary.Builder.
--   
--   When using <a>toLazyByteString</a> to extract a lazy <a>ByteString</a>
--   from a <a>Builder</a>, this means that a new chunk will be started in
--   the resulting lazy <a>ByteString</a>. The remaining part of the buffer
--   is spilled, if the reamining free space is smaller than the minimal
--   desired buffer size.
flush :: Builder
data Put a

-- | Put the given builder.
putBuilder :: Builder -> Put ()
putBuildStepCont :: (forall r. (a -> BufRange -> IO (BuildSignal r)) -> (BufRange -> IO (BuildSignal r))) -> Put a

-- | Lift the given IO action.
putLiftIO :: IO a -> Put a

-- | Run a <a>Write</a> to produce a strict <a>ByteString</a>. This is
--   equivalent to <tt>(<a>toByteString</a> . <a>fromWrite</a>)</tt>, but
--   is more efficient because it uses just one appropriately-sized buffer.
writeToByteString :: Write -> ByteString

-- | Extract the lazy <a>ByteString</a> from the builder by running it with
--   default buffer sizes. Use this function, if you do not have any
--   special considerations with respect to buffer sizes.
--   
--   <pre>
--   <a>toLazyByteString</a> b = <a>toLazyByteStringWith</a> <a>defaultBufferSize</a> <a>defaultMinimalBufferSize</a> <a>defaultFirstBufferSize</a> b L.empty
--   </pre>
--   
--   Note that <tt><a>toLazyByteString</a></tt> is a <tt>Monoid</tt>
--   homomorphism.
--   
--   <pre>
--   toLazyByteString mempty          == mempty
--   toLazyByteString (x `mappend` y) == toLazyByteString x `mappend` toLazyByteString y
--   </pre>
--   
--   However, in the second equation, the left-hand-side is generally
--   faster to execute.
toLazyByteString :: Builder -> ByteString

-- | Run a <a>Builder</a> with the given buffer sizes.
--   
--   Use this function for integrating the <a>Builder</a> type with other
--   libraries that generate lazy bytestrings.
--   
--   Note that the builders should guarantee that on average the desired
--   chunk size is attained. Builders may decide to start a new buffer and
--   not completely fill the existing buffer, if this is faster. However,
--   they should not spill too much of the buffer, if they cannot
--   compensate for it.
--   
--   A call <tt>toLazyByteStringWith bufSize minBufSize firstBufSize</tt>
--   will generate a lazy bytestring according to the following strategy.
--   First, we allocate a buffer of size <tt>firstBufSize</tt> and start
--   filling it. If it overflows, we allocate a buffer of size
--   <tt>minBufSize</tt> and copy the first buffer to it in order to avoid
--   generating a too small chunk. Finally, every next buffer will be of
--   size <tt>bufSize</tt>. This, slow startup strategy is required to
--   achieve good speed for short (&lt;200 bytes) resulting bytestrings, as
--   for them the allocation cost is of a large buffer cannot be
--   compensated. Moreover, this strategy also allows us to avoid spilling
--   too much memory for short resulting bytestrings.
--   
--   Note that setting <tt>firstBufSize &gt;= minBufSize</tt> implies that
--   the first buffer is no longer copied but allocated and filled
--   directly. Hence, setting <tt>firstBufSize = bufSize</tt> means that
--   all chunks will use an underlying buffer of size <tt>bufSize</tt>.
--   This is recommended, if you know that you always output more than
--   <tt>minBufSize</tt> bytes.
toLazyByteStringWith :: Int -> Int -> Int -> Builder -> ByteString -> ByteString

-- | Run the builder to construct a strict bytestring containing the
--   sequence of bytes denoted by the builder. This is done by first
--   serializing to a lazy bytestring and then packing its chunks to a
--   appropriately sized strict bytestring.
--   
--   <pre>
--   toByteString = packChunks . toLazyByteString
--   </pre>
--   
--   Note that <tt><a>toByteString</a></tt> is a <tt>Monoid</tt>
--   homomorphism.
--   
--   <pre>
--   toByteString mempty          == mempty
--   toByteString (x `mappend` y) == toByteString x `mappend` toByteString y
--   </pre>
--   
--   However, in the second equation, the left-hand-side is generally
--   faster to execute.
toByteString :: Builder -> ByteString

-- | Run the builder with a <a>defaultBufferSize</a>d buffer and execute
--   the given <a>IO</a> action whenever the buffer is full or gets
--   flushed.
--   
--   <pre>
--   <a>toByteStringIO</a> = <a>toByteStringIOWith</a> <a>defaultBufferSize</a>
--   </pre>
--   
--   This is a <tt>Monoid</tt> homomorphism in the following sense.
--   
--   <pre>
--   toByteStringIO io mempty          == return ()
--   toByteStringIO io (x `mappend` y) == toByteStringIO io x &gt;&gt; toByteStringIO io y
--   </pre>
toByteStringIO :: (ByteString -> IO ()) -> Builder -> IO ()

-- | <tt>toByteStringIOWith bufSize io b</tt> runs the builder <tt>b</tt>
--   with a buffer of at least the size <tt>bufSize</tt> and executes the
--   <a>IO</a> action <tt>io</tt> whenever the buffer is full.
--   
--   Compared to <a>toLazyByteStringWith</a> this function requires less
--   allocation, as the output buffer is only allocated once at the start
--   of the serialization and whenever something bigger than the current
--   buffer size has to be copied into the buffer, which should happen very
--   seldomly for the default buffer size of 32kb. Hence, the pressure on
--   the garbage collector is reduced, which can be an advantage when
--   building long sequences of bytes.
toByteStringIOWith :: Int -> (ByteString -> IO ()) -> Builder -> IO ()

-- | The default length (64) for the first buffer to be allocated when
--   converting a <a>Builder</a> to a lazy bytestring.
--   
--   See <a>toLazyByteStringWith</a> for further explanation.
defaultFirstBufferSize :: Int

-- | The minimal length (~4kb) a buffer must have before filling it and
--   outputting it as a chunk of the output stream.
--   
--   This size determines when a buffer is spilled after a <a>flush</a> or
--   a direct bytestring insertion. It is also the size of the first chunk
--   generated by <a>toLazyByteString</a>.
defaultMinimalBufferSize :: Int

-- | Default size (~32kb) for the buffer that becomes a chunk of the output
--   stream once it is filled.
defaultBufferSize :: Int

-- | The maximal number of bytes for that copying is cheaper than direct
--   insertion into the output stream. This takes into account the
--   fragmentation that may occur in the output buffer due to the early
--   <a>flush</a> implied by the direct bytestring insertion.
--   
--   <pre>
--   <a>defaultMaximalCopySize</a> = 2 * <a>defaultMinimalBufferSize</a>
--   </pre>
defaultMaximalCopySize :: Int


-- | <a>Write</a>s and <a>Builder</a>s for serializing Unicode characters
--   using the UTF-8 encoding.
module Blaze.ByteString.Builder.Char.Utf8

-- | Write a UTF-8 encoded Unicode character to a buffer.
writeChar :: Char -> Write

-- | <i>O(1)</i>. Serialize a Unicode character using the UTF-8 encoding.
fromChar :: Char -> Builder

-- | <i>O(n)</i>. Serialize a Unicode <a>String</a> using the UTF-8
--   encoding.
fromString :: String -> Builder

-- | <i>O(n)</i>. Serialize a value by <a>Show</a>ing it and UTF-8 encoding
--   the resulting <a>String</a>.
fromShow :: Show a => a -> Builder

-- | <i>O(n)</i>. Serialize a strict Unicode <a>Text</a> value using the
--   UTF-8 encoding.
fromText :: Text -> Builder

-- | <i>O(n)</i>. Serialize a lazy Unicode <a>Text</a> value using the
--   UTF-8 encoding.
fromLazyText :: Text -> Builder


-- | <a>Write</a>s and <a>Builder</a>s for strict and lazy bytestrings.
--   
--   We assume the following qualified imports in order to differentiate
--   between strict and lazy bytestrings in the code examples.
--   
--   <pre>
--   import qualified Data.ByteString      as S
--   import qualified Data.ByteString.Lazy as L
--   </pre>
module Blaze.ByteString.Builder.ByteString

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

-- | Smart serialization of a strict bytestring.
--   
--   <pre>
--   <a>fromByteString</a> = <a>fromByteStringWith</a> <a>defaultMaximalCopySize</a>
--   </pre>
--   
--   Use this function to serialize strict bytestrings. It guarantees an
--   average chunk size of 4kb, which has been shown to be a reasonable
--   size in benchmarks. Note that the check whether to copy or to insert
--   is (almost) free as the builder performance is mostly memory-bound.
--   
--   If you statically know that copying or inserting the strict bytestring
--   is always the best choice, then you can use the <a>copyByteString</a>
--   or <a>insertByteString</a> functions.
fromByteString :: ByteString -> Builder

-- | <tt>fromByteStringWith maximalCopySize bs</tt> serializes the strict
--   bytestring <tt>bs</tt> according to the following rules.
--   
--   <ul>
--   <li><i><tt>S.length bs &lt;= maximalCopySize</tt>:</i> <tt>bs</tt> is
--   copied to the output buffer.</li>
--   <li><i><tt>S.length bs &gt; maximalCopySize</tt>:</i> <tt>bs</tt> the
--   output buffer is flushed and <tt>bs</tt> is inserted directly as
--   separate chunk in the output stream.</li>
--   </ul>
--   
--   These rules guarantee that average chunk size in the output stream is
--   at least half the <tt>maximalCopySize</tt>.
fromByteStringWith :: Int -> ByteString -> Builder

-- | <tt>copyByteString bs</tt> serialize the strict bytestring <tt>bs</tt>
--   by copying it to the output buffer.
--   
--   Use this function to serialize strict bytestrings that are statically
--   known to be smallish (<tt>&lt;= 4kb</tt>).
copyByteString :: ByteString -> Builder

-- | <tt>insertByteString bs</tt> serializes the strict bytestring
--   <tt>bs</tt> by inserting it directly as a chunk of the output stream.
--   
--   Note that this implies flushing the output buffer; even if it contains
--   just a single byte. Hence, you should use this operation only for
--   large (<tt>&gt; 8kb</tt>) bytestrings, as otherwise the resulting
--   output stream may be too fragmented to be processed efficiently.
insertByteString :: ByteString -> Builder

-- | <i>O(n)</i>. Smart serialization of a lazy bytestring.
--   
--   <pre>
--   <a>fromLazyByteString</a> = <a>fromLazyByteStringWith</a> <a>defaultMaximalCopySize</a>
--   </pre>
--   
--   Use this function to serialize lazy bytestrings. It guarantees an
--   average chunk size of 4kb, which has been shown to be a reasonable
--   size in benchmarks. Note that the check whether to copy or to insert
--   is (almost) free as the builder performance is mostly memory-bound.
--   
--   If you statically know that copying or inserting <i>all</i> chunks of
--   the lazy bytestring is always the best choice, then you can use the
--   <a>copyLazyByteString</a> or <a>insertLazyByteString</a> functions.
fromLazyByteString :: ByteString -> Builder

-- | <i>O(n)</i>. Serialize a lazy bytestring chunk-wise according to the
--   same rules as in <a>fromByteStringWith</a>.
--   
--   Semantically, it holds that
--   
--   <pre>
--     fromLazyByteStringWith maxCopySize
--   = mconcat . map (fromByteStringWith maxCopySize) . L.toChunks
--   </pre>
--   
--   However, the left-hand-side is much more efficient, as it moves the
--   end-of-buffer pointer out of the inner loop and provides the compiler
--   with more strictness information.
fromLazyByteStringWith :: Int -> ByteString -> Builder

-- | <i>O(n)</i>. Serialize a lazy bytestring by copying <i>all</i> chunks
--   sequentially to the output buffer.
--   
--   See <a>copyByteString</a> for usage considerations.
copyLazyByteString :: ByteString -> Builder

-- | <i>O(n)</i>. Serialize a lazy bytestring by inserting <i>all</i> its
--   chunks directly into the output stream.
--   
--   See <a>insertByteString</a> for usage considerations.
--   
--   For library developers, see the <tt>ModifyChunks</tt> build signal, if
--   you need an <i>O(1)</i> lazy bytestring insert based on difference
--   lists.
insertLazyByteString :: ByteString -> Builder


-- | <a>Write</a>s and <a>Builder</a>s for serializing words.
--   
--   Note that for serializing a three tuple <tt>(x,y,z)</tt> of bytes (or
--   other word values) you should use the expression
--   
--   <pre>
--   fromWrite $ writeWord8 x `mappend` writeWord8 y `mappend` writeWord z
--   </pre>
--   
--   instead of
--   
--   <pre>
--   fromWord8 x `mappend` fromWord8 y `mappend` fromWord z
--   </pre>
--   
--   The first expression will result in a single atomic write of three
--   bytes, while the second expression will check for each byte, if there
--   is free space left in the output buffer. Coalescing these checks can
--   improve performance quite a bit, as long as you use it sensibly.
module Blaze.ByteString.Builder.Word

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

-- | Write a <a>Word16</a> in big endian format.
writeWord16be :: Word16 -> Write

-- | Write a <a>Word32</a> in big endian format.
writeWord32be :: Word32 -> Write

-- | Write a <a>Word64</a> in big endian format.
writeWord64be :: Word64 -> Write

-- | Write a <a>Word16</a> in little endian format.
writeWord16le :: Word16 -> Write

-- | Write a <a>Word32</a> in little endian format.
writeWord32le :: Word32 -> Write

-- | Write a <a>Word64</a> in little endian format.
writeWord64le :: Word64 -> Write

-- | Write a single native machine <a>Word</a>. The <a>Word</a> is written
--   in host order, host endian form, for the machine you're on. On a 64
--   bit machine the <a>Word</a> is an 8 byte value, on a 32 bit machine, 4
--   bytes. Values written this way are not portable to different endian or
--   word sized machines, without conversion.
writeWordhost :: Word -> Write

-- | Write a <a>Word16</a> in native host order and host endianness.
writeWord16host :: Word16 -> Write

-- | Write a <a>Word32</a> in native host order and host endianness.
writeWord32host :: Word32 -> Write

-- | Write a <a>Word64</a> in native host order and host endianness.
writeWord64host :: Word64 -> Write

-- | Serialize a single byte.
fromWord8 :: Word8 -> Builder

-- | Serialize a list of bytes.
fromWord8s :: [Word8] -> Builder

-- | Serialize a <a>Word16</a> in big endian format.
fromWord16be :: Word16 -> Builder

-- | Serialize a <a>Word32</a> in big endian format.
fromWord32be :: Word32 -> Builder

-- | Serialize a <a>Word64</a> in big endian format.
fromWord64be :: Word64 -> Builder

-- | Serialize a list of <a>Word32</a>s in big endian format.
fromWord32sbe :: [Word32] -> Builder

-- | Serialize a list of <a>Word16</a>s in big endian format.
fromWord16sbe :: [Word16] -> Builder

-- | Serialize a list of <a>Word64</a>s in big endian format.
fromWord64sbe :: [Word64] -> Builder

-- | Serialize a <a>Word16</a> in little endian format.
fromWord16le :: Word16 -> Builder

-- | Serialize a <a>Word32</a> in little endian format.
fromWord32le :: Word32 -> Builder

-- | Serialize a <a>Word64</a> in little endian format.
fromWord64le :: Word64 -> Builder

-- | Serialize a list of <a>Word16</a>s in little endian format.
fromWord16sle :: [Word16] -> Builder

-- | Serialize a list of <a>Word32</a>s in little endian format.
fromWord32sle :: [Word32] -> Builder

-- | Serialize a list of <a>Word64</a>s in little endian format.
fromWord64sle :: [Word64] -> Builder

-- | Serialize a single native machine <a>Word</a>. The <a>Word</a> is
--   serialized in host order, host endian form, for the machine you're on.
--   On a 64 bit machine the <a>Word</a> is an 8 byte value, on a 32 bit
--   machine, 4 bytes. Values written this way are not portable to
--   different endian or word sized machines, without conversion.
fromWordhost :: Word -> Builder

-- | Write a <a>Word16</a> in native host order and host endianness.
fromWord16host :: Word16 -> Builder

-- | Write a <a>Word32</a> in native host order and host endianness.
fromWord32host :: Word32 -> Builder

-- | Write a <a>Word64</a> in native host order and host endianness.
fromWord64host :: Word64 -> Builder

-- | Serialize a list of <a>Word</a>s. See <a>fromWordhost</a> for usage
--   considerations.
fromWordshost :: [Word] -> Builder

-- | Write a list of <a>Word16</a>s in native host order and host
--   endianness.
fromWord16shost :: [Word16] -> Builder

-- | Write a list of <a>Word32</a>s in native host order and host
--   endianness.
fromWord32shost :: [Word32] -> Builder

-- | Write a list of <a>Word64</a>s in native host order and host
--   endianness.
fromWord64shost :: [Word64] -> Builder


-- | <i></i>Note:<i></i> This package is intended for low-level use like
--   implementing protocols. If you need to <i></i>serialize<i></i> Unicode
--   characters use one of the UTF encodings (e.g.
--   'Blaze.ByteString.Builder.Char.UTF-8').
--   
--   <a>Write</a>s and <a>Builder</a>s for serializing the lower 8-bits of
--   characters.
--   
--   This corresponds to what the <tt>bytestring</tt> package offer in
--   <a>Char8</a>.
module Blaze.ByteString.Builder.Char8

-- | Write the lower 8-bits of a character to a buffer.
writeChar :: Char -> Write

-- | <i>O(1)</i>. Serialize the lower 8-bits of a character.
fromChar :: Char -> Builder

-- | <i>O(n)</i>. Serialize the lower 8-bits of all characters of a string
fromString :: String -> Builder

-- | <i>O(n)</i>. Serialize a value by <a>Show</a>ing it and serializing
--   the lower 8-bits of the resulting string.
fromShow :: Show a => a -> Builder

-- | <i>O(n)</i>. Serialize the lower 8-bits of all characters in the
--   strict text.
fromText :: Text -> Builder

-- | <i>O(n)</i>. Serialize the lower 8-bits of all characters in the lazy
--   text.
fromLazyText :: Text -> Builder


-- | Support for HTTP response encoding.
--   
--   TODO: Improve documentation.
module Blaze.ByteString.Builder.HTTP

-- | Transform a builder such that it uses chunked HTTP transfer encoding.
chunkedTransferEncoding :: Builder -> Builder

-- | The zero-length chunk '0\r\n\r\n' signaling the termination of the
--   data transfer.
chunkedTransferTerminator :: Builder


-- | <a>Write</a>s and <a>Builder</a>s for serializing integers.
--   
--   See <a>Blaze.ByteString.Builder.Word</a> for information about how to
--   best write several integers at once.
module Blaze.ByteString.Builder.Int

-- | Write a single signed byte.
writeInt8 :: Int8 -> Write

-- | Write an <a>Int16</a> in big endian format.
writeInt16be :: Int16 -> Write

-- | Write an <a>Int32</a> in big endian format.
writeInt32be :: Int32 -> Write

-- | Write an <a>Int64</a> in big endian format.
writeInt64be :: Int64 -> Write

-- | Write an <a>Int16</a> in little endian format.
writeInt16le :: Int16 -> Write

-- | Write an <a>Int32</a> in little endian format.
writeInt32le :: Int32 -> Write

-- | Write an <a>Int64</a> in little endian format.
writeInt64le :: Int64 -> Write

-- | Write a single native machine <a>Int</a>. The <a>Int</a> is written in
--   host order, host endian form, for the machine you're on. On a 64 bit
--   machine the <a>Int</a> is an 8 byte value, on a 32 bit machine, 4
--   bytes. Values written this way are not portable to different endian or
--   integer sized machines, without conversion.
writeInthost :: Int -> Write

-- | Write an <a>Int16</a> in native host order and host endianness.
writeInt16host :: Int16 -> Write

-- | Write an <a>Int32</a> in native host order and host endianness.
writeInt32host :: Int32 -> Write

-- | Write an <a>Int64</a> in native host order and host endianness.
writeInt64host :: Int64 -> Write

-- | Serialize a single byte.
fromInt8 :: Int8 -> Builder

-- | Serialize a list of bytes.
fromInt8s :: [Int8] -> Builder

-- | Serialize an <a>Int16</a> in big endian format.
fromInt16be :: Int16 -> Builder

-- | Serialize an <a>Int32</a> in big endian format.
fromInt32be :: Int32 -> Builder

-- | Serialize an <a>Int64</a> in big endian format.
fromInt64be :: Int64 -> Builder

-- | Serialize a list of <a>Int32</a>s in big endian format.
fromInt32sbe :: [Int32] -> Builder

-- | Serialize a list of <a>Int16</a>s in big endian format.
fromInt16sbe :: [Int16] -> Builder

-- | Serialize a list of <a>Int64</a>s in big endian format.
fromInt64sbe :: [Int64] -> Builder

-- | Serialize an <a>Int16</a> in little endian format.
fromInt16le :: Int16 -> Builder

-- | Serialize an <a>Int32</a> in little endian format.
fromInt32le :: Int32 -> Builder

-- | Serialize an <a>Int64</a> in little endian format.
fromInt64le :: Int64 -> Builder

-- | Serialize a list of <a>Int16</a>s in little endian format.
fromInt16sle :: [Int16] -> Builder

-- | Serialize a list of <a>Int32</a>s in little endian format.
fromInt32sle :: [Int32] -> Builder

-- | Serialize a list of <a>Int64</a>s in little endian format.
fromInt64sle :: [Int64] -> Builder

-- | Serialize a single native machine <a>Int</a>. The <a>Int</a> is
--   serialized in host order, host endian form, for the machine you're on.
--   On a 64 bit machine the <a>Int</a> is an 8 byte value, on a 32 bit
--   machine, 4 bytes. Values written this way are not portable to
--   different endian or integer sized machines, without conversion.
fromInthost :: Int -> Builder

-- | Write an <a>Int16</a> in native host order and host endianness.
fromInt16host :: Int16 -> Builder

-- | Write an <a>Int32</a> in native host order and host endianness.
fromInt32host :: Int32 -> Builder

-- | Write an <a>Int64</a> in native host order and host endianness.
fromInt64host :: Int64 -> Builder

-- | Serialize a list of <a>Int</a>s. See <a>fromInthost</a> for usage
--   considerations.
fromIntshost :: [Int] -> Builder

-- | Write a list of <a>Int16</a>s in native host order and host
--   endianness.
fromInt16shost :: [Int16] -> Builder

-- | Write a list of <a>Int32</a>s in native host order and host
--   endianness.
fromInt32shost :: [Int32] -> Builder

-- | Write a list of <a>Int64</a>s in native host order and host
--   endianness.
fromInt64shost :: [Int64] -> Builder


-- | <a>Blaze.ByteString.Builder</a> is the main module, which you should
--   import as a user of the <tt>blaze-builder</tt> library.
--   
--   <pre>
--   import Blaze.ByteString.Builder
--   </pre>
--   
--   It provides you with a type <a>Builder</a> that allows to efficiently
--   construct lazy bytestrings with a large average chunk size.
--   
--   Intuitively, a <a>Builder</a> denotes the construction of a part of a
--   lazy bytestring. Builders can either be created using one of the
--   primitive combinators in <a>Blaze.ByteString.Builder.Write</a> 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 <tt>mappend</tt> from the <tt>Monoid</tt> typeclass.
--   
--   Here is a small example that serializes a list of strings using the
--   UTF-8 encoding.
--   
--   <pre>
--   import <a>Blaze.ByteString.Builder.Char.Utf8</a>
--   </pre>
--   
--   <pre>
--   strings :: [String]
--   strings = replicate 10000 "Hello there!"
--   </pre>
--   
--   The function <tt><tt>fromString</tt></tt> creates a <a>Builder</a>
--   denoting the UTF-8 encoded argument. Hence, UTF-8 encoding and
--   concatenating all <tt>strings</tt> can be done follows.
--   
--   <pre>
--   concatenation :: Builder
--   concatenation = mconcat $ map fromString strings
--   </pre>
--   
--   The function <a>toLazyByteString</a> can be used to execute a
--   <a>Builder</a> and obtain the resulting lazy bytestring.
--   
--   <pre>
--   result :: L.ByteString
--   result = toLazyByteString concatenation
--   </pre>
--   
--   The <tt>result</tt> is a lazy bytestring containing 10000 repetitions
--   of the string <tt>"Hello there!"</tt> encoded using UTF-8. The
--   corresponding 120000 bytes are distributed among three chunks of 32kb
--   and a last chunk of 6kb.
--   
--   <i>A note on history.</i> This serialization library was inspired by
--   the <tt>Data.Binary.Builder</tt> module provided by the
--   <tt>binary</tt> package. It was originally developed with the specific
--   needs of the <tt>blaze-html</tt> package in mind. Since then it has
--   been restructured to serve as a drop-in replacement for
--   <tt>Data.Binary.Builder</tt>, which it improves upon both in speed as
--   well as expressivity.
module Blaze.ByteString.Builder
data Builder

-- | Output all data written in the current buffer and start a new chunk.
--   
--   The use of this function depends on how the resulting bytestrings are
--   consumed. <a>flush</a> is possibly not very useful in non-interactive
--   scenarios. However, it is kept for compatibility with the builder
--   provided by Data.Binary.Builder.
--   
--   When using <a>toLazyByteString</a> to extract a lazy <a>ByteString</a>
--   from a <a>Builder</a>, this means that a new chunk will be started in
--   the resulting lazy <a>ByteString</a>. The remaining part of the buffer
--   is spilled, if the reamining free space is smaller than the minimal
--   desired buffer size.
flush :: Builder

-- | Extract the lazy <a>ByteString</a> from the builder by running it with
--   default buffer sizes. Use this function, if you do not have any
--   special considerations with respect to buffer sizes.
--   
--   <pre>
--   <a>toLazyByteString</a> b = <a>toLazyByteStringWith</a> <a>defaultBufferSize</a> <a>defaultMinimalBufferSize</a> <a>defaultFirstBufferSize</a> b L.empty
--   </pre>
--   
--   Note that <tt><a>toLazyByteString</a></tt> is a <tt>Monoid</tt>
--   homomorphism.
--   
--   <pre>
--   toLazyByteString mempty          == mempty
--   toLazyByteString (x `mappend` y) == toLazyByteString x `mappend` toLazyByteString y
--   </pre>
--   
--   However, in the second equation, the left-hand-side is generally
--   faster to execute.
toLazyByteString :: Builder -> ByteString

-- | Run a <a>Builder</a> with the given buffer sizes.
--   
--   Use this function for integrating the <a>Builder</a> type with other
--   libraries that generate lazy bytestrings.
--   
--   Note that the builders should guarantee that on average the desired
--   chunk size is attained. Builders may decide to start a new buffer and
--   not completely fill the existing buffer, if this is faster. However,
--   they should not spill too much of the buffer, if they cannot
--   compensate for it.
--   
--   A call <tt>toLazyByteStringWith bufSize minBufSize firstBufSize</tt>
--   will generate a lazy bytestring according to the following strategy.
--   First, we allocate a buffer of size <tt>firstBufSize</tt> and start
--   filling it. If it overflows, we allocate a buffer of size
--   <tt>minBufSize</tt> and copy the first buffer to it in order to avoid
--   generating a too small chunk. Finally, every next buffer will be of
--   size <tt>bufSize</tt>. This, slow startup strategy is required to
--   achieve good speed for short (&lt;200 bytes) resulting bytestrings, as
--   for them the allocation cost is of a large buffer cannot be
--   compensated. Moreover, this strategy also allows us to avoid spilling
--   too much memory for short resulting bytestrings.
--   
--   Note that setting <tt>firstBufSize &gt;= minBufSize</tt> implies that
--   the first buffer is no longer copied but allocated and filled
--   directly. Hence, setting <tt>firstBufSize = bufSize</tt> means that
--   all chunks will use an underlying buffer of size <tt>bufSize</tt>.
--   This is recommended, if you know that you always output more than
--   <tt>minBufSize</tt> bytes.
toLazyByteStringWith :: Int -> Int -> Int -> Builder -> ByteString -> ByteString

-- | Run the builder to construct a strict bytestring containing the
--   sequence of bytes denoted by the builder. This is done by first
--   serializing to a lazy bytestring and then packing its chunks to a
--   appropriately sized strict bytestring.
--   
--   <pre>
--   toByteString = packChunks . toLazyByteString
--   </pre>
--   
--   Note that <tt><a>toByteString</a></tt> is a <tt>Monoid</tt>
--   homomorphism.
--   
--   <pre>
--   toByteString mempty          == mempty
--   toByteString (x `mappend` y) == toByteString x `mappend` toByteString y
--   </pre>
--   
--   However, in the second equation, the left-hand-side is generally
--   faster to execute.
toByteString :: Builder -> ByteString

-- | Run the builder with a <a>defaultBufferSize</a>d buffer and execute
--   the given <a>IO</a> action whenever the buffer is full or gets
--   flushed.
--   
--   <pre>
--   <a>toByteStringIO</a> = <a>toByteStringIOWith</a> <a>defaultBufferSize</a>
--   </pre>
--   
--   This is a <tt>Monoid</tt> homomorphism in the following sense.
--   
--   <pre>
--   toByteStringIO io mempty          == return ()
--   toByteStringIO io (x `mappend` y) == toByteStringIO io x &gt;&gt; toByteStringIO io y
--   </pre>
toByteStringIO :: (ByteString -> IO ()) -> Builder -> IO ()

-- | <tt>toByteStringIOWith bufSize io b</tt> runs the builder <tt>b</tt>
--   with a buffer of at least the size <tt>bufSize</tt> and executes the
--   <a>IO</a> action <tt>io</tt> whenever the buffer is full.
--   
--   Compared to <a>toLazyByteStringWith</a> this function requires less
--   allocation, as the output buffer is only allocated once at the start
--   of the serialization and whenever something bigger than the current
--   buffer size has to be copied into the buffer, which should happen very
--   seldomly for the default buffer size of 32kb. Hence, the pressure on
--   the garbage collector is reduced, which can be an advantage when
--   building long sequences of bytes.
toByteStringIOWith :: Int -> (ByteString -> IO ()) -> Builder -> IO ()

-- | A write of a bounded number of bytes.
--   
--   When defining a function <tt>write :: a -&gt; Write</tt> for some
--   <tt>a</tt>, then it is important to ensure that the bound on the
--   number of bytes written is data-independent. Formally,
--   
--   <pre>
--   forall x y. getBound (write x) = getBound (write y)
--   </pre>
--   
--   The idea is that this data-independent bound is specified such that
--   the compiler can optimize the check, if there are enough free bytes in
--   the buffer, to a single subtraction between the pointer to the next
--   free byte and the pointer to the end of the buffer with this constant
--   bound of the maximal number of bytes to be written.
data Write

-- | Create a builder that execute a single <a>Write</a>.
fromWrite :: Write -> Builder
fromWriteSingleton :: (a -> Write) -> (a -> Builder)

-- | Construct a <a>Builder</a> writing a list of data one element at a
--   time.
fromWriteList :: (a -> Write) -> [a] -> Builder

-- | Run a <a>Write</a> to produce a strict <a>ByteString</a>. This is
--   equivalent to <tt>(<a>toByteString</a> . <a>fromWrite</a>)</tt>, but
--   is more efficient because it uses just one appropriately-sized buffer.
writeToByteString :: Write -> ByteString

-- | Write a storable value.
writeStorable :: Storable a => a -> Write

-- | A builder that serializes a storable value. No alignment is done.
fromStorable :: Storable a => a -> Builder

-- | A builder that serializes a list of storable values by writing them
--   consecutively. No alignment is done. Parsing information needs to be
--   provided externally.
fromStorables :: Storable a => [a] -> Builder


-- | <a>Write</a>s and <a>Builder</a>s for serializing HTML escaped and
--   UTF-8 encoded characters.
--   
--   This module is used by both the 'blaze-html' and the 'hamlet' HTML
--   templating libraries. If the <a>Builder</a> from 'blaze-builder'
--   replaces the <a>Builder</a> implementation, this module will most
--   likely keep its place, as it provides a set of very specialized
--   functions.
module Blaze.ByteString.Builder.Html.Utf8

-- | Write a HTML escaped and UTF-8 encoded Unicode character to a bufffer.
writeHtmlEscapedChar :: Char -> Write

-- | <i>O(1).</i> Serialize a HTML escaped Unicode character using the
--   UTF-8 encoding.
fromHtmlEscapedChar :: Char -> Builder

-- | <i>O(n)</i>. Serialize a HTML escaped Unicode <a>String</a> using the
--   UTF-8 encoding.
fromHtmlEscapedString :: String -> Builder

-- | <i>O(n)</i>. Serialize a value by <a>Show</a>ing it and then, HTML
--   escaping and UTF-8 encoding the resulting <a>String</a>.
fromHtmlEscapedShow :: Show a => a -> Builder

-- | <i>O(n)</i>. Serialize a HTML escaped strict Unicode <a>Text</a> value
--   using the UTF-8 encoding.
fromHtmlEscapedText :: Text -> Builder

-- | <i>O(n)</i>. Serialize a HTML escaped Unicode <a>Text</a> using the
--   UTF-8 encoding.
fromHtmlEscapedLazyText :: Text -> Builder