summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorSam T <pxqr.sta@gmail.com>2013-08-26 07:05:34 +0400
committerSam T <pxqr.sta@gmail.com>2013-08-26 07:05:34 +0400
commit29819e580b6501be46a7870c5b1de6761ec38e23 (patch)
treece3002f9fffc3ea7559ded1c55fc2a88566f795b /src
parent007e669a651ef6b024432279fbd9ab3e4dd1d1c2 (diff)
+ Document rest of module.
Diffstat (limited to 'src')
-rw-r--r--src/Data/BEncode.hs41
1 files changed, 27 insertions, 14 deletions
diff --git a/src/Data/BEncode.hs b/src/Data/BEncode.hs
index 9896114..62188ff 100644
--- a/src/Data/BEncode.hs
+++ b/src/Data/BEncode.hs
@@ -62,11 +62,18 @@ module Data.BEncode
62 ( -- * Datatype 62 ( -- * Datatype
63 BEncode(..) 63 BEncode(..)
64 , Dict 64 , Dict
65 , ppBEncode
65 66
66 -- * Construction && Destructuring 67 -- * Conversion
67 , BEncodable (..) 68 , BEncodable (..)
68 , Result 69 , Result
69 70
71 -- * Serialization
72 , encode
73 , decode
74 , encoded
75 , decoded
76
70 -- ** Dictionaries 77 -- ** Dictionaries
71 -- *** Building 78 -- *** Building
72 , Assoc 79 , Assoc
@@ -76,17 +83,12 @@ module Data.BEncode
76 , fromAscAssocs 83 , fromAscAssocs
77 84
78 -- *** Extraction 85 -- *** Extraction
86 , decodingError
79 , reqKey 87 , reqKey
80 , optKey 88 , optKey
81 , (>--) 89 , (>--)
82 , (>--?) 90 , (>--?)
83 91
84 -- * Serialization
85 , encode
86 , decode
87 , encoded
88 , decoded
89
90 -- * Predicates 92 -- * Predicates
91 , isInteger 93 , isInteger
92 , isString 94 , isString
@@ -96,8 +98,6 @@ module Data.BEncode
96 -- * Extra 98 -- * Extra
97 , builder 99 , builder
98 , parser 100 , parser
99 , decodingError
100 , printPretty
101 ) where 101 ) where
102 102
103 103
@@ -132,13 +132,13 @@ import qualified Text.ParserCombinators.ReadP as ReadP
132import GHC.Generics 132import GHC.Generics
133#endif 133#endif
134 134
135-- | BEncode key-value dictionary.
135type Dict = Map ByteString BEncode 136type Dict = Map ByteString BEncode
136 137
137-- | 'BEncode' is straightforward ADT for b-encoded values. Please 138-- | 'BEncode' is straightforward ADT for b-encoded values. Please
138-- note that since dictionaries are sorted, in most cases we can 139-- note that since dictionaries are sorted, in most cases we can
139-- compare BEncoded values without serialization and vice versa. 140-- compare BEncoded values without serialization and vice versa.
140-- Lists is not required to be sorted through. Also note that 141-- Lists is not required to be sorted through.
141-- 'BEncode' have JSON-like instance for 'Pretty'.
142-- 142--
143data BEncode = BInteger {-# UNPACK #-} !Int64 143data BEncode = BInteger {-# UNPACK #-} !Int64
144 | BString !ByteString 144 | BString !ByteString
@@ -149,7 +149,10 @@ data BEncode = BInteger {-# UNPACK #-} !Int64
149-- | Result used in decoding operations. 149-- | Result used in decoding operations.
150type Result = Either String 150type Result = Either String
151 151
152-- | This class is used to define new datatypes that could be easily
153-- serialized using bencode format.
152class BEncodable a where 154class BEncodable a where
155 -- | See an example of implementation here 'Assoc'
153 toBEncode :: a -> BEncode 156 toBEncode :: a -> BEncode
154 157
155#if __GLASGOW_HASKELL__ >= 702 158#if __GLASGOW_HASKELL__ >= 702
@@ -161,6 +164,7 @@ class BEncodable a where
161 toBEncode = gto . from 164 toBEncode = gto . from
162#endif 165#endif
163 166
167 -- | See an example of implementation here 'reqKey'.
164 fromBEncode :: BEncode -> Result a 168 fromBEncode :: BEncode -> Result a
165 169
166#if __GLASGOW_HASKELL__ >= 702 170#if __GLASGOW_HASKELL__ >= 702
@@ -172,6 +176,8 @@ class BEncodable a where
172 fromBEncode x = to <$> gfrom x 176 fromBEncode x = to <$> gfrom x
173#endif 177#endif
174 178
179-- | Typically used to throw an decoding error in fromBEncode; when
180-- BEncode value to match expected value.
175decodingError :: String -> Result a 181decodingError :: String -> Result a
176decodingError s = Left ("fromBEncode: unable to decode " ++ s) 182decodingError s = Left ("fromBEncode: unable to decode " ++ s)
177{-# INLINE decodingError #-} 183{-# INLINE decodingError #-}
@@ -587,15 +593,21 @@ isDict _ = False
587 Encoding 593 Encoding
588--------------------------------------------------------------------} 594--------------------------------------------------------------------}
589 595
596-- | Convert bencoded value to raw bytestring according to the
597-- specification.
590encode :: BEncode -> Lazy.ByteString 598encode :: BEncode -> Lazy.ByteString
591encode = B.toLazyByteString . builder 599encode = B.toLazyByteString . builder
592 600
601-- | Try to convert raw bytestring to bencoded value according to
602-- specification.
593decode :: ByteString -> Result BEncode 603decode :: ByteString -> Result BEncode
594decode = P.parseOnly parser 604decode = P.parseOnly parser
595 605
606-- | The same as 'decode' but returns any bencodable value.
596decoded :: BEncodable a => ByteString -> Result a 607decoded :: BEncodable a => ByteString -> Result a
597decoded = decode >=> fromBEncode 608decoded = decode >=> fromBEncode
598 609
610-- | The same as 'encode' but takes any bencodable value.
599encoded :: BEncodable a => a -> Lazy.ByteString 611encoded :: BEncodable a => a -> Lazy.ByteString
600encoded = encode . toBEncode 612encoded = encode . toBEncode
601 613
@@ -603,6 +615,7 @@ encoded = encode . toBEncode
603 Internals 615 Internals
604--------------------------------------------------------------------} 616--------------------------------------------------------------------}
605 617
618-- | BEncode format encoder according to specification.
606builder :: BEncode -> B.Builder 619builder :: BEncode -> B.Builder
607builder = go 620builder = go
608 where 621 where
@@ -625,6 +638,7 @@ builder = go
625 {-# INLINE buildString #-} 638 {-# INLINE buildString #-}
626 639
627-- TODO try to replace peekChar with something else 640-- TODO try to replace peekChar with something else
641-- | BEncode format parser according to specification.
628parser :: Parser BEncode 642parser :: Parser BEncode
629parser = valueP 643parser = valueP
630 where 644 where
@@ -672,12 +686,11 @@ parser = valueP
672 Pretty Printing 686 Pretty Printing
673--------------------------------------------------------------------} 687--------------------------------------------------------------------}
674 688
675printPretty :: BEncode -> IO ()
676printPretty = print . ppBEncode
677
678ppBS :: ByteString -> Doc 689ppBS :: ByteString -> Doc
679ppBS = text . map w2c . B.unpack 690ppBS = text . map w2c . B.unpack
680 691
692-- | Convert to easily readable JSON-like document. Typically used for
693-- debugging purposes.
681ppBEncode :: BEncode -> Doc 694ppBEncode :: BEncode -> Doc
682ppBEncode (BInteger i) = int $ fromIntegral i 695ppBEncode (BInteger i) = int $ fromIntegral i
683ppBEncode (BString s) = ppBS s 696ppBEncode (BString s) = ppBS s