Skip to content
Browse files

interface and documentation cleanup

  • Loading branch information...
1 parent ef0980d commit a7ef90fb26b63fb7aaa70303c309f99f3bcecab2 @meiersi committed Dec 5, 2010
Showing with 46 additions and 10 deletions.
  1. +38 −3 Blaze/ByteString/Builder/Enumerator.hs
  2. +7 −5 README.md
  3. +1 −2 blaze-builder-enumerator.cabal
View
41 Blaze/ByteString/Builder/Enumerator.hs
@@ -1,8 +1,9 @@
------------------------------------------------------------------------------
-- |
-- Module : Blaze.ByteString.Builder.Enumerator
+-- Copyright : (c) 2010 Simon Meier
-- License : BSD3
--- Copyright : 2010 Simon Meier <iridcode@gmail.com>
+--
-- Maintainer : Simon Meier <iridcode@gmail.com>
-- Stability : Experimental
-- Portability : Tested on GHC only
@@ -16,7 +17,36 @@
------------------------------------------------------------------------------
-module Blaze.ByteString.Builder.Enumerator where
+module Blaze.ByteString.Builder.Enumerator (
+
+ -- * Buffers
+ Buffer
+
+ -- ** Status information
+ , freeSize
+ , sliceSize
+ , bufferSize
+
+ -- ** Creation and modification
+ , allocBuffer
+ , reuseBuffer
+ , nextSlice
+
+ -- ** Conversion to bytestings
+ , unsafeFreezeBuffer
+ , unsafeFreezeNonEmptyBuffer
+
+ -- * Buffer allocation strategies
+ , BufferAllocStrategy
+ , allNewBuffersStrategy
+ , reuseBufferStrategy
+
+ -- * Enumeratees from builders to bytestrings
+ , builderToByteString
+ , unsafeBuilderToByteString
+ , builderToByteStringWith
+
+ ) where
import Prelude
import Foreign
@@ -146,7 +176,8 @@ unsafeBuilderToByteString = builderToByteStringWith . reuseBufferStrategy
-- buffer to use and how to compute a new buffer @nextBuf minSize buf@ with at
-- least size @minSize@ from a filled buffer @buf@. The double nesting of the
-- @IO@ monad helps to ensure that the reference to the filled buffer @buf@ is
--- lost as soon as possible.
+-- 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,
@@ -177,6 +208,10 @@ reuseBufferStrategy buf0 =
-- filled chunks as bytestrings to an inner iteratee.
--
-- INV: All bytestrings passed to the inner iteratee are non-empty.
+
+--
+-- based on the enumeratee code by Michael Snoyman <michael@snoyman.com>
+--
builderToByteStringWith :: MonadIO m
=> BufferAllocStrategy
-> Enumeratee Builder S.ByteString m a
View
12 README.md
@@ -1,12 +1,14 @@
Blaze Builder Enumerator
========================
-This package makes it easy to use the [`blaze-builder` package][1] together
-with the [`enumerator` package][2].
+This package integrates the builders from the [`blaze-builder` package][1]
+package with the [`enumerator` package][2]. It provides infrastructure and
+enumeratees for incrementally executing builders and pass the filled chunks to
+a bytestring iteratee.
-Where packages like [`attoparsec-enumerator`][3] make it easy to parse text
-into data types within enumerators this package handles the other direction,
-converting your data back into text.
+Where packages like [`attoparsec-enumerator`][3] make it easy to parse
+sequences of bytes into data types within enumerators, this package handles the
+other direction, converting your data back into sequences of bytes.
[1]: http://hackage.haskell.org/package/blaze-builder
[2]: http://hackage.haskell.org/package/enumerator
View
3 blaze-builder-enumerator.cabal
@@ -11,10 +11,9 @@ Description :
Author : Simon Meier <iridcode@gmail.com>
Maintainer : Simon Meier <iridcode@gmail.com>
-Copyright : Copyright (c) Simon Meier 2010
+Copyright : Copyright (c) 2010 Simon Meier
original package by Thomas Sutton <me@thomas-sutton.id.au>
- original enumeratee code by Michael Snoyman <michael@snoyman.com>
License : BSD3
License-file : LICENSE

0 comments on commit a7ef90f

Please sign in to comment.
Something went wrong with that request. Please try again.