diff options
author | Sam T <pxqr.sta@gmail.com> | 2013-08-26 07:05:34 +0400 |
---|---|---|
committer | Sam T <pxqr.sta@gmail.com> | 2013-08-26 07:05:34 +0400 |
commit | 29819e580b6501be46a7870c5b1de6761ec38e23 (patch) | |
tree | ce3002f9fffc3ea7559ded1c55fc2a88566f795b /src | |
parent | 007e669a651ef6b024432279fbd9ab3e4dd1d1c2 (diff) |
+ Document rest of module.
Diffstat (limited to 'src')
-rw-r--r-- | src/Data/BEncode.hs | 41 |
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 | |||
132 | import GHC.Generics | 132 | import GHC.Generics |
133 | #endif | 133 | #endif |
134 | 134 | ||
135 | -- | BEncode key-value dictionary. | ||
135 | type Dict = Map ByteString BEncode | 136 | type 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 | -- |
143 | data BEncode = BInteger {-# UNPACK #-} !Int64 | 143 | data 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. |
150 | type Result = Either String | 150 | type Result = Either String |
151 | 151 | ||
152 | -- | This class is used to define new datatypes that could be easily | ||
153 | -- serialized using bencode format. | ||
152 | class BEncodable a where | 154 | class 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. | ||
175 | decodingError :: String -> Result a | 181 | decodingError :: String -> Result a |
176 | decodingError s = Left ("fromBEncode: unable to decode " ++ s) | 182 | decodingError 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. | ||
590 | encode :: BEncode -> Lazy.ByteString | 598 | encode :: BEncode -> Lazy.ByteString |
591 | encode = B.toLazyByteString . builder | 599 | encode = B.toLazyByteString . builder |
592 | 600 | ||
601 | -- | Try to convert raw bytestring to bencoded value according to | ||
602 | -- specification. | ||
593 | decode :: ByteString -> Result BEncode | 603 | decode :: ByteString -> Result BEncode |
594 | decode = P.parseOnly parser | 604 | decode = P.parseOnly parser |
595 | 605 | ||
606 | -- | The same as 'decode' but returns any bencodable value. | ||
596 | decoded :: BEncodable a => ByteString -> Result a | 607 | decoded :: BEncodable a => ByteString -> Result a |
597 | decoded = decode >=> fromBEncode | 608 | decoded = decode >=> fromBEncode |
598 | 609 | ||
610 | -- | The same as 'encode' but takes any bencodable value. | ||
599 | encoded :: BEncodable a => a -> Lazy.ByteString | 611 | encoded :: BEncodable a => a -> Lazy.ByteString |
600 | encoded = encode . toBEncode | 612 | encoded = 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. | ||
606 | builder :: BEncode -> B.Builder | 619 | builder :: BEncode -> B.Builder |
607 | builder = go | 620 | builder = 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. | ||
628 | parser :: Parser BEncode | 642 | parser :: Parser BEncode |
629 | parser = valueP | 643 | parser = valueP |
630 | where | 644 | where |
@@ -672,12 +686,11 @@ parser = valueP | |||
672 | Pretty Printing | 686 | Pretty Printing |
673 | --------------------------------------------------------------------} | 687 | --------------------------------------------------------------------} |
674 | 688 | ||
675 | printPretty :: BEncode -> IO () | ||
676 | printPretty = print . ppBEncode | ||
677 | |||
678 | ppBS :: ByteString -> Doc | 689 | ppBS :: ByteString -> Doc |
679 | ppBS = text . map w2c . B.unpack | 690 | ppBS = text . map w2c . B.unpack |
680 | 691 | ||
692 | -- | Convert to easily readable JSON-like document. Typically used for | ||
693 | -- debugging purposes. | ||
681 | ppBEncode :: BEncode -> Doc | 694 | ppBEncode :: BEncode -> Doc |
682 | ppBEncode (BInteger i) = int $ fromIntegral i | 695 | ppBEncode (BInteger i) = int $ fromIntegral i |
683 | ppBEncode (BString s) = ppBS s | 696 | ppBEncode (BString s) = ppBS s |