RefSerialize-0.2.4: Data-RefSerialize.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--Rendered using the Haskell Html Library v0.2-->
<HTML
><HEAD
><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8"
><TITLE
>Data.RefSerialize</TITLE
><LINK HREF="haddock.css" REL="stylesheet" TYPE="text/css"
><SCRIPT SRC="haddock-util.js" TYPE="text/javascript"
></SCRIPT
><SCRIPT TYPE="text/javascript"
>window.onload = function () {setSynopsis("mini_Data-RefSerialize.html")};</SCRIPT
></HEAD
><BODY
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="topbar"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD
><IMG SRC="haskell_icon.gif" WIDTH="16" HEIGHT="16" ALT=" "
></TD
><TD CLASS="title"
></TD
><TD CLASS="topbut"
><A HREF="index.html"
>Contents</A
></TD
><TD CLASS="topbut"
><A HREF="doc-index.html"
>Index</A
></TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="modulebar"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD
><FONT SIZE="6"
>Data.RefSerialize</FONT
></TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
>Description</TD
></TR
><TR
><TD CLASS="doc"
><P
>Read, Show and Data.Binary do not check for repeated references to the same address.
As a result, the data is duplicated when seri<alized. 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.
</P
><P
>Here comes a brief tutorial:
</P
><PRE
>runW applies showp, the serialization parser of the instance Int for the RefSerialize class
Data.RefSerialize>let x= 5 :: Int
Data.RefSerialize>runW $ showp x
<A HREF="5.html"
>5</A
>
every instance of Read and Show is an instance of RefSerialize. for how to construct showp and readp parsers, see the demo.hs
rshowp is derived from showp, it labels the serialized data with a variable name
Data.RefSerialize>runW $ rshowp x
<A HREF=" v8 where {v8= 5; }.html"
> v8 where {v8= 5; }</A
>
Data.RefSerialize>runW $ rshowp [2::Int,3::Int]
<A HREF=" v6 where {v6= [ v9, v10]; v9= 2; v10= 3; }.html"
> v6 where {v6= [ v9, v10]; v9= 2; v10= 3; }</A
>
while showp does a normal show serialization
Data.RefSerialize>runW $ showp [x,x]
<A HREF="[5, 5].html"
>[5, 5]</A
>
rshowp variables are serialized memory references: no piece of data that point to the same addrees is serialized but one time
Data.RefSerialize>runW $ rshowp [x,x]
<A HREF=" v9 where {v6= 5; v9= [ v6, v6]; }.html"
> v9 where {v6= 5; v9= [ v6, v6]; }</A
>
<A HREF="this happens recursively.html"
>this happens recursively</A
>
Data.RefSerialize>let xs= [x,x] in str = runW $ rshowp [xs,xs]
Data.RefSerialize>str
<A HREF=" v8 where {v8= [ v10, v10]; v9= 5; v10= [ v9, v9]; }.html"
> v8 where {v8= [ v10, v10]; v9= 5; v10= [ v9, v9]; }</A
>
the rshowp serialized data is read with rreadp. The showp serialized data is read by readp
Data.RefSerialize>let xss= runR rreadp str :: [[Int]]
Data.RefSerialize>print xss
[[5,5],[5,5]]
this is the deserialized data
the deserialized data keep the references!! pointers are restored! That is the whole point!
Data.RefSerialize>varName xss !! 0 == varName xss !! 1
True
rShow= runW rshowp
rRead= runR rreadp
Data.RefSerialize>rShow x
<A HREF=" v11 where {v11= 5; }.html"
> v11 where {v11= 5; }</A
>
In the definition of a referencing parser non referencing parsers can be used and viceversa. Use a referencing parser
when the piece of data is being referenced many times inside the serialized data.
by default the referencing parser is constructed by:
rshowp= insertVar showp
rreadp= readVar readp
but this can be redefined. See for example the instance of [] in RefSerialize.hs
This is an example of a showp parser for a simple data structure.
data S= S Int Int deriving ( Show, Eq)
instance Serialize S where
showp (S x y)= do
xs <- rshowp x -- rshowp parsers can be inside showp parser
ys <- rshowp y
return $ <A HREF="S .html"
>S </A
>++xs++<A HREF=" .html"
> </A
>++ys
readp = do
symbol <A HREF="S.html"
>S</A
> -- I included a (almost) complete Parsec for deserialization
x <- rreadp
y <- rreadp
return $ S x y
there is a mix between referencing and no referencing parser here:
Data.RefSerialize>putStrLn $ runW $ showp $ S x x
S v23 v23 where {v23= 5; }</PRE
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
>Synopsis</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="body"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="decl"
>module <A HREF="Data-Parser.html"
>Data.Parser</A
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>class</SPAN
> <A HREF="#t%3ASerialize"
>Serialize</A
> c <SPAN CLASS="keyword"
>where</SPAN
></TD
></TR
><TR
><TD CLASS="body"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="decl"
><A HREF="#v%3Ashowp"
>showp</A
> :: c -> <A HREF="Data-Parser.html#t%3AST"
>ST</A
> String</TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3Areadp"
>readp</A
> :: <A HREF="Data-Parser.html#t%3AST"
>ST</A
> c</TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3Arshowp"
>rshowp</A
> :: c -> <A HREF="Data-Parser.html#t%3AST"
>ST</A
> String</TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3Arreadp"
>rreadp</A
> :: <A HREF="Data-Parser.html#t%3AST"
>ST</A
> c</TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3ArShow"
>rShow</A
> :: <A HREF="Data-RefSerialize.html#t%3ASerialize"
>Serialize</A
> c => c -> String</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3ArRead"
>rRead</A
> :: <A HREF="Data-RefSerialize.html#t%3ASerialize"
>Serialize</A
> c => String -> c</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AinsertVar"
>insertVar</A
> :: (a -> <A HREF="Data-Parser.html#t%3AST"
>ST</A
> String) -> a -> <A HREF="Data-Parser.html#t%3AST"
>ST</A
> String</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AreadVar"
>readVar</A
> :: <A HREF="Data-RefSerialize.html#t%3ASerialize"
>Serialize</A
> c => <A HREF="Data-Parser.html#t%3AST"
>ST</A
> c -> <A HREF="Data-Parser.html#t%3AST"
>ST</A
> c</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AvarName"
>varName</A
> :: a -> String</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3ArunR"
>runR</A
> :: <A HREF="Data-Parser.html#t%3AST"
>ST</A
> a -> String -> a</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3ArunW"
>runW</A
> :: <A HREF="Data-Parser.html#t%3AST"
>ST</A
> String -> String</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AreadHexp"
>readHexp</A
> :: (Num a, Integral a) => <A HREF="Data-Parser.html#t%3AST"
>ST</A
> a</TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A HREF="#v%3AshowHexp"
>showHexp</A
> :: (Num a, Integral a) => a -> <A HREF="Data-Parser.html#t%3AST"
>ST</A
> String</TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="section1"
>Documentation</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
>module <A HREF="Data-Parser.html"
>Data.Parser</A
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><SPAN CLASS="keyword"
>class</SPAN
> <A NAME="t:Serialize"
><A NAME="t%3ASerialize"
></A
></A
><B
>Serialize</B
> c <SPAN CLASS="keyword"
>where</SPAN
></TD
></TR
><TR
><TD CLASS="body"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="section4"
>Methods</TD
></TR
><TR
><TD CLASS="body"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="decl"
><A NAME="v:showp"
><A NAME="v%3Ashowp"
></A
></A
><B
>showp</B
></TD
></TR
><TR
><TD CLASS="body"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="arg"
>:: c</TD
><TD CLASS="rdoc"
></TD
></TR
><TR
><TD CLASS="arg"
>-> <A HREF="Data-Parser.html#t%3AST"
>ST</A
> String</TD
><TD CLASS="rdoc"
>shows the content of a expression, must be defined bu the user
</TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:readp"
><A NAME="v%3Areadp"
></A
></A
><B
>readp</B
></TD
></TR
><TR
><TD CLASS="body"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="arg"
>:: <A HREF="Data-Parser.html#t%3AST"
>ST</A
> c</TD
><TD CLASS="rdoc"
>read the content of a expression, must be user defined
</TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:rshowp"
><A NAME="v%3Arshowp"
></A
></A
><B
>rshowp</B
></TD
></TR
><TR
><TD CLASS="body"
><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0"
><TR
><TD CLASS="arg"
>:: c</TD
><TD CLASS="rdoc"
></TD
></TR
><TR
><TD CLASS="arg"
>-> <A HREF="Data-Parser.html#t%3AST"
>ST</A
> String</TD
><TD CLASS="rdoc"
>insert a reference (a variable in the where section). <TT
>rshowp = insertVar showp </TT
> -- default definition
</TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:rreadp"
><A NAME="v%3Arreadp"
></A
></A
><B
>rreadp</B
> :: <A HREF="Data-Parser.html#t%3AST"
>ST</A
> c</TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s8"
></TD
></TR
><TR
><TD CLASS="section4"
><IMG SRC="minus.gif" CLASS="coll" ONCLICK="toggle(this,'i:Serialize')" ALT="show/hide"
> Instances</TD
></TR
><TR
><TD CLASS="body"
><DIV ID="i:Serialize" STYLE="display:block;"
><TABLE CLASS="vanilla" CELLSPACING="1" CELLPADDING="0"
><TR
><TD CLASS="decl"
><A HREF="Data-RefSerialize.html#t%3ASerialize"
>Serialize</A
> String</TD
></TR
><TR
><TD CLASS="decl"
><A HREF="Data-RefSerialize.html#t%3ASerialize"
>Serialize</A
> a => <A HREF="Data-RefSerialize.html#t%3ASerialize"
>Serialize</A
> ([] a)</TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
></TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:rShow"
><A NAME="v%3ArShow"
></A
></A
><B
>rShow</B
> :: <A HREF="Data-RefSerialize.html#t%3ASerialize"
>Serialize</A
> c => c -> String</TD
></TR
><TR
><TD CLASS="doc"
>use the rshowp parser to serialize the object
<TT
> rShow c= runW $ rshowp c</TT
>
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:rRead"
><A NAME="v%3ArRead"
></A
></A
><B
>rRead</B
> :: <A HREF="Data-RefSerialize.html#t%3ASerialize"
>Serialize</A
> c => String -> c</TD
></TR
><TR
><TD CLASS="doc"
>deserialize trough the rreadp parser
<TT
> rRead str= runR rreadp $ str</TT
>
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:insertVar"
><A NAME="v%3AinsertVar"
></A
></A
><B
>insertVar</B
> :: (a -> <A HREF="Data-Parser.html#t%3AST"
>ST</A
> String) -> a -> <A HREF="Data-Parser.html#t%3AST"
>ST</A
> String</TD
></TR
><TR
><TD CLASS="doc"
>insert a variable at this position. The expression value is inserted the where part 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) -> <A HREF="1.html"
>1</A
>
runW (insertVar showp) (1::Int) -> v1 where { v1=1}
runW (insertVar showp) [(1::Int) ,1] -> [v1.v1] where { v1=1}</TT
>
This is useful when the object is referenced many times
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:readVar"
><A NAME="v%3AreadVar"
></A
></A
><B
>readVar</B
> :: <A HREF="Data-RefSerialize.html#t%3ASerialize"
>Serialize</A
> c => <A HREF="Data-Parser.html#t%3AST"
>ST</A
> c -> <A HREF="Data-Parser.html#t%3AST"
>ST</A
> c</TD
></TR
><TR
><TD CLASS="doc"
>deserialize a variable serialized with insertVar. Memory references are restored
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:varName"
><A NAME="v%3AvarName"
></A
></A
><B
>varName</B
> :: a -> String</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:runR"
><A NAME="v%3ArunR"
></A
></A
><B
>runR</B
> :: <A HREF="Data-Parser.html#t%3AST"
>ST</A
> a -> String -> a</TD
></TR
><TR
><TD CLASS="doc"
>deserialize the string with the parser
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:runW"
><A NAME="v%3ArunW"
></A
></A
><B
>runW</B
> :: <A HREF="Data-Parser.html#t%3AST"
>ST</A
> String -> String</TD
></TR
><TR
><TD CLASS="doc"
>serialize x with the parser
</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:readHexp"
><A NAME="v%3AreadHexp"
></A
></A
><B
>readHexp</B
> :: (Num a, Integral a) => <A HREF="Data-Parser.html#t%3AST"
>ST</A
> a</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="decl"
><A NAME="v:showHexp"
><A NAME="v%3AshowHexp"
></A
></A
><B
>showHexp</B
> :: (Num a, Integral a) => a -> <A HREF="Data-Parser.html#t%3AST"
>ST</A
> String</TD
></TR
><TR
><TD CLASS="s15"
></TD
></TR
><TR
><TD CLASS="botbar"
>Produced by <A HREF="http://www.haskell.org/haddock/"
>Haddock</A
> version 2.4.2</TD
></TR
></TABLE
></BODY
></HTML
>