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


-- | Library for encoding/decoding TNET strings for PGI
--   
--   Provides an API to encode/decode Haskell datatypes into the TNET
--   protocol.
@package tnet
@version 0.0.1


-- | <a>TNET</a> is a library that implements the TNET serialization
--   protocol to be used for PGI
--   (<a>http://code.google.com/p/polyweb/source/browse/doc/PGI.txt</a>)
--   applications. The TNET protocol (<a>http://tnetstrings.org</a>) is
--   designed to be simple to implement in any language, please look at the
--   README for the changes to the original tnetstrings spec.
module TNET
tnetParser :: Parser TValue

-- | The <a>TNET</a> typeclass represents types that can be encoded and
--   decoded in the TNET format. An example instance:
--   
--   <pre>
--   data Person = Person {
--                   name :: String
--                 , age  :: Integer
--                 }
--   instance TNET Person where
--     toTNET (Person n a) = dict [ "name" .= n
--                                , "age"  .= a
--                                ]
--     fromTNET tval = do
--       n &lt;- tval .: "name"
--       a &lt;- tval .: "age"
--       return $ Person n a
--   </pre>
class TNET a
toTNET :: TNET a => a -> TValue
fromTNET :: TNET a => TValue -> Maybe a

-- | A <a>TValue</a> represents a raw TNET object. TNET values are one of
--   the following types:
--   
--   <ul>
--   <li>a string of bytes</li>
--   <li>a UTF-8 encoded string</li>
--   <li>an integer</li>
--   <li>a floating point number</li>
--   <li>a boolean</li>
--   <li>null</li>
--   <li>a dictionary type</li>
--   <li>a list of TValues</li>
--   </ul>
data TValue

-- | Decode a TNET format bytestring into a Haskell value. An explicit type
--   annotation may be needed if the type of the decoded value can not be
--   determined:
--   
--   <pre>
--   &gt;&gt;&gt; decode "0:~" :: Maybe ()
--   Just ()
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decode "0:~" :: Maybe (Maybe String)
--   Just Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decode "1:5#" :: Maybe Integer
--   Just 5
--   </pre>
--   
--   <pre>
--   let x = decode "4:true!" in
--   case x of
--     Just True  -&gt; putStrLn "got true!"
--     Just False -&gt; putStrLn "got false!"
--     Nothing    -&gt; putStrLn "error decoding"
--   </pre>
decode :: TNET a => ByteString -> Maybe a

-- | Encode a Haskell value into the TNET format. Some examples:
--   
--   <pre>
--   &gt;&gt;&gt; encode 5
--   "1:5#"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; encode "Hello"
--   "5:Hello$"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; encode (-12.3)
--   "5:-12.3^"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; encode ()
--   "0:~"
--   </pre>
encode :: TNET a => a -> ByteString

-- | Used to create a TNET dictionary from TNET values. Meant to be used
--   with the <a>.=</a> operator as in the following example:
--   
--   <pre>
--   myDict = dict [ "a" .= 5
--                 , "is_dict" .= True
--                 ]
--   </pre>
dict :: [(String, TValue)] -> TValue
(.=) :: TNET a => String -> a -> (String, TValue)

-- | Helper function to extract TNET values from a TNET dictionary. Meant
--   to be used as in the following example:
--   
--   <pre>
--   data Person = Person {
--                   name :: String
--                 , age  :: Integer
--                 }
--   personFromDict :: TValue -&gt; Maybe Person
--   personFromDict tdict = do
--     name &lt;- tdict .: "name"
--     age  &lt;- tdict .: "age"
--     return $ Person name age
--   </pre>
(.:) :: TNET a => TValue -> String -> Maybe a
instance [overlap ok] Eq TValue
instance [overlap ok] Show TValue
instance [overlap ok] TNET a => TNET [a]
instance [overlap ok] TNET a => TNET (Maybe a)
instance [overlap ok] TNET ByteString
instance [overlap ok] TNET Char
instance [overlap ok] TNET String
instance [overlap ok] TNET a => TNET [(String, a)]
instance [overlap ok] TNET Bool
instance [overlap ok] TNET Double
instance [overlap ok] TNET Integer
instance [overlap ok] TNET TValue
instance [overlap ok] TNET ()