1% BEGIN LICENSE BLOCK
2% Version: CMPL 1.1
3%
4% The contents of this file are subject to the Cisco-style Mozilla Public
5% License Version 1.1 (the "License"); you may not use this file except
6% in compliance with the License.  You may obtain a copy of the License
7% at www.eclipse-clp.org/license.
8% 
9% Software distributed under the License is distributed on an "AS IS"
10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See
11% the License for the specific language governing rights and limitations
12% under the License. 
13% 
14% The Original Code is  The ECLiPSe Constraint Logic Programming System. 
15% The Initial Developer of the Original Code is  Cisco Systems, Inc. 
16% Portions created by the Initial Developer are
17% Copyright (C) 2006 Cisco Systems, Inc.  All Rights Reserved.
18% 
19% Contributor(s): Joachim Schimpf, IC-Parc
20% 
21% END LICENSE BLOCK
22%
23% $Id: embexdr.tex,v 1.1 2006/09/23 01:48:59 snovello Exp $
24%
25% Author:	Joachim Schimpf, IC-Parc
26%
27
28%----------------------------------------------------------------------
29\chapter{EXDR Data Interchange Format}
30\label{chapexdr}
31%HEVEA\cutdef[1]{section}
32%----------------------------------------------------------------------
33
34We have defined a data interchange format called EXDR for the
35communication between {\eclipse} and other languages.  The data types
36available in this format are integer, double, string, list, nil,
37structure and anonymous variable.  This is intended to be the subset
38of {\eclipse} types that has a meaningful mapping to many other
39languages' data types.  The mapping onto different languages is given
40in the following table. For details of the mapping between Java
41classes/interfaces and EXDR/{\eclipse} types see Section
42\ref{sec:ji-type-correspondence}.
43
44\begin{quote}
45\begin{tabular}{|llll|}
46\hline
47\bf EXDR type     & \bf ECLiPSe type  &  \bf TCL type  &  \bf Java type\\
48\hline
49Integer       & integer       &  int	&	java.lang.Integer\\
50 e.g.         & 123           &  123	&	123\\
51\hline
52Long          & integer       &  string	&	java.lang.Long\\
53 e.g.         & 5000000000    &  5000000000 &	5000000000\\
54\hline
55Double        & float         &  double	&	java.lang.Double/Float\\
56 e.g.         & 12.3          &  12.3	&	12.3\\
57\hline
58String        & string        &  string	&	java.lang.String\\
59 e.g.         & "abc"         &  abc	&	"abc"\\
60\hline
61List          & ./2           &  list	&	java.util.Collection\\
62 e.g.         & \lbr a,b,c\rbr  &  \{a b c\} &	\\
63\hline
64Nil           & \nil /0          &  empty string &	java.util.Collection\\
65 e.g.         & \nil            &  \{\} "" & \\
66\hline
67Struct        & compound      &  list	&	CompoundTerm/Atom\\
68 e.g.         & foo(bar,3)    &  \{foo bar 3\}&\\
69\hline
70Variable      & variable      &  string	&	null\\
71 e.g.         & _             &  _	&	\\
72\hline
73\end{tabular}
74\end{quote}
75
76The EXDR Integer data type is a 32-bit signed integer, the EXDR Long
77data type is a 64-bit signed integer, bigger {\eclipse} integers cannot
78be represented.
79The EXDR Variable type only allows singleton, anonymous variables,
80which means that it is not possible to construct a term where a variable
81occurs in several places simultaneously. The main use of these variables
82is as placeholders for result arguments in remote procedure calls.
83
84
85%----------------------------------------------------------------------
86\section{{\eclipse} primitives to read/write EXDR terms}
87%----------------------------------------------------------------------
88
89The {\eclipse} predicates to create and interpret EXDR-representation
90read from and write directly to {\eclipse} streams. This means that
91EXDR-format can be used readily to communicate via files, pipes,
92sockets, queues etc.
93\begin{description}
94\item[\biptxtref{write_exdr(+Stream, +Term)}{write_exdr/2}
95	{../bips/kernel/ioterm/write_exdr-2.html}]\ \\
96    	This predicate writes terms in exdr format.
97	The type of the generated EXDR-term is the type resulting
98	from the "natural" mapping of the Eclipse terms.
99	Atoms are written as structures of arity 0 (not as strings).
100	Note that all information about variable sharing, variable
101	names and variable attributes is lost in the EXDR representation.
102
103\item[\biptxtref{read_exdr(+Stream, -Term)}{read_exdr/2}
104	{../bips/kernel/ioterm/read_exdr-2.html}]\ \\
105    	This predicate reads exdr format and constructs a
106	corresponding Eclipse term.
107\end{description}
108
109Please refer to chapter \ref{chaptcl} for the Tcl primitives,
110and to chapter \ref{chapjava} for the Java primitives for manipulating
111EXDR terms. 
112
113
114%----------------------------------------------------------------------
115\section{Serialized representation of EXDR terms}
116%----------------------------------------------------------------------
117
118The following is the specification of what is actually send over the
119communication channels.
120This is all the information needed to create new language mappings
121for EXDR terms. This definition corresponds to EXDR_VERSION 2:
122\begin{quote}\begin{verbatim}
123ExdrTerm      ::=   'V' Version CompactFlag? Term
124CompactFlag   ::=   'C'
125Term          ::=   (Integer|Double|String|List|Nil|Struct|Variable)
126Integer       ::=   ('B' <byte> | 'I' XDR_int | 'J' XDR_long)
127Double        ::=   'D' XDR_double
128String        ::=   ('S' Length <byte>* | 'R' Index)
129List          ::=   '[' Term (List|Nil)
130Nil           ::=   ']'
131Struct        ::=   'F' Arity String Term*
132Variable      ::=   '_'
133Length        ::=   XDR_nat
134Index         ::=   XDR_nat
135Arity         ::=   XDR_nat
136Version       ::=   <byte>
137XDR_int       ::=   <4 bytes, msb first>
138XDR_long      ::=   <8 bytes, msb first>
139XDR_double    ::=   <8 bytes, ieee double, exponent first>
140XDR_nat       ::=   ( <8 bits: 1 + seven bits unsigned value>
141                    | XDR_int )                    // >= 0
142\end{verbatim}\end{quote}
143The version byte is 1 or 2.  EXDR version 1 encodings are also valid
144version 2 encodings, and version version 2 decoders can read
145version 1 encoded terms.
146
147XDR_long, XDR_int and byte are all signed integers in two's complement
148representation.
149
150The string reference code R means that the string is the same as the
151Index'th S-encoded string that occurred in the EXDR term earlier.
152The presence of the CompactFlag C in the header indicates that the term
153may actually contain such string references. If the flag is absent, the
154term does not contain any.
155
156%HEVEA\cutend
157