Safe Haskell | None |
---|---|
Language | Haskell98 |
pipes
utilities for encoding and decoding values as byte streams
The tutorial at the bottom of this module illustrates how to use this library.
In this module, the following type synonym compatible with the lens
,
lens-family
and lens-family-core
libraries is used but not exported:
type Lens' a b = forall f . Functor
f => (b -> f b) -> (a -> f a)
- encode :: (Monad m, Binary a) => a -> Producer' ByteString m ()
- encodePut :: Monad m => Put -> Producer' ByteString m ()
- decode :: (Monad m, Binary a) => Parser ByteString m (Either DecodingError a)
- decoded :: (Monad m, Binary a) => Lens' (Producer ByteString m r) (Producer a m (Either (DecodingError, Producer ByteString m r) r))
- decodeL :: (Monad m, Binary a) => Parser ByteString m (Either DecodingError (ByteOffset, a))
- decodedL :: (Monad m, Binary a) => Lens' (Producer ByteString m r) (Producer (ByteOffset, a) m (Either (DecodingError, Producer ByteString m r) r))
- decodeGet :: Monad m => Get a -> Parser ByteString m (Either DecodingError a)
- decodeGetL :: Monad m => Get a -> Parser ByteString m (Either DecodingError (ByteOffset, a))
- data DecodingError = DecodingError {
- deConsumed :: !ByteOffset
- deMessage :: !String
- module Data.Binary
- module Data.Binary.Get
- module Data.Binary.Put
- module Data.ByteString
- module Pipes.Parse
Encoding
encode :: (Monad m, Binary a) => a -> Producer' ByteString m () Source #
Convert a value to a byte stream.
Keep in mind that a single encode value might be split into many ByteString
chunks, that is, the lenght of the obtained Producer
might be greater than
1.
Hint: You can easily turn this Producer'
into a Pipe
that encodes
Binary
instances as they flow downstream using:
for
cat
encode
:: (Monad
m,Binary
a) =>Pipe
aByteString
m r
Explicit Put
Decoding
decode :: (Monad m, Binary a) => Parser ByteString m (Either DecodingError a) Source #
Parse a value from a byte stream.
decoded :: (Monad m, Binary a) => Lens' (Producer ByteString m r) (Producer a m (Either (DecodingError, Producer ByteString m r) r)) Source #
Including lengths
decodeL :: (Monad m, Binary a) => Parser ByteString m (Either DecodingError (ByteOffset, a)) Source #
Like decode
, but also returns the length of input consumed in order to
to decode the value.
decodedL :: (Monad m, Binary a) => Lens' (Producer ByteString m r) (Producer (ByteOffset, a) m (Either (DecodingError, Producer ByteString m r) r)) Source #
Like decoded
, except this tags each decoded value with the length of
input consumed in order to decode it.
Explicit Get
decodeGet :: Monad m => Get a -> Parser ByteString m (Either DecodingError a) Source #
decodeGetL :: Monad m => Get a -> Parser ByteString m (Either DecodingError (ByteOffset, a)) Source #
Types
data DecodingError Source #
DecodingError | |
|
Exports
The following types are re-exported from this module for your convenience:
- From Data.Binary
Binary
- From Data.Binary.Put
Put
- From Data.Binary.Get
Get
,ByteOffset
- From Data.ByteString
ByteString
- From Pipes.Parse
Parser
module Data.Binary
module Data.Binary.Get
module Data.Binary.Put
module Data.ByteString
module Pipes.Parse
Tutorial
Use encode
to convert values to byte streams
-- example.hs import Pipes import qualified Pipes.Prelude as P import Pipes.Binary readInts :: Int -> Producer Int IO () readInts n = P.readLn >-> P.take n encodedValues :: Producer ByteString IO () encodedValues = do for (readInts 3) encode -- Encode 3 Ints read from user input encode 'C' -- Encode a 'Char' encode True -- Encode a 'Bool'
Use decode
to parse a single decoded value or decoded
to access a stream
of decoded values:
-- example.hs import Data.ByteString (ByteString) import Pipes.Parse import Prelude hiding (splitAt) -- We need to import 'zoom', which can be found in many packages and all work -- equally fine for our purposes. Read "Pipes.Parse.Tutorial" for details. -- -- * From the package @lens-family-core@: 'Lens.Family.State.Strict.zoom' -- * From the package @lens-family@: 'Lens.Family2.State.Strict.zoom' -- * From the package @lens@: 'Control.Lens.Zoom.zoom' import Lens.Family.State.Strict (zoom) decoder :: Parser ByteString IO () decoder = do xs <- zoom (decoded . splitAt 3) drawAll -- Decode up to three 'Int's lift $ print (xs :: [Int]) y <- decode -- Decode a single 'Char' lift $ print (y :: Either DecodingError Char) z <- zoom decoded draw -- Same as 'decode', but lift $ print (z :: Maybe Bool) -- with a 'Maybe' main = evalStateT decoder encodedValues
Here are some example inputs:
$ ./example 1<Enter> 2<Enter> 3<Enter> [1,2,3] Right 'C' Just True $ ./example <Ctrl-D> [] Right 'C' Just True