-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A library for encoding and decoding of BEncode data. -- -- A library for encoding and decoding of BEncode data. -- -- -- -- @package bencoding @version 0.2.0.0 -- | 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: -- -- -- -- To serialize any other types we need to make conversion. To make -- conversion more convenient there is type class for it: -- BEncodable. 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. module Data.BEncode -- | BEncode 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. data BEncode BInteger :: {-# UNPACK #-} !Int64 -> BEncode BString :: !ByteString -> BEncode BList :: [BEncode] -> BEncode BDict :: Dict -> BEncode -- | BEncode key-value dictionary. type Dict = Map ByteString BEncode -- | Convert to easily readable JSON-like document. Typically used for -- debugging purposes. ppBEncode :: BEncode -> Doc -- | This class is used to define new datatypes that could be easily -- serialized using bencode format. -- -- By default BEncodable have a generic implementation; suppose -- the following datatype: -- -- 
--   data List a = Cons { _head  :: a
--                      , __tail :: (List a) }
--               | Nil
--                 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 BEncodable a => BEncodable (List a)
--
-- -- Example of derived toBEncode result: -- -- 
--   > toBEncode (Cons 123 $ Cons 1 Nil)
--   BDict (fromList [("head",BInteger 123),("tail",BList [])])
--
-- -- Note that '_' prefixes are omitted. class BEncodable a where toBEncode = gto . from fromBEncode x = to <$> gfrom x toBEncode :: BEncodable a => a -> BEncode fromBEncode :: BEncodable a => BEncode -> Result a -- | Result used in decoding operations. type Result = Either String -- | Convert bencoded value to raw bytestring according to the -- specification. encode :: BEncode -> ByteString -- | Try to convert raw bytestring to bencoded value according to -- specification. decode :: ByteString -> Result BEncode -- | The same as encode but takes any bencodable value. encoded :: BEncodable a => a -> ByteString -- | The same as decode but returns any bencodable value. decoded :: BEncodable a => ByteString -> Result a -- | 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 BEncodable 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 BEncodable FileInfo where
--     toBEncode FileInfo {..} = fromAssocs
--       [ "length" -->  fileLength
--       , "md5sum" -->? fileMD5sum
--       , "path"   -->  filePath
--       , "tags"   -->? fileTags
--       ]
--       ...
--
data Assoc -- | Make required key value pair. (-->) :: BEncodable a => ByteString -> a -> Assoc -- | Like (-->) but if the value is not present then the key do not -- appear in resulting bencoded dictionary. (-->?) :: BEncodable a => ByteString -> Maybe a -> Assoc -- | Build BEncode dictionary using key -> value description. fromAssocs :: [Assoc] -> BEncode -- | A faster version of fromAssocs. Should be used only when keys -- in builder list are sorted by ascending. fromAscAssocs :: [Assoc] -> BEncode -- | Typically used to throw an decoding error in fromBEncode; when BEncode -- value to match expected value. decodingError :: String -> Result 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 -- fromBEncode looks like: -- -- 
--   instance BEncodable FileInfo where
--     ...
--     fromBEncode (BDict d) =
--       FileInfo <$> d >--  "length"
--                <*> d >--? "md5sum"
--                <*> d >--  "path"
--                <*> d >--? "tags"
--     fromBEncode _ = decodingError "FileInfo"
--
-- -- The reqKey is used to extract required key — if lookup is -- failed then whole destructuring fail. reqKey :: BEncodable a => Dict -> ByteString -> Result a -- | Used to extract optional key — if lookup is failed returns -- Nothing. optKey :: BEncodable a => Dict -> ByteString -> Result (Maybe a) -- | Infix version of the reqKey. (>--) :: BEncodable a => Dict -> ByteString -> Result a -- | Infix version of the optKey. (>--?) :: BEncodable a => Dict -> ByteString -> Result (Maybe a) -- | Test if bencoded value is an integer. isInteger :: BEncode -> Bool -- | Test if bencoded value is a string, both raw and utf8 encoded. isString :: BEncode -> Bool -- | Test if bencoded value is a list. isList :: BEncode -> Bool -- | Test if bencoded value is a dictionary. isDict :: BEncode -> Bool -- | BEncode format encoder according to specification. builder :: BEncode -> Builder -- | BEncode format parser according to specification. parser :: Parser BEncode instance Show BEncode instance Read BEncode instance Eq BEncode instance Ord BEncode instance BEncodable Word instance BEncodable Word64 instance BEncodable Word32 instance BEncodable Word16 instance BEncodable Word8 instance BEncodable Version instance (BEncodable a, BEncodable b, BEncodable c, BEncodable d, BEncodable e) => BEncodable (a, b, c, d, e) instance (BEncodable a, BEncodable b, BEncodable c, BEncodable d) => BEncodable (a, b, c, d) instance (BEncodable a, BEncodable b, BEncodable c) => BEncodable (a, b, c) instance (BEncodable a, BEncodable b) => BEncodable (a, b) instance BEncodable () instance (Eq a, BEncodable a) => BEncodable (Set a) instance BEncodable a => BEncodable (Map ByteString a) instance BEncodable a => BEncodable [a] instance BEncodable Text instance BEncodable ByteString instance BEncodable Integer instance BEncodable Bool instance BEncodable Int instance BEncodable BEncode instance GBEncodable f e => GBEncodable (M1 D d f) e instance (Constructor c, GBEncodable f Dict, GBEncodable f [BEncode]) => GBEncodable (M1 C c f) BEncode instance GBEncodable f BEncode => GBEncodable (M1 S s f) [BEncode] instance (Selector s, GBEncodable f BEncode) => GBEncodable (M1 S s f) Dict instance (GBEncodable a e, GBEncodable b e) => GBEncodable (a :+: b) e instance (GBEncodable a Dict, GBEncodable b Dict) => GBEncodable (a :*: b) Dict instance (GBEncodable a [BEncode], GBEncodable b [BEncode]) => GBEncodable (a :*: b) [BEncode] instance (Eq e, Monoid e) => GBEncodable U1 e instance BEncodable f => GBEncodable (K1 R f) BEncode instance NFData BEncode