Copyright	(c) Dong Han 2017-2019 (c) Tao He 2018-2019
License	BSD
Maintainer	winterland1989@gmail.com
Stability	experimental
Portability	non-portable
Safe Haskell	None
Language	Haskell2010

Z.Data.Builder.Base

Contents

Builder type
Running a builder
Basic buiders
Boundary handling
Pritimive builders
More builders
Builder helpers

Description

A Builder records a buffer writing function, which can be mappend in O(1) via composition. In Z-Data a Builder are designed to deal with different AllocateStrategy, it affects how Builder react when writing across buffer boundaries:

When building a short strict Bytes with 'buildBytes/buildByteswith', we do a DoubleBuffer.
When building a large lazy [Bytes] with 'buildBytesList/buildBytesListwith', we do an InsertChunk.
When building and consuming are interlaced with 'buildAndRun/buildAndRunWith', we do an OneShotAction.

Most of the time using combinators from this module to build Builder s is enough, but in case of rolling something shining from the ground, keep an eye on correct AllocateStrategy handling.

Synopsis

data AllocateStrategy s
- = DoubleBuffer
- | InsertChunk !Int
- | OneShotAction (Bytes -> ST s ())
data Buffer s = Buffer !(MutablePrimArray s Word8) !Int
type BuildStep s = Buffer s -> ST s [Bytes]
newtype Builder a = Builder {
- runBuilder :: forall s. AllocateStrategy s -> (a -> BuildStep s) -> BuildStep s
}
append :: Builder a -> Builder b -> Builder b
buildBytes :: Builder a -> Bytes
buildBytesWith :: Int -> Builder a -> Bytes
buildBytesList :: Builder a -> [Bytes]
buildBytesListWith :: Int -> Int -> Builder a -> [Bytes]
buildAndRun :: (Bytes -> IO ()) -> Builder a -> IO ()
buildAndRunWith :: Int -> (Bytes -> IO ()) -> Builder a -> IO ()
bytes :: Bytes -> Builder ()
ensureN :: Int -> Builder ()
atMost :: Int -> (forall s. MutablePrimArray s Word8 -> Int -> ST s Int) -> Builder ()
writeN :: Int -> (forall s. MutablePrimArray s Word8 -> Int -> ST s ()) -> Builder ()
doubleBuffer :: Int -> BuildStep s -> BuildStep s
insertChunk :: Int -> Int -> BuildStep s -> BuildStep s
oneShotAction :: (Bytes -> ST s ()) -> Int -> BuildStep s -> BuildStep s
encodePrim :: forall a. Unaligned a => a -> Builder ()
encodePrimLE :: forall a. Unaligned (LE a) => a -> Builder ()
encodePrimBE :: forall a. Unaligned (BE a) => a -> Builder ()
stringModifiedUTF8 :: String -> Builder ()
charModifiedUTF8 :: Char -> Builder ()
stringUTF8 :: String -> Builder ()
charUTF8 :: Char -> Builder ()
string7 :: String -> Builder ()
char7 :: Char -> Builder ()
string8 :: String -> Builder ()
char8 :: Char -> Builder ()
text :: Text -> Builder ()
paren :: Builder () -> Builder ()
curly :: Builder () -> Builder ()
square :: Builder () -> Builder ()
angle :: Builder () -> Builder ()
quotes :: Builder () -> Builder ()
squotes :: Builder () -> Builder ()
colon :: Builder ()
comma :: Builder ()
intercalateVec :: Vec v a => Builder () -> (a -> Builder ()) -> v a -> Builder ()
intercalateList :: Builder () -> (a -> Builder ()) -> [a] -> Builder ()

Builder type

data AllocateStrategy s Source #

AllocateStrategy will decide how each BuildStep proceed when previous buffer is not enough.

Constructors

DoubleBuffer
InsertChunk !Int
OneShotAction (Bytes -> ST s ())

data Buffer s Source #

Helper type to help ghc unpack

Constructors

Buffer
Fields !(MutablePrimArray s Word8) the buffer content !Int writing offset

type BuildStep s = Buffer s -> ST s [Bytes] Source #

BuilderStep is a function that fill buffer under given conditions.

newtype Builder a Source #

Builder is a monad to help compose BuilderStep. With next BuilderStep continuation, we can do interesting things like perform some action, or interleave the build process.

Notes on IsString instance: Builder ()'s IsString instance use stringModifiedUTF8, which is different from stringUTF8 in that it DOES NOT PROVIDE UTF8 GUARANTEES! :

NUL will be written as xC0 x80.
xD800 ~ xDFFF will be encoded in three bytes as normal UTF-8 codepoints.

Constructors

Builder
Fields runBuilder :: forall s. AllocateStrategy s -> (a -> BuildStep s) -> BuildStep s

Instances

Monad Builder Source #
Instance details Defined in Z.Data.Builder.Base Methods (>>=) :: Builder a -> (a -> Builder b) -> Builder b # (>>) :: Builder a -> Builder b -> Builder b # return :: a -> Builder a # fail :: String -> Builder a #
Functor Builder Source #
Instance details Defined in Z.Data.Builder.Base Methods fmap :: (a -> b) -> Builder a -> Builder b # (<$) :: a -> Builder b -> Builder a #
Applicative Builder Source #
Instance details Defined in Z.Data.Builder.Base Methods pure :: a -> Builder a # (<>) :: Builder (a -> b) -> Builder a -> Builder b # liftA2 :: (a -> b -> c) -> Builder a -> Builder b -> Builder c # (>) :: Builder a -> Builder b -> Builder b # (<*) :: Builder a -> Builder b -> Builder a #
Show (Builder a) Source #
Instance details Defined in Z.Data.Builder.Base Methods showsPrec :: Int -> Builder a -> ShowS # show :: Builder a -> String # showList :: [Builder a] -> ShowS #
a ~ () => IsString (Builder a) Source #	This instance simple write literals' bytes into buffer, which is different from `stringUTF8` in that it DOES NOT PROVIDE UTF8 GUARANTEES! :
Instance details Defined in Z.Data.Builder.Base Methods fromString :: String -> Builder a #
Semigroup (Builder ()) Source #
Instance details Defined in Z.Data.Builder.Base Methods (<>) :: Builder () -> Builder () -> Builder () # sconcat :: NonEmpty (Builder ()) -> Builder () # stimes :: Integral b => b -> Builder () -> Builder () #
Monoid (Builder ()) Source #
Instance details Defined in Z.Data.Builder.Base Methods mempty :: Builder () # mappend :: Builder () -> Builder () -> Builder () # mconcat :: [Builder ()] -> Builder () #
Arbitrary (Builder ()) Source #
Instance details Defined in Z.Data.Builder.Base Methods arbitrary :: Gen (Builder ()) # shrink :: Builder () -> [Builder ()] #
CoArbitrary (Builder ()) Source #
Instance details Defined in Z.Data.Builder.Base Methods coarbitrary :: Builder () -> Gen b -> Gen b #

append :: Builder a -> Builder b -> Builder b Source #

Running a builder

buildBytes :: Builder a -> Bytes Source #

shortcut to buildBytesWith defaultInitSize.

buildBytesWith :: Int -> Builder a -> Bytes Source #

run Builder with DoubleBuffer strategy, which is suitable for building short bytes.

buildBytesList :: Builder a -> [Bytes] Source #

shortcut to buildBytesListWith defaultChunkSize.

buildBytesListWith :: Int -> Int -> Builder a -> [Bytes] Source #

run Builder with InsertChunk strategy, which is suitable for building lazy bytes chunks.

buildAndRun :: (Bytes -> IO ()) -> Builder a -> IO () Source #

shortcut to buildAndRunWith defaultChunkSize.

buildAndRunWith :: Int -> (Bytes -> IO ()) -> Builder a -> IO () Source #

run Builder with OneShotAction strategy, which is suitable for doing effects while building.

Basic buiders

bytes :: Bytes -> Builder () Source #

Write a Bytes.

ensureN :: Int -> Builder () Source #

Ensure that there are at least n many elements available.

atMost Source #

Arguments

:: Int	size bound
-> (forall s. MutablePrimArray s Word8 -> Int -> ST s Int)	the writer which pure a new offset for next write
-> Builder ()

writeN Source #

Arguments

:: Int	size bound
-> (forall s. MutablePrimArray s Word8 -> Int -> ST s ())	the writer which pure a new offset for next write
-> Builder ()

Boundary handling

doubleBuffer :: Int -> BuildStep s -> BuildStep s Source #

insertChunk :: Int -> Int -> BuildStep s -> BuildStep s Source #

oneShotAction :: (Bytes -> ST s ()) -> Int -> BuildStep s -> BuildStep s Source #

Pritimive builders

encodePrim :: forall a. Unaligned a => a -> Builder () Source #

write primitive types in host byte order.

encodePrimLE :: forall a. Unaligned (LE a) => a -> Builder () Source #

write primitive types with little endianess.

encodePrimBE :: forall a. Unaligned (BE a) => a -> Builder () Source #

write primitive types with big endianess.

More builders

stringModifiedUTF8 :: String -> Builder () Source #

Encode string with modified UTF-8 encoding, will be rewritten to a memcpy if possible.

charModifiedUTF8 :: Char -> Builder () Source #

Turn Char into Builder with Modified UTF8 encoding

'\NUL' is encoded as two bytes C0 80 , '\xD800' ~ '\xDFFF' is encoded as a three bytes normal UTF-8 codepoint.

stringUTF8 :: String -> Builder () Source #

Turn String into Builder with UTF8 encoding

Illegal codepoints will be written as replacementChars.

This is different from writing string literals builders via OverloadedStrings, because string literals do not provide UTF8 guarantees.

This function will be rewritten into a memcpy if possible, (running a fast UTF-8 validation at runtime first).

charUTF8 :: Char -> Builder () Source #

Turn Char into Builder with UTF8 encoding

Illegal codepoints will be written as replacementChars.

string7 :: String -> Builder () Source #

Turn String into Builder with ASCII7 encoding

Codepoints beyond '\x7F' will be chopped.

char7 :: Char -> Builder () Source #

Turn Char into Builder with ASCII7 encoding

Codepoints beyond '\x7F' will be chopped.

string8 :: String -> Builder () Source #

Turn String into Builder with ASCII8 encoding

Codepoints beyond '\xFF' will be chopped. Note, this encoding is NOT compatible with UTF8 encoding, i.e. bytes written by this builder may not be legal UTF8 encoding bytes.

char8 :: Char -> Builder () Source #

Turn Char into Builder with ASCII8 encoding

Codepoints beyond '\xFF' will be chopped. Note, this encoding is NOT compatible with UTF8 encoding, i.e. bytes written by this builder may not be legal UTF8 encoding bytes.

text :: Text -> Builder () Source #

Write UTF8 encoded Text using Builder.

Note, if you're trying to write string literals builders, please open OverloadedStrings and use Builders IsString instance, it will be rewritten into a memcpy.