-- 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:
--   
--   Compatibility with older versions of bytestring that have no
--   <a>toStrict</a> call
--   
--   deserialization is much, much faster by using the stringsearch package
--   
--   See <a>Data.RefSerialize</a> for details
@package RefSerialize
@version 0.4.0

module Data.RefSerialize.Serialize
myToStrict :: ByteString -> ByteString
type MFun = Char
type VarName = String
data ShowF
Expr :: ByteString -> ShowF
Var :: Int -> ShowF
type Context = BasicHashTable 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

-- | monadic serialization
empty :: HashTable h => IO h RealWorld k v
assocs :: (Hashable a, HashTable h, Ord a) => h RealWorld a b -> [(a, b)]
insert :: (Hashable k, Eq k, HashTable h) => k -> v -> h RealWorld k v -> h RealWorld k v
delete :: (Hashable k, Eq k, HashTable h) => k -> h RealWorld k v -> h RealWorld k v
lookup :: (Hashable k, Eq k, HashTable h) => k -> h RealWorld k v -> Maybe v
toList :: (Hashable k, Eq k, HashTable h) => h RealWorld k v -> [(k, v)]
fromList :: (Hashable k, Eq k, HashTable h) => [(k, v)] -> h RealWorld k v

-- | 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, b)

-- | 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 :: () => p -> [Char]
numVar :: String -> Maybe Int
instance GHC.Show.Show Data.RefSerialize.Serialize.ShowF
instance GHC.Base.Functor Data.RefSerialize.Serialize.STW
instance GHC.Base.Applicative Data.RefSerialize.Serialize.STW
instance GHC.Base.Monad Data.RefSerialize.Serialize.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
infix 0 <?>
(<|>) :: () => STR a -> STR a -> STR a
infixr 1 <|>
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 a1 -> m a2 -> m b -> m b
choice :: Foldable t => t STR a -> STR a
option :: () => a -> STR a -> STR a
notFollowedBy :: Show a => STR a -> STR ()
many :: STR a -> STR [a]
manyTill :: () => STR a1 -> STR a2 -> STR [a1]
oneOf :: Foldable t => t Char -> STR Char
noneOf :: Foldable t => t 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 GHC.Base.Functor Data.RefSerialize.Parser.STR
instance GHC.Base.Applicative Data.RefSerialize.Parser.STR
instance GHC.Base.Alternative Data.RefSerialize.Parser.STR
instance GHC.Base.Monad Data.RefSerialize.Parser.STR
instance GHC.Base.MonadPlus Data.RefSerialize.Parser.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 p => p -> 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 "where" 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; "1" 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 :: Int64 -> STR ByteString
readHexp :: (Num a, Integral a) => STR a
showHexp :: (Num a, Integral a, Show a) => a -> STW ()
type Context = BasicHashTable 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 "where"
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 Data.RefSerialize.Serialize a => Data.RefSerialize.Serialize [a]
instance Data.RefSerialize.Serialize GHC.Base.String
instance (Data.RefSerialize.Serialize a, Data.RefSerialize.Serialize b) => Data.RefSerialize.Serialize (a, b)
instance (Data.RefSerialize.Serialize a, Data.RefSerialize.Serialize b, Data.RefSerialize.Serialize c) => Data.RefSerialize.Serialize (a, b, c)
instance (Data.RefSerialize.Serialize a, Data.RefSerialize.Serialize b, Data.RefSerialize.Serialize c, Data.RefSerialize.Serialize d) => Data.RefSerialize.Serialize (a, b, c, d)
instance (Data.RefSerialize.Serialize a, GHC.Classes.Ord a, Data.RefSerialize.Serialize b) => Data.RefSerialize.Serialize (Data.Map.Internal.Map a b)
instance Data.RefSerialize.Serialize a => Data.RefSerialize.Serialize (GHC.Base.Maybe a)
instance (Data.RefSerialize.Serialize a, Data.RefSerialize.Serialize b) => Data.RefSerialize.Serialize (Data.Either.Either a b)
