Data.BEncode

This module provides convinient and fast way to serialize, deserealize and construct/destructure Bencoded values with optional fields.

It supports four different types of values:

• byte strings — represented as ByteString;
• integers — represented as Integer;
• lists - represented as ordinary lists;
• dictionaries — represented as BDictMap;

To serialize any other types we need to make conversion. To make conversion more convenient there is type class for it: BEncode. Any textual strings are considered as UTF8 encoded Text.

The complete Augmented BNF syntax for bencoding format is:

<BE>    ::= <DICT> | <LIST> | <INT> | <STR>

<DICT>  ::= "d" 1 * (<STR> <BE>) "e"
<LIST>  ::= "l" 1 * <BE>         "e"
<INT>   ::= "i"     <SNUM>       "e"
<STR>   ::= <NUM> ":" n * <CHAR>; where n equals the <NUM>

<SNUM>  ::= "-" <NUM> / <NUM>
<NUM>   ::= 1 * <DIGIT>
<CHAR>  ::= %
<DIGIT> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

This module is considered to be imported qualified, for example:

import Data.BEncode as BE

Documentation

data BValue

BValue is straightforward ADT for b-encoded values. Please note that since dictionaries are sorted, in most cases we can compare BEncoded values without serialization and vice versa. Lists is not required to be sorted through.

Constructors

BInteger !BInteger

bencode integers;

BString !BString

bencode strings;

BList BList

list of bencode values;

BDict BDict

bencode key-value dictionary.

Instances

Eq BValue

Defined in Data.BEncode.Types

Methods

(==) :: BValue -> BValue -> Bool

(/=) :: BValue -> BValue -> Bool

Ord BValue

Defined in Data.BEncode.Types

Methods

compare :: BValue -> BValue -> Ordering

(<) :: BValue -> BValue -> Bool

(<=) :: BValue -> BValue -> Bool

(>) :: BValue -> BValue -> Bool

(>=) :: BValue -> BValue -> Bool

max :: BValue -> BValue -> BValue

min :: BValue -> BValue -> BValue

Read BValue

Defined in Data.BEncode.Types

Methods

readsPrec :: Int -> ReadS BValue

readList :: ReadS [BValue]

readPrec :: ReadPrec BValue

readListPrec :: ReadPrec [BValue]

Show BValue

Defined in Data.BEncode.Types

Methods

showsPrec :: Int -> BValue -> ShowS

show :: BValue -> String

showList :: [BValue] -> ShowS

Generic BValue

Defined in Data.BEncode.Types

Associated Types

type Rep BValue :: Type -> Type

Methods

from :: BValue -> Rep BValue x

to :: Rep BValue x -> BValue

NFData BValue

Defined in Data.BEncode.Types

Methods

rnf :: BValue -> ()

BEncode BValue

Defined in Data.BEncode

Methods

toBEncode :: BValue -> BValue

fromBEncode :: BValue -> Result BValue

BEncode BDict

Defined in Data.BEncode

Methods

toBEncode :: BDict -> BValue

fromBEncode :: BValue -> Result BDict

type Rep BValue

Defined in Data.BEncode.Types

type Rep BValue = D1 (MetaData "BValue" "Data.BEncode.Types" "bencoding-0.4.5.0-JFndeJnXcPJGKg9gavbH9H" False) ((C1 (MetaCons "BInteger" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 BInteger)) :+: C1 (MetaCons "BString" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness SourceStrict DecidedStrict) (Rec0 BString))) :+: (C1 (MetaCons "BList" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 BList)) :+: C1 (MetaCons "BDict" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 BDict))))

class BEncode a where

This class is used to define new datatypes that could be easily serialized using bencode format.

By default BEncode have a generic implementation; suppose the following datatype:

data List a = C { _head  :: a
                , __tail :: List a }
            | N
              deriving Generic

If we don't need to obey any particular specification or standard, the default instance could be derived automatically from the Generic instance:

instance BEncode a => BEncode (List a)

Example of derived toBEncode result:

> toBEncode (C 123 $ C 1 N)
BDict (fromList [("head",BInteger 123),("tail",BList [])])

Note that prefixed underscore characters are omitted since they are usually used for lens.

Minimal complete definition

Nothing

Methods

toBEncode :: a -> BValue

See an example of implementation here Assoc

toBEncode :: Generic a => GBEncodable (Rep a) BValue => a -> BValue

See an example of implementation here Assoc

fromBEncode :: BValue -> Result a

See an example of implementation here Get.

fromBEncode :: Generic a => GBEncodable (Rep a) BValue => BValue -> Result a

See an example of implementation here Get.

Instances

BEncode Bool

Defined in Data.BEncode

Methods

toBEncode :: Bool -> BValue

fromBEncode :: BValue -> Result Bool

BEncode Int

Defined in Data.BEncode

Methods

toBEncode :: Int -> BValue

fromBEncode :: BValue -> Result Int

BEncode Int8

Defined in Data.BEncode

Methods

toBEncode :: Int8 -> BValue

fromBEncode :: BValue -> Result Int8

BEncode Int16

Defined in Data.BEncode

Methods

toBEncode :: Int16 -> BValue

fromBEncode :: BValue -> Result Int16

BEncode Int32

Defined in Data.BEncode

Methods

toBEncode :: Int32 -> BValue

fromBEncode :: BValue -> Result Int32

BEncode Int64

Defined in Data.BEncode

Methods

toBEncode :: Int64 -> BValue

fromBEncode :: BValue -> Result Int64

BEncode Word

Defined in Data.BEncode

Methods

toBEncode :: Word -> BValue

fromBEncode :: BValue -> Result Word

BEncode Word8

Defined in Data.BEncode

Methods

toBEncode :: Word8 -> BValue

fromBEncode :: BValue -> Result Word8

BEncode Word16

Defined in Data.BEncode

Methods

toBEncode :: Word16 -> BValue

fromBEncode :: BValue -> Result Word16

BEncode Word32

Defined in Data.BEncode

Methods

toBEncode :: Word32 -> BValue

fromBEncode :: BValue -> Result Word32

BEncode Word64

Defined in Data.BEncode

Methods

toBEncode :: Word64 -> BValue

fromBEncode :: BValue -> Result Word64

BEncode ()

Defined in Data.BEncode

Methods

toBEncode :: () -> BValue

fromBEncode :: BValue -> Result ()

BEncode Text

Defined in Data.BEncode

Methods

toBEncode :: Text -> BValue

fromBEncode :: BValue -> Result Text

BEncode Version

Defined in Data.BEncode

Methods

toBEncode :: Version -> BValue

fromBEncode :: BValue -> Result Version

BEncode BValue

Defined in Data.BEncode

Methods

toBEncode :: BValue -> BValue

fromBEncode :: BValue -> Result BValue

BEncode BDict

Defined in Data.BEncode

Methods

toBEncode :: BDict -> BValue

fromBEncode :: BValue -> Result BDict

BEncode BString

Defined in Data.BEncode

Methods

toBEncode :: BString -> BValue

fromBEncode :: BValue -> Result BString

BEncode BInteger

Defined in Data.BEncode

Methods

toBEncode :: BInteger -> BValue

fromBEncode :: BValue -> Result BInteger

BEncode a => BEncode [a]

Defined in Data.BEncode

Methods

toBEncode :: [a] -> BValue

fromBEncode :: BValue -> Result [a]

(BEncode a, BEncode b) => BEncode (a, b)

Defined in Data.BEncode

Methods

toBEncode :: (a, b) -> BValue

fromBEncode :: BValue -> Result (a, b)

(BEncode a, BEncode b, BEncode c) => BEncode (a, b, c)

Defined in Data.BEncode

Methods

toBEncode :: (a, b, c) -> BValue

fromBEncode :: BValue -> Result (a, b, c)

(BEncode a, BEncode b, BEncode c, BEncode d) => BEncode (a, b, c, d)

Defined in Data.BEncode

Methods

toBEncode :: (a, b, c, d) -> BValue

fromBEncode :: BValue -> Result (a, b, c, d)

(BEncode a, BEncode b, BEncode c, BEncode d, BEncode e) => BEncode (a, b, c, d, e)

Defined in Data.BEncode

Methods

toBEncode :: (a, b, c, d, e) -> BValue

fromBEncode :: BValue -> Result (a, b, c, d, e)

encode :: BEncode a => a -> ByteString

Encode a value using bencode format to a lazy ByteString.

decode :: BEncode a => ByteString -> Result a

Decode a value from a strict ByteString using bencode format.

Helpers

Building

data Assoc

Assoc used to easily build dictionaries with required and optional keys. Suppose we have we following datatype we want to serialize:

  data FileInfo = FileInfo
    { fileLength :: Integer
    , fileMD5sum :: Maybe ByteString
    , filePath   :: [ByteString]
    , fileTags   :: Maybe [Text]
    } deriving (Show, Read, Eq)
 

We need to make instance BEncode FileInfo, though we don't want to check the both Maybes manually. The more declarative and convenient way to define the toBEncode method is to use dictionary builders:

  instance BEncode FileInfo where
    toBEncode FileInfo {..} = toDict $
         "length" .=! fileLength
      .: "md5sum" .=? fileMD5sum
      .: "path"   .=! filePath
      .: "tags"   .=? fileTags
      .: endDict
 

NOTE: the list of pairs MUST be sorted lexicographically by keys, like so:

"length" < "md5sum" < "path" < "tags"

(.=!) :: BEncode a => BKey -> a -> Assoc infix 6

Make required key value pair.

(.=?) :: BEncode a => BKey -> Maybe a -> Assoc infix 6

Like the (.=!) operator but if the value is not present then the key do not appear in resulting bencode dictionary.

(.:) :: Assoc -> BDict -> BDict infixr 5

Cons a key/value pair.

endDict :: BDict

Used to specify end of dictionary. See Assoc.

toDict :: BDict -> BValue

Make a bencode value from dictionary description.

Extraction

data Get a

Dictionary extractor are similar to dictionary builders, but play the opposite role: they are used to define fromBEncode method in declarative style. Using the same FileInfo datatype the fromBEncode function instance looks like:

  instance BEncode FileInfo where
    fromBEncode = fromDict $ do
      FileInfo <$>! "length"
               <*>? "md5sum"
               <*>! "path"
               <*>? "tags"
 

The reqKey is used to extract required key — if lookup is failed then whole destructuring fail.

NOTE: the actions MUST be sorted lexicographically by keys, like so:

"length" < "md5sum" < "path" < "tags"

Instances

Monad Get

fail is catchable from pure code.

Defined in Data.BEncode

Methods

(>>=) :: Get a -> (a -> Get b) -> Get b

(>>) :: Get a -> Get b -> Get b

return :: a -> Get a

fail :: String -> Get a

Functor Get

Defined in Data.BEncode

Methods

fmap :: (a -> b) -> Get a -> Get b

(<$) :: a -> Get b -> Get a

Applicative Get

Defined in Data.BEncode

Methods

pure :: a -> Get a

(<*>) :: Get (a -> b) -> Get a -> Get b

liftA2 :: (a -> b -> c) -> Get a -> Get b -> Get c

(*>) :: Get a -> Get b -> Get b

(<*) :: Get a -> Get b -> Get a

Alternative Get

Defined in Data.BEncode

Methods

empty :: Get a

(<|>) :: Get a -> Get a -> Get a

some :: Get a -> Get [a]

many :: Get a -> Get [a]

type Result = Either String

Result used in decoding operations.

decodingError :: String -> Result a

Typically used to throw an decoding error in fromBEncode; when BEncode value to match expected value.

fromDict :: forall a. Typeable a => Get a -> BValue -> Result a

Run a Get monad. See Get for usage.

lookAhead :: Get a -> Get a

Run action, but return without consuming and key/value pair. Fails if the action fails.

next :: Get BValue

Get lexicographical successor of the current key/value pair.

req :: BKey -> Get BValue

Extract required value from the given key.

opt :: BKey -> Get (Maybe BValue)

Extract optional value from the given key.

field :: BEncode a => Get BValue -> Get a

Reconstruct a bencodable value from bencode value.

match :: BKey -> BValue -> Get ()

Match key with value.

(<$>!) :: BEncode a => (a -> b) -> BKey -> Get b infixl 4

Shorthand for: f <$> field (req k).

(<$>?) :: BEncode a => (Maybe a -> b) -> BKey -> Get b infixl 4

Shorthand for: f <$> optional (field (req k)).

(<*>!) :: BEncode a => Get (a -> b) -> BKey -> Get b infixl 4

Shorthand for: f <*> field (req k).

(<*>?) :: BEncode a => Get (Maybe a -> b) -> BKey -> Get b infixl 4

Shorthand for: f <*> optional (field (req k)).