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.

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.

Encode a value using bencode format to a lazy ByteString.

Decode a value from a strict ByteString using bencode format.

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"

Make required key value pair.

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

Cons a key/value pair.

Used to specify end of dictionary. See Assoc.

Make a bencode value from dictionary description.

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"

Result used in decoding operations.

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

Run a Get monad. See Get for usage.

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

Get lexicographical successor of the current key/value pair.

Extract required value from the given key.

Extract optional value from the given key.

Reconstruct a bencodable value from bencode value.

Match key with value.

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

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

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

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