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