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


-- | Write to and read from ByteStrings maintaining internal memory references
--   
--   Read, Show and Binary instances do not check for internal data
--   references to the same address. As a result, the data is duplicated
--   when serialized. This is a waste of space in the filesystem and also a
--   waste of serialization time. but the worst consequence is that, when
--   the serialized data is read, it allocates multiple copies for the same
--   object when referenced multiple times. Because multiple referenced
--   data is very typical in a pure language such is Haskell, this means
--   that the resulting data loose the beatiful economy of space and
--   processing time that referential transparency permits.
--   
--   In this release the default <a>(Read a, Show a) =&gt; Refserialize
--   a</a> has been removed.
--   
--   See <a>Data.RefSerialize</a> for details
@package RefSerialize
@version 0.3.1.0

module Data.RefSerialize.Serialize
type MFun = Char
type VarName = String
data ShowF
Expr :: ByteString -> ShowF
Var :: Int -> ShowF
type Context = HashTable Int (StableName MFun, MFun, [ShowF], Int)
data Error
Error :: String -> Error
data StatW
StatW :: (Context, [ShowF], ByteString) -> StatW
data STW a
STW :: (StatW -> (StatW, a)) -> STW a
empty :: IO (HashTable Int val)
assocs :: Ord a => HashTable a b -> [(a, b)]
insert :: key -> val -> HashTable key val -> HashTable key val
delete :: key -> HashTable key val -> HashTable key val
lookup :: key -> HashTable key val -> Maybe val
toList :: HashTable key val -> [(key, val)]
fromList :: [(Int, val)] -> HashTable Int val

-- | return a unique hash identifier for an object the context assures that
--   no StableName used in addrStr is garbage collected, so the hashes are
--   constant and the correspondence address - string remain one to one as
--   long as the context is not garbage collected. Left is returned if it
--   is the first time that <tt>addHash</tt> is called for that variable
addrHash :: Context -> a -> IO (Either Int Int)
readContext :: ByteString -> ByteString -> (ByteString, ByteString)
hasht :: a -> (Int, t)

-- | two variables that point to the same address will have identical
--   varname (derived from import System.Mem.StableName)varName:: a -&gt;
--   String . The stable names of during the serializing deserializing
--   process are not deleted . This is assured by the pointers in the
--   context, so the hash values remain and the comparison of varNames is
--   correct.
varName :: a -> [Char]
numVar :: String -> Maybe Int
instance [overlap ok] Show ShowF
instance [overlap ok] Monad STW


-- | A Parsec parser for the refSerialize monad. See package Parsec. all
--   the functions have the same meaning
module Data.RefSerialize.Parser
data STR a
STR :: (StatR -> Either Error (StatR, a)) -> STR a
data StatR
StatR :: (Context, ByteString, ByteString) -> StatR
(<?>) :: STR a -> String -> STR a
(<|>) :: STR a -> STR a -> STR a
char :: Char -> STR Char
anyChar :: STR Char
string :: [Char] -> STR [Char]
upper :: STR Char
space :: STR Char
digit :: STR Char
sepBy :: STR a -> STR sep -> STR [a]
between :: Monad m => m a -> m a1 -> m b -> m b
choice :: [STR a] -> STR a
option :: a -> STR a -> STR a
notFollowedBy :: Show t => STR t -> STR ()
many :: STR a -> STR [a]
manyTill :: STR a1 -> STR a -> STR [a1]
oneOf :: [Char] -> STR Char
noneOf :: [Char] -> STR Char
bool :: STR Bool
try :: STR b -> STR b
empty :: STR ()
readContent :: STR ByteString
charLiteral :: STR Char
stringLiteral :: STR [Char]
natural :: STR Integer
integer :: STR Integer
float :: STR Double
naturalOrFloat :: STR (Either Integer Double)
decimal :: STR Integer
hexadecimal :: STR Integer
octal :: STR Integer
symbol :: [Char] -> STR [Char]
lexeme :: STR b -> STR b
whiteSpace :: STR ()
parens :: STR a -> STR a
braces :: STR a -> STR a
angles :: STR a -> STR a
brackets :: STR a -> STR a
semi :: STR [Char]
comma :: STR [Char]
colon :: STR [Char]
dot :: STR [Char]
semiSep :: STR a -> STR [a]
semiSep1 :: STR a -> STR [a]
commaSep :: STR a -> STR [a]
commaSep1 :: STR a -> STR [a]
instance MonadPlus STR
instance Monad STR


