-
Notifications
You must be signed in to change notification settings - Fork 22
/
Builder.hs
204 lines (181 loc) · 6.95 KB
/
Builder.hs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
-----------------------------------------------------------------------------
-- |
-- 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." #-}