Conversions from Bencoded ByteStrings to Haskell values.

Introduction

Decoding is done using parsers. There are parsers for the four Bencode types:

• string decodes Bencode strings as ByteStrings
• integer decodes Bencode integers as Integers
• list decodes Bencode lists as Vectors
• dict decodes Bencode dictionaries as Maps with ByteString keys.

These can be used to build more complex parsers for arbitrary types.

data File = File
  { hash :: ByteString
  , size :: Integer
  , tags :: Vector Text
  } deriving Show

Assuming a File is encoded as a Bencode dictionary with the field names as keys and appropriate value types, a parser for File can be defined as

{-# LANGUAGE OverloadedStrings #-}
import qualified Data.Bencode.Decode as D

fileParser :: D.Parser File
fileParser =
  File <$> D.field "hash" D.string
       <*> D.field "size" D.integer
       <*> D.field "tags" (D.list D.text)

The parser can then be run on a ByteString with decode.

>>> D.decode fileParser "d4:hash4:xxxx4:sizei1024e4:tagsl4:work6:backupee"
Right (File {hash = "xxxx", size = 1024, tags = ["work","backup"]})

Of course, invalid Bencode or Bencode that does not satisfy our File parser will fail to decode.

>>> D.decode fileParser "d4:hash4:xxxx4:tagsl4:work6:backupee"
Left "KeyNotFound \"size\""

For more examples, see the "Recipes" section at the end of this page.

Recipes for some common and uncommon usages.

The following preface is assumed.

{-# LANGUAGE OverloadedStrings #-}
import Data.ByteString (ByteString)
import Data.Text (Text)
import qualified Data.Bencode.Decode as D

Decode an optional field

import Control.Applicative (optional)

data File = File { name :: Text, size :: Maybe Int } deriving Show

fileParser :: D.Parser File
fileParser =
  File
    <$> D.field "name" D.text
    <*> optional (D.field "size" D.int)

>>> D.decode fileParser "d4:name9:hello.txt4:sizei16ee"
Right (File {name = "hello.txt", size = Just 16})
>>> D.decode fileParser "d4:name9:hello.txte"
Right (File {name = "hello.txt", size = Nothing})

Decode an enum

import Control.Applicative ((<|>))

data Color = Red | Green | Blue deriving Show

colorParser :: D.Parser Color
colorParser =
      Red   <$ D.stringEq "red"
  <|> Green <$ D.stringEq "green"
  <|> Blue  <$ D.stringEq "blue"
  <|> D.fail "unknown color"

>>> D.decode colorParser "5:green"
Right Green
>>> D.decode colorParser "5:black"
Left "Fail: unknown color"

Decode differently based on dict contents

import Control.Applicative ((<|>))

data Response = Response
  { id_    :: Int
  , result :: Either Text ByteString
  } deriving Show

responseParser :: D.Parser Response
responseParser = do
  id_ <- D.field "id" D.int
  success <- D.field "status" $
        False <$ D.stringEq "failure"
    <|> True  <$ D.stringEq "success"
    <|> D.fail "unknown status"
  Response id_
    <$> if success
        then Right <$> D.field "data" D.string
        else Left  <$> D.field "reason" D.text

>>> D.decode responseParser "d2:idi42e6:reason12:unauthorized6:status7:failuree"
Right (Response {id_ = 42, result = Left "unauthorized"})
>>> D.decode responseParser "d4:data4:00002:idi42e6:status7:successe"
Right (Response {id_ = 42, result = Right "0000"})

Decode nested dicts

data File = File { name :: Text, size :: Int } deriving Show

fileParser :: D.Parser File
fileParser =
  File
    <$> D.field "name" D.text
    <*> D.field "metadata" (D.field "info" (D.field "size" D.int))

>>> D.decode fileParser "d8:metadatad4:infod4:sizei32eee4:name9:hello.txte"
Right (File {name = "hello.txt", size = 32})