-- | Read, Show and Data.Binary do not check for repeated references to the
--   same address. As a result, the data is duplicated when serialized.
--   This is a waste of space in the filesystem and also a waste of
--   serialization time. but the worst consequence is that, when the
--   serialized data is read, it allocates multiple copies for the same
--   object when referenced multiple times. Because multiple referenced
--   data is very typical in a pure language such is Haskell, this means
--   that the resulting data loose the beatiful economy of space and
--   processing time that referential transparency permits.
--   
--   This package leverages Show, Read and Data.Binary instances while it
--   permits textual as well as binary serialization keeping internal
--   references.
--   
--   NOTE: to avoid long lists of variables with only one reference, now
--   variables not referenced two or more times are inlined so rshowp
--   serializes the same result than showp in these cases. However, showp
--   is faster. In correspondence, rreadp call readp when there is no
--   variable serialized.
--   
--   This is an example of a showp parser for a simple data structure.
--   
--   <pre>
--   data S= S Int Int deriving ( Show, Eq)
--   
--   instance  Serialize S  where
--      showp (S x y)= do
--                      insertString "S"
--                      rshowp x       -- rshowp parsers can be inside showp parser
--                      rshowp y
--   
--   
--      readp =  do
--                      symbol "S"     -- I included a (almost) complete Parsec for deserialization
--                      x &lt;- rreadp
--                      y &lt;- rreadp
--                      return $ S x y
--   </pre>
--   
--   there is a mix between referencing and no referencing parser here:
--   
--   <pre>
--   Data.RefSerialize&gt;putStrLn $ runW $ showp $ S x x
--   S  v23 v23 where {v23= 5; }
--   </pre>
module Data.RefSerialize
class Serialize c
showp :: Serialize c => c -> STW ()
readp :: Serialize c => STR c

-- | insert a reference (a variable in the where section).
rshowp :: Serialize c => c -> STW ()
rreadp :: Serialize c => STR c

-- | return the serialization instead of updating the writer
showps :: Serialize a => a -> STW ByteString

-- | return the variable name of the serialized data, which is put in the
--   context and does not update the writer
rshowps :: Serialize c => c -> STW ByteString

-- | deserialize the string with the parser
runR :: STR a -> ByteString -> a

-- | serialize x with the parser
runW :: STW () -> ByteString

-- | if a is an instance of Show, showpText can be used as the showp method
--   the drawback is that the data inside is not inspected for common
--   references so it is recommended to create your own readp method for
--   your complex data structures
showpText :: Show a => a -> STW ()

-- | if a is an instance of Read, readpText can be used as the readp method
--   the drawback is that the data inside is not inspected for common
--   references so it is recommended to create your own readp method for
--   your complex data structures
readpText :: Read a => STR a

-- | serialize a variable which has a Binary instance
showpBinary :: Binary a => a -> STW ()

-- | deserialize a variable serialized by <a>showpBinary</a>
readpBinary :: Binary a => STR a

-- | Write a String in the serialized output with an added whitespace.
--   Deserializable with <a>symbol</a>
insertString :: ByteString -> STW ()

-- | Write a char in the serialized output (no spaces)
insertChar :: Char -> STW ()

-- | use the rshowp parser to serialize the object <tt> rShow c= runW $
--   rshowp c</tt>
rShow :: Serialize c => c -> ByteString

-- | deserialize trough the rreadp parser <tt> rRead str= runR rreadp $
--   str</tt>
rRead :: Serialize c => ByteString -> c

-- | insert a variable at this position. The expression value is inserted
--   in the <a>where</a> section if it is not already created. If the
--   address of this object being parsed correspond with an address already
--   parsed and it is in the where section, then the same variable name is
--   used <tt>runW showp (1::Int) -&gt; <a>1</a> runW (insertVar showp)
--   (1::Int) -&gt; v1 where { v1=1} runW (insertVar showp) [(1::Int) ,1]
--   -&gt; [v1.v1] where { v1=1}</tt> This is useful when the object is
--   referenced many times
insertVar :: (a -> STW ()) -> a -> STW ()

-- | return a unique hash identifier for an object the context assures that
--   no StableName used in addrStr is garbage collected, so the hashes are
--   constant and the correspondence address - string remain one to one as
--   long as the context is not garbage collected. Left is returned if it
--   is the first time that <tt>addHash</tt> is called for that variable
addrHash :: Context -> a -> IO (Either Int Int)

-- | deserialize a variable serialized with insertVar. Memory references
--   are restored
readVar :: Serialize c => STR c -> STR c
takep :: Int -> STR ByteString
readHexp :: (Num a, Integral a) => STR a
showHexp :: (Num a, Integral a, Show a) => a -> STW ()
type Context = HashTable Int (StableName MFun, MFun, [ShowF], Int)

-- | return the serialized list of variable values useful for delayed
--   deserialzation of expresions, in case of dynamic variables were
--   deserialization is done when needed, once the type is known with
--   <a>runRC</a>
getRContext :: STR (Context, ByteString)
getWContext :: STW (Context, ByteString)
newContext :: IO Context

-- | serialize the variables. if the Bool flag is true, it prepend the text
--   with the string <a>where</a>
showContext :: Context -> Bool -> ByteString

-- | read an expression with the variables definedd in a context passed as
--   parameter.
runRC :: (Context, ByteString) -> STR a -> ByteString -> a

-- | serialize x witn a given context and the parser
runWC :: (Context, ByteString) -> STW () -> ByteString
instance [incoherent] (Serialize a, Serialize b) => Serialize (Either a b)
instance [incoherent] Serialize a => Serialize (Maybe a)
instance [incoherent] (Serialize a, Ord a, Serialize b) => Serialize (Map a b)
instance [incoherent] (Serialize a, Serialize b, Serialize c, Serialize d) => Serialize (a, b, c, d)
instance [incoherent] (Serialize a, Serialize b, Serialize c) => Serialize (a, b, c)
instance [incoherent] (Serialize a, Serialize b) => Serialize (a, b)
instance [incoherent] Serialize String
instance [incoherent] Serialize a => Serialize [a]