-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A library for encoding and decoding of BEncode data.
--   
--   A library for fast and easy encoding and decoding of BEncode data.
@package bencoding
@version 0.4.4.0


-- | This module defines a simple key/value list ordered by keys which both
--   faster and more suitable for bencode dictionaries than just [(k,v)].
module Data.BEncode.BDict
type BKey = ByteString

-- | BDictMap is an ascending list of key/value pairs sorted by keys.
data BDictMap a
Cons :: !BKey -> a -> !(BDictMap a) -> BDictMap a
Nil :: BDictMap a

-- | <i>O(1)</i>. The empty dicionary.
empty :: BDictMap a

-- | <i>O(1)</i>. Dictionary of one key-value pair.
singleton :: BKey -> a -> BDictMap a

-- | <i>O(1)</i>. Is the dictionary empty?
null :: BDictMap a -> Bool

-- | <i>O(n)</i>. Is the key a member of the dictionary?
member :: BKey -> BDictMap a -> Bool

-- | <i>O(n)</i>. Lookup the value at a key in the dictionary.
lookup :: BKey -> BDictMap a -> Maybe a

-- | <i>O(n + m)</i>. Merge two dictionaries by taking pair from both given
--   dictionaries. Dublicated keys are <i>not</i> filtered.
union :: BDictMap a -> BDictMap a -> BDictMap a

-- | <i>O(n).</i> Map a function over all values in the dictionary.
map :: (a -> b) -> BDictMap a -> BDictMap b

-- | <i>O(n).</i> Map a function over all keys/value pairs in the
--   dictionary.
mapWithKey :: (BKey -> a -> b) -> BDictMap a -> BDictMap b

-- | <i>O(n)</i>. Map each key/value pair to a monoid and fold resulting
--   sequnce using <a>mappend</a>.
foldMapWithKey :: Monoid m => (BKey -> a -> m) -> BDictMap a -> m

-- | <i>O(n)</i>. Map each key/value pair to a monoid and fold resulting
--   sequnce using <a>mappend</a>.

-- | <i>Deprecated: Use foldMapWithKey instead</i>
bifoldMap :: Monoid m => (BKey -> a -> m) -> BDictMap a -> m

-- | <i>O(n)</i>. Build a dictionary from a list of key/value pairs where
--   the keys are in ascending order.
fromAscList :: [(BKey, a)] -> BDictMap a

-- | <i>O(n)</i>. Convert the dictionary to a list of key/value pairs where
--   the keys are in ascending order.
toAscList :: BDictMap a -> [(BKey, a)]
instance GHC.Generics.Generic (Data.BEncode.BDict.BDictMap a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.BEncode.BDict.BDictMap a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.BEncode.BDict.BDictMap a)
instance GHC.Read.Read a => GHC.Read.Read (Data.BEncode.BDict.BDictMap a)
instance GHC.Show.Show a => GHC.Show.Show (Data.BEncode.BDict.BDictMap a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Data.BEncode.BDict.BDictMap a)
instance GHC.Base.Functor Data.BEncode.BDict.BDictMap
instance Data.Foldable.Foldable Data.BEncode.BDict.BDictMap
instance GHC.Base.Semigroup (Data.BEncode.BDict.BDictMap a)
instance GHC.Base.Monoid (Data.BEncode.BDict.BDictMap a)


-- | Types for working with bencode data.
module Data.BEncode.Types

-- | A bencode "integer".
type BInteger = Integer

-- | A raw bencode string.
type BString = ByteString

-- | A plain bencode list.
type BList = [BValue]

-- | A bencode dictionary.
type BDict = BDictMap BValue

-- | <a>BValue</a> 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 BValue

-- | bencode integers;
BInteger :: !BInteger -> BValue

-- | bencode strings;
BString :: !BString -> BValue

-- | list of bencode values;
BList :: BList -> BValue

-- | bencode key-value dictionary.
BDict :: BDict -> BValue

-- | Test if bencoded value is an integer.
isInteger :: BValue -> Bool

-- | Test if bencoded value is a string, both raw and utf8 encoded.
isString :: BValue -> Bool

-- | Test if bencoded value is a list.
isList :: BValue -> Bool

-- | Test if bencoded value is a dictionary.
isDict :: BValue -> Bool
instance GHC.Generics.Generic Data.BEncode.Types.BValue
instance GHC.Classes.Ord Data.BEncode.Types.BValue
instance GHC.Classes.Eq Data.BEncode.Types.BValue
instance GHC.Read.Read Data.BEncode.Types.BValue
instance GHC.Show.Show Data.BEncode.Types.BValue
instance Control.DeepSeq.NFData Data.BEncode.Types.BValue


-- | This module provides bencode values serialization. Normally, you don't
--   need to import this module, use <a>BEncode</a> instead.
module Data.BEncode.Internal

-- | BEncode format parser according to specification.
parser :: Parser BValue

-- | Try to convert raw bytestring to bencoded value according to
--   specification.
parse :: ByteString -> Either String BValue

-- | BEncode format encoder according to specification.
builder :: BValue -> Builder

-- | Convert bencoded value to raw bytestring according to the
--   specification.
build :: BValue -> ByteString

-- | Convert to easily readable JSON-like document. Typically used for
--   debugging purposes.
ppBEncode :: BValue -> Doc


-- | 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:
--   
--   <ul>
--   <li>byte strings — represented as <a>ByteString</a>;</li>
--   <li>integers — represented as <a>Integer</a>;</li>
--   <li>lists - represented as ordinary lists;</li>
--   <li>dictionaries — represented as <a>BDictMap</a>;</li>
--   </ul>
--   
--   To serialize any other types we need to make conversion. To make
--   conversion more convenient there is type class for it: <a>BEncode</a>.
--   Any textual strings are considered as UTF8 encoded <a>Text</a>.
--   
--   The complete Augmented BNF syntax for bencoding format is:
--   
--   <pre>
--   &lt;BE&gt;    ::= &lt;DICT&gt; | &lt;LIST&gt; | &lt;INT&gt; | &lt;STR&gt;
--   
--   &lt;DICT&gt;  ::= "d" 1 * (&lt;STR&gt; &lt;BE&gt;) "e"
--   &lt;LIST&gt;  ::= "l" 1 * &lt;BE&gt;         "e"
--   &lt;INT&gt;   ::= "i"     &lt;SNUM&gt;       "e"
--   &lt;STR&gt;   ::= &lt;NUM&gt; ":" n * &lt;CHAR&gt;; where n equals the &lt;NUM&gt;
--   
--   &lt;SNUM&gt;  ::= "-" &lt;NUM&gt; / &lt;NUM&gt;
--   &lt;NUM&gt;   ::= 1 * &lt;DIGIT&gt;
--   &lt;CHAR&gt;  ::= %
--   &lt;DIGIT&gt; ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
--   </pre>
--   
--   This module is considered to be imported qualified, for example:
--   
--   <pre>
--   import Data.BEncode as BE
--   </pre>
module Data.BEncode

-- | <a>BValue</a> 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 BValue

-- | bencode integers;
BInteger :: !BInteger -> BValue

-- | bencode strings;
BString :: !BString -> BValue

-- | list of bencode values;
BList :: BList -> BValue

-- | bencode key-value dictionary.
BDict :: BDict -> BValue

-- | This class is used to define new datatypes that could be easily
--   serialized using bencode format.
--   
--   By default <a>BEncode</a> have a generic implementation; suppose the
--   following datatype:
--   
--   <pre>
--   data List a = C { _head  :: a
--                   , __tail :: List a }
--               | N
--                 deriving Generic
--   </pre>
--   
--   If we don't need to obey any particular specification or standard, the
--   default instance could be derived automatically from the
--   <a>Generic</a> instance:
--   
--   <pre>
--   instance BEncode a =&gt; BEncode (List a)
--   </pre>
--   
--   Example of derived <a>toBEncode</a> result:
--   
--   <pre>
--   &gt; toBEncode (C 123 $ C 1 N)
--   BDict (fromList [("head",BInteger 123),("tail",BList [])])
--   </pre>
--   
--   Note that prefixed underscore characters are omitted since they are
--   usually used for lens.
class BEncode a

-- | See an example of implementation here <a>Assoc</a>
toBEncode :: BEncode a => a -> BValue

-- | See an example of implementation here <a>Assoc</a>
toBEncode :: (BEncode a, Generic a) => GBEncodable (Rep a) BValue => a -> BValue

-- | See an example of implementation here <a>Get</a>.
fromBEncode :: BEncode a => BValue -> Result a

-- | See an example of implementation here <a>Get</a>.
fromBEncode :: (BEncode a, Generic a) => GBEncodable (Rep a) BValue => BValue -> Result a

-- | Encode a value using bencode format to a lazy <a>ByteString</a>.
encode :: BEncode a => a -> ByteString

-- | Decode a value from a strict <a>ByteString</a> using bencode format.
decode :: BEncode a => ByteString -> Result a

-- | <i>Assoc</i> used to easily build dictionaries with required and
--   optional keys. Suppose we have we following datatype we want to
--   serialize:
--   
--   <pre>
--   data FileInfo = FileInfo
--     { fileLength :: Integer
--     , fileMD5sum :: Maybe ByteString
--     , filePath   :: [ByteString]
--     , fileTags   :: Maybe [Text]
--     } deriving (Show, Read, Eq)
--   
--   </pre>
--   
--   We need to make <tt>instance <a>BEncode</a> FileInfo</tt>, though we
--   don't want to check the both <a>Maybe</a>s manually. The more
--   declarative and convenient way to define the <a>toBEncode</a> method
--   is to use dictionary builders:
--   
--   <pre>
--   instance <a>BEncode</a> FileInfo where
--     <a>toBEncode</a> FileInfo {..} = <a>toDict</a> $
--          "length" <a>.=!</a> fileLength
--       <a>.:</a> "md5sum" <a>.=?</a> fileMD5sum
--       <a>.:</a> "path"   <a>.=!</a> filePath
--       <a>.:</a> "tags"   <a>.=?</a> fileTags
--       <a>.:</a> <a>endDict</a>
--   
--   </pre>
--   
--   NOTE: the list of pairs MUST be sorted lexicographically by keys, like
--   so:
--   
--   "length" <a>&lt;</a> "md5sum" <a>&lt;</a> "path" <a>&lt;</a> "tags"
data Assoc

-- | Make required key value pair.
(.=!) :: BEncode a => BKey -> a -> Assoc
infix 6 .=!

-- | Like the (<a>.=!</a>) operator but if the value is not present then
--   the key do not appear in resulting bencode dictionary.
(.=?) :: BEncode a => BKey -> Maybe a -> Assoc
infix 6 .=?

-- | Cons a key/value pair.
(.:) :: Assoc -> BDict -> BDict
infixr 5 .:

-- | Used to specify end of dictionary. See <a>Assoc</a>.
endDict :: BDict

-- | Make a bencode value from dictionary description.
toDict :: BDict -> BValue

-- | Dictionary extractor are similar to dictionary builders, but play the
--   opposite role: they are used to define <a>fromBEncode</a> method in
--   declarative style. Using the same <i>FileInfo</i> datatype the
--   <a>fromBEncode</a> function instance looks like:
--   
--   <pre>
--   instance <a>BEncode</a> FileInfo where
--     <a>fromBEncode</a> = <a>fromDict</a> $ do
--       FileInfo <a>&lt;$&gt;!</a> "length"
--                <a>&lt;*&gt;?</a> "md5sum"
--                <a>&lt;*&gt;!</a> "path"
--                <a>&lt;*&gt;?</a> "tags"
--   
--   </pre>
--   
--   The <i>reqKey</i> 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" <a>&lt;</a> "md5sum" <a>&lt;</a> "path" <a>&lt;</a> "tags"
data Get a

-- | Result used in decoding operations.
type Result = Either String

-- | Typically used to throw an decoding error in fromBEncode; when BEncode
--   value to match expected value.
decodingError :: String -> Result a

-- | Run a <a>Get</a> monad. See <a>Get</a> for usage.
fromDict :: forall a. Typeable a => Get a -> BValue -> Result a

-- | Run action, but return without consuming and key/value pair. Fails if
--   the action fails.
lookAhead :: Get a -> Get a

-- | Get lexicographical successor of the current key/value pair.
next :: Get BValue

-- | Extract <i>required</i> value from the given key.
req :: BKey -> Get BValue

-- | Extract optional value from the given key.
opt :: BKey -> Get (Maybe BValue)

-- | Reconstruct a bencodable value from bencode value.
field :: BEncode a => Get BValue -> Get a

-- | Match key with value.
match :: BKey -> BValue -> Get ()

-- | Shorthand for: <tt>f <a>&lt;$&gt;</a> <a>field</a> (<a>req</a>
--   k)</tt>.
(<$>!) :: BEncode a => (a -> b) -> BKey -> Get b
infixl 4 <$>!

-- | Shorthand for: <tt>f <a>&lt;$&gt;</a> <a>optional</a> (<a>field</a>
--   (<a>req</a> k))</tt>.
(<$>?) :: BEncode a => (Maybe a -> b) -> BKey -> Get b
infixl 4 <$>?

-- | Shorthand for: <tt>f <a>&lt;*&gt;</a> <a>field</a> (<a>req</a>
--   k)</tt>.
(<*>!) :: BEncode a => Get (a -> b) -> BKey -> Get b
infixl 4 <*>!

-- | Shorthand for: <tt>f <a>&lt;*&gt;</a> <a>optional</a> (<a>field</a>
--   (<a>req</a> k))</tt>.
(<*>?) :: BEncode a => Get (Maybe a -> b) -> BKey -> Get b
infixl 4 <*>?
instance GHC.Base.Alternative Data.BEncode.Get
instance GHC.Base.Applicative Data.BEncode.Get
instance GHC.Base.Functor Data.BEncode.Get
instance GHC.Base.Monad Data.BEncode.Get
instance Data.BEncode.BEncode f => Data.BEncode.GBEncodable (GHC.Generics.K1 GHC.Generics.R f) Data.BEncode.Types.BValue
instance Data.BEncode.BEncode Data.BEncode.Types.BValue
instance Data.BEncode.BEncode Data.BEncode.Types.BInteger
instance Data.BEncode.BEncode Data.BEncode.Types.BString
instance Data.BEncode.BEncode Data.BEncode.Types.BDict
instance Data.BEncode.BEncode GHC.Word.Word8
instance Data.BEncode.BEncode GHC.Word.Word16
instance Data.BEncode.BEncode GHC.Word.Word32
instance Data.BEncode.BEncode GHC.Word.Word64
instance Data.BEncode.BEncode GHC.Types.Word
instance Data.BEncode.BEncode GHC.Int.Int8
instance Data.BEncode.BEncode GHC.Int.Int16
instance Data.BEncode.BEncode GHC.Int.Int32
instance Data.BEncode.BEncode GHC.Int.Int64
instance Data.BEncode.BEncode GHC.Types.Int
instance Data.BEncode.BEncode GHC.Types.Bool
instance Data.BEncode.BEncode Data.Text.Internal.Text
instance Data.BEncode.BEncode a => Data.BEncode.BEncode [a]
instance Data.BEncode.BEncode Data.Version.Version
instance Data.BEncode.BEncode ()
instance (Data.BEncode.BEncode a, Data.BEncode.BEncode b) => Data.BEncode.BEncode (a, b)
instance (Data.BEncode.BEncode a, Data.BEncode.BEncode b, Data.BEncode.BEncode c) => Data.BEncode.BEncode (a, b, c)
instance (Data.BEncode.BEncode a, Data.BEncode.BEncode b, Data.BEncode.BEncode c, Data.BEncode.BEncode d) => Data.BEncode.BEncode (a, b, c, d)
instance (Data.BEncode.BEncode a, Data.BEncode.BEncode b, Data.BEncode.BEncode c, Data.BEncode.BEncode d, Data.BEncode.BEncode e) => Data.BEncode.BEncode (a, b, c, d, e)
instance (GHC.Classes.Eq e, GHC.Base.Monoid e) => Data.BEncode.GBEncodable GHC.Generics.U1 e
instance (Data.BEncode.GBEncodable a Data.BEncode.Types.BList, Data.BEncode.GBEncodable b Data.BEncode.Types.BList) => Data.BEncode.GBEncodable (a GHC.Generics.:*: b) Data.BEncode.Types.BList
instance (Data.BEncode.GBEncodable a Data.BEncode.Types.BDict, Data.BEncode.GBEncodable b Data.BEncode.Types.BDict) => Data.BEncode.GBEncodable (a GHC.Generics.:*: b) Data.BEncode.Types.BDict
instance (Data.BEncode.GBEncodable a e, Data.BEncode.GBEncodable b e) => Data.BEncode.GBEncodable (a GHC.Generics.:+: b) e
instance (GHC.Generics.Selector s, Data.BEncode.GBEncodable f Data.BEncode.Types.BValue) => Data.BEncode.GBEncodable (GHC.Generics.M1 GHC.Generics.S s f) Data.BEncode.Types.BDict
instance Data.BEncode.GBEncodable f Data.BEncode.Types.BValue => Data.BEncode.GBEncodable (GHC.Generics.M1 GHC.Generics.S s f) Data.BEncode.Types.BList
instance (GHC.Generics.Constructor c, Data.BEncode.GBEncodable f Data.BEncode.Types.BDict, Data.BEncode.GBEncodable f Data.BEncode.Types.BList) => Data.BEncode.GBEncodable (GHC.Generics.M1 GHC.Generics.C c f) Data.BEncode.Types.BValue
instance Data.BEncode.GBEncodable f e => Data.BEncode.GBEncodable (GHC.Generics.M1 GHC.Generics.D d f) e