/usr/share/doc/libatd-ocaml-dev/atd-manual.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<TITLE>ATD 
Adjustable Type Definitions 
release 1.0.1
</TITLE>

<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.10">
<STYLE type="text/css">
.li-itemize{margin:1ex 0ex;}
.li-enumerate{margin:1ex 0ex;}
.dd-description{margin:0ex 0ex 1ex 4ex;}
.dt-description{margin:0ex;}
.toc{list-style:none;}
.thefootnotes{text-align:left;margin:0ex;}
.dt-thefootnotes{margin:0em;}
.dd-thefootnotes{margin:0em 0em 0em 2em;}
.footnoterule{margin:1em auto 1em 0px;width:50%;}
.caption{padding-left:2ex; padding-right:2ex; margin-left:auto; margin-right:auto}
.title{margin:2ex auto;text-align:center}
.center{text-align:center;margin-left:auto;margin-right:auto;}
.flushleft{text-align:left;margin-left:0ex;margin-right:auto;}
.flushright{text-align:right;margin-left:auto;margin-right:0ex;}
DIV TABLE{margin-left:inherit;margin-right:inherit;}
PRE{text-align:left;margin-left:0ex;margin-right:auto;}
BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;}
TD P{margin:0px;}
.boxed{border:1px solid black}
.textboxed{border:1px solid black}
.vbar{border:none;width:2px;background-color:black;}
.hbar{border:none;height:2px;width:100%;background-color:black;}
.hfill{border:none;height:1px;width:200%;background-color:black;}
.vdisplay{border-collapse:separate;border-spacing:2px;width:auto; empty-cells:show; border:2px solid red;}
.vdcell{white-space:nowrap;padding:0px;width:auto; border:2px solid green;}
.display{border-collapse:separate;border-spacing:2px;width:auto; border:none;}
.dcell{white-space:nowrap;padding:0px;width:auto; border:none;}
.dcenter{margin:0ex auto;}
.vdcenter{border:solid #FF8000 2px; margin:0ex auto;}
.minipage{text-align:left; margin-left:0em; margin-right:auto;}
.marginpar{border:solid thin black; width:20%; text-align:left;}
.marginparleft{float:left; margin-left:0ex; margin-right:1ex;}
.marginparright{float:right; margin-left:1ex; margin-right:0ex;}
.theorem{text-align:left;margin:1ex auto 1ex 0ex;}
.part{margin:2ex auto;text-align:center}
</STYLE>
</HEAD>
<BODY >
<!--HEVEA command line is: hevea -fix atd-manual -->
<!--CUT DEF section 1 --><TABLE CLASS="title"><TR><TD><H1 CLASS="titlemain">ATD<BR>
<SPAN STYLE="font-variant:small-caps">Adjustable Type Definitions</SPAN><BR>
release 1.0.1</H1><H3 CLASS="titlerest">Martin Jambon<BR>
© 2010 MyLife</H3></TD></TR>
</TABLE><!--TOC section Contents-->
<H2 CLASS="section"><!--SEC ANCHOR -->Contents</H2><!--SEC END --><UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc1">1  Introduction</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc2">1.1  Scope</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc3">1.2  Language overview</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc4">1.3  Editing and validating ATD files</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc5">2  ATD language</A>
<UL CLASS="toc"><LI CLASS="li-toc">
<A HREF="#htoc6">2.1  Notations</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc7">2.2  Lexical rules</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc8">2.3  Grammar</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc9">2.4  Predefined type names</A>
</LI><LI CLASS="li-toc"><A HREF="#htoc10">2.5  Shared values</A>
</LI></UL>
</LI><LI CLASS="li-toc"><A HREF="#htoc11">3  OCaml <TT>atd</TT> library</A>
</LI></UL><!--TOC section Introduction-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc1">1</A>  Introduction</H2><!--SEC END --><P>ATD stands for Adjustable Type Definitions.</P><PRE>
<FONT COLOR="#990000">(* This is a sample ATD file *)</FONT>

<FONT COLOR="#007F00">type</FONT> profile = {
  id : string;
  email : string;
  ~email_validated : bool;
  name : string;
  ?real_name : string option;
  ~about_me : string list;
  ?gender : gender option;
  ?date_of_birth : date option;
}

<FONT COLOR="#007F00">type</FONT> gender = [ <FONT COLOR="#0033CC">Female</FONT> <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Male</FONT> ]

<FONT COLOR="#007F00">type</FONT> date = {
  year : int;
  month : int;
  day : int;
}
</PRE><P>ATD is a language for defining data types across multiple programming
languages and multiple data formats.
That&#X2019;s it.</P><P>We provide an OCaml library that provides a parser and a collection of
tools that make it easy to write data validators and code generators
based on ATD definitions.</P><P>Unlike the big &#X201C;frameworks&#X201D; that provide &#X201C;everything&#X201D; in one
monolithic package, we split the problem of data exchange into logical
modules and ATD is one of them.
In particular, we acknowledge that the following pieces have
little in common and should be defined and implemented separately:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
data type specifications
</LI><LI CLASS="li-itemize">transport protocols
</LI><LI CLASS="li-itemize">serialization formats
</LI></UL><P>Ideally we want just one single language for defining data types and
it should accomodate all programming languages and data formats. ATD
can play this role, but its OCaml implementation makes it
particularly easy to translate ATD specifications into other interface
definition languages if needed.</P><P>It is however much harder to imagine that a single transport protocol and
a single serialization format would ever become the only ones used.
A reader from the future might wonder why we are even considering
defining a transport protocol and a serialization format together. 
This has been a widespread practice at least until the beginning of
the 21st century (ONC RPC, ICE, Thrift, etc.). For mysterious reasons,
people somehow became convinced that calls to remote services should
be made to mimic internal function calls, pretending that nothing
really bad could happen on the way between the caller and the remote
service. Well, I don&#X2019;t let my 3-old daughter go to school by herself
because the definition of the external world is precisely that it is
unsafe.</P><P>Data input is by definition unsafe. A program whose internal data is
corrupted should abort but a failed attempt to read external data
should not cause a program to abort. On the contrary, a program should
be very resistent to all forms of data corruption and attacks and
provide the best diagnosis possible when problems with external data
occur.</P><P>Because data exchange is critical and involves multiple partners, we
depart from magic programming language-centric or company-centric
approaches. We define ATD, a data type definition language
designed for maximum expressivity, compatibility across languages and
static type checking of programs using such data.</P><!--TOC subsection Scope-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc2">1.1</A>  Scope</H3><!--SEC END --><P>ATD offers a core syntax for type definitions, i.e. an idealized view
of the structure of data. Types are mapped to each programming
language or data format using language-specific conventions.
Annotations can complete the type definitions in
order to specify options for a particular language.
Annotations are placed in angle brackets after the element they refer to:</P><PRE>
<FONT COLOR="#007F00">type</FONT> profile = {
  id : int &lt;ocaml repr=<FONT COLOR="#AA4444">"int64"</FONT>&gt;;
    <FONT COLOR="#990000">(*</FONT>
<FONT COLOR="#990000">       An int here will map to an OCaml int64 instead of</FONT>
<FONT COLOR="#990000">       OCaml&#X2019;s default int type.</FONT>
<FONT COLOR="#990000">       Other languages than OCaml will use their default int type.</FONT>
<FONT COLOR="#990000">    *)</FONT>

  age : int;
    <FONT COLOR="#990000">(* No annotation here, the default int type will be used. *)</FONT>
}
</PRE><P>ATD supports:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
the following atomic types: bool, int, float, string and unit;
</LI><LI CLASS="li-itemize">built-in list and option types;
</LI><LI CLASS="li-itemize">records aka structs with a syntax for optional fields with or
with default;
</LI><LI CLASS="li-itemize">tuples;
</LI><LI CLASS="li-itemize">sum types aka variant types, algebraic data types or tagged unions;
</LI><LI CLASS="li-itemize">parametrized types;
</LI><LI CLASS="li-itemize">inheritance for both records and sum types;
</LI><LI CLASS="li-itemize">abstract types;
</LI><LI CLASS="li-itemize">arbitrary annotations.
</LI></UL><P>ATD by design does not support:
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
function types, function signatures or method signatures;
</LI><LI CLASS="li-itemize">a syntax to represent values;
</LI><LI CLASS="li-itemize">a syntax for submodules.
</LI></UL><!--TOC subsection Language overview-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc3">1.2</A>  Language overview</H3><!--SEC END --><P>ATD was strongly inspired by the type system of ML and OCaml. Such a
type system allows static type checking and type inference, properties
which contribute to the safety and conciseness of the language.</P><P>Unlike mainstream languages like Java, C++, C# or Python to name a
few, languages such as Haskell or OCaml offer sum types,
also known as algebraic data types or variant types. These allow to
specify that an object is of one kind or another without ever
performing dynamic casts.</P><PRE>
<FONT COLOR="#990000">(* Example of a sum type in ATD. The vertical bar reads &#X2018;or&#X2019;. *)</FONT>
<FONT COLOR="#007F00">type</FONT> shape = [
    <FONT COLOR="#0033CC">Square</FONT> <FONT COLOR="#007F00">of</FONT> float               <FONT COLOR="#990000">(* argument: side length *)</FONT>
  <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Rectangle</FONT> <FONT COLOR="#007F00">of</FONT> (float * float)  <FONT COLOR="#990000">(* argument: width and height *)</FONT>
  <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Circle</FONT> <FONT COLOR="#007F00">of</FONT> float               <FONT COLOR="#990000">(* argument: radius *)</FONT>
  <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Dot</FONT>                           <FONT COLOR="#990000">(* no argument *)</FONT>
]
</PRE><P>A notable example of sum types is the predefined option type.
An object of an option type contains either one value of a given type 
or nothing. We could define our own <TT>int_option</TT> type as follows:</P><PRE>
<FONT COLOR="#007F00">type</FONT> int_option = [ <FONT COLOR="#0033CC">None</FONT> <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Some</FONT> <FONT COLOR="#007F00">of</FONT> int ]
</PRE><P>ATD supports parametrized types also known as generics in Java or
templates in C++. We could define our own generic option type as
follows:</P><PRE>
<FONT COLOR="#007F00">type</FONT> &#X2019;a opt = [ <FONT COLOR="#0033CC">None</FONT> <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Some</FONT> <FONT COLOR="#007F00">of</FONT> &#X2019;a ]
  <FONT COLOR="#990000">(* &#X2019;a denotes a type parameter. *)</FONT>

<FONT COLOR="#007F00">type</FONT> opt_int = int opt
  <FONT COLOR="#990000">(* equivalent to int_option defined in the previous example *)</FONT>

<FONT COLOR="#007F00">type</FONT> opt_string = string opt
  <FONT COLOR="#990000">(* same with string instead of int *)</FONT>
</PRE><P>In practice we shall use the predefined option type.
The option type is fundamentally different from nullable objects since
the latter don&#X2019;t allow values that would have type <TT>&#X2019;a option option</TT>.</P><P>ATD also support product types. They come in two forms: tuples and
records:</P><PRE>
<FONT COLOR="#007F00">type</FONT> tuple_example = (string * int)

<FONT COLOR="#007F00">type</FONT> record_example = {
  name : string;
  age : int;
}
</PRE><P>Although tuples in theory are not more expressive than
records, they are much more concise and languages that support them
natively usually do not require type definitions.</P><P>Finally, ATD supports multiple inheritance which is a simple mechanism
for adding fields to records or variants to sum types:</P><PRE>
<FONT COLOR="#007F00">type</FONT> builtin_color = [
    <FONT COLOR="#0033CC">Red</FONT> <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Green</FONT> <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Blue</FONT> <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Yellow</FONT>
  <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Purple</FONT> <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Black</FONT> <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">White</FONT>
]

<FONT COLOR="#007F00">type</FONT> rgb = (float * float * float)
<FONT COLOR="#007F00">type</FONT> cmyk = (float * float * float * float)

<FONT COLOR="#990000">(* Inheritance of variants *)</FONT>
<FONT COLOR="#007F00">type</FONT> color = [
    <FONT COLOR="#007F00">inherit</FONT> builtin_color
  <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Rgb</FONT> <FONT COLOR="#007F00">of</FONT> rgb
  <FONT COLOR="#77AAAA">|</FONT> <FONT COLOR="#0033CC">Cmyk</FONT> <FONT COLOR="#007F00">of</FONT> cmyk
]
</PRE><PRE>
<FONT COLOR="#007F00">type</FONT> basic_profile = {
  id : string;
  name : string;
}

<FONT COLOR="#990000">(* Inheritance of record fields *)</FONT>
<FONT COLOR="#007F00">type</FONT> full_profile = {
  <FONT COLOR="#007F00">inherit</FONT> basic_profile;
  date_of_birth : (int * int * int) option;
  street_address1 : string option;
  street_address2 : string option;
  city : string option;
  zip_code : string option;
  state : string option;
}
</PRE><!--TOC subsection Editing and validating ATD files-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc4">1.3</A>  Editing and validating ATD files</H3><!--SEC END --><P>The extension for ATD files is <TT>.atd</TT>. Editing ATD files is best
achieved using an OCaml-friendly editor since the ATD syntax is vastly
compatible with OCaml and uses a subset of OCaml&#X2019;s keywords.</P><P>Emacs users can use caml-mode or tuareg-mode to edit ATD files.
Adding the following line to the <TT>~/.emacs</TT> file will
automatically use tuareg-mode when opening a file with a <TT>.atd</TT>
extension:
</P><PRE CLASS="verbatim">(add-to-list 'auto-mode-alist '("\\.atd\\'" . tuareg-mode))
</PRE><P>The syntax of an ATD file can be checked with the program
<TT>atdcat</TT> provided with the OCaml library <TT>atd</TT>.
<TT>atdcat</TT> pretty-prints its input data, optionally after some
transformations such as monomorphization or inheritance.
Here is the output of <TT>atdcat -help</TT>:
</P><PRE CLASS="verbatim">Usage: atdcat FILE
  -x 
          make type expressions monomorphic
  -xk 
          keep parametrized type definitions and imply -x.
          Default is to return only monomorphic type definitions
  -xd 
          debug mode implying -x
  -i 
          expand all `inherit' statements
  -if 
          expand `inherit' statements in records
  -iv 
          expand `inherit' statements in sum types
  -ml &lt;name&gt;
          output the ocaml code of the ATD abstract syntax tree
  -version 
          print the version of atd and exit
  -help  Display this list of options
  --help  Display this list of options
</PRE><!--TOC section ATD language-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc5">2</A>  ATD language</H2><!--SEC END --><P>This is a precise description of the syntax of the ATD language, not a
tutorial.</P><!--TOC subsection Notations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc6">2.1</A>  Notations</H3><!--SEC END --><P>Lexical and grammatical rules are expressed using a BNF-like syntax.
Graphical terminal symbols use <FONT COLOR="#AA4444"><TT>unquoted strings in typewriter font</TT></FONT>.
Non-graphical characters use their official uppercase ASCII name such
as LF for the newline character or SPACE for the space character.
Non-terminal symbols use the regular font and link to their
definition. Parentheses are used for grouping.</P><P>The following postfix operators are used to specify repeats:</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD ALIGN=left NOWRAP>x*</TD><TD ALIGN=left NOWRAP>0, 1 or more occurrences of x</TD></TR>
<TR><TD ALIGN=left NOWRAP>x?</TD><TD ALIGN=left NOWRAP>0 or 1 occurrence of x</TD></TR>
<TR><TD ALIGN=left NOWRAP>x+</TD><TD ALIGN=left NOWRAP>1 or more occurrences of x</TD></TR>
</TABLE><!--TOC subsection Lexical rules-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc7">2.2</A>  Lexical rules</H3><!--SEC END --><P>ATD does not enforce a particular character encoding other than ASCII
compatibility. Non-ASCII text and data found in annotations and
in comments may contain arbitrary bytes in the non-ASCII range 128-255
without escaping. The UTF-8 encoding is however strongly recommended
for all text. The use of hexadecimal or decimal escape sequences is
recommended for binary data.</P><P>An ATD lexer splits its input into a stream of <A HREF="#token">token</A>s,
discarding white<A HREF="#space">space</A> and <A HREF="#comment">comment</A>s.</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD ALIGN=right NOWRAP><A NAME="token">token</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><A HREF="#keyword">keyword</A> 
| <A HREF="#lident">lident</A>
| <A HREF="#uident">uident</A>
| <A HREF="#tident">tident</A>
| <A HREF="#string">string</A></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="ignorable">ignorable</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><A HREF="#space">space</A> | <A HREF="#comment">comment</A></TD><TD ALIGN=left NOWRAP><I>discarded</I></TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="space">space</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP>SPACE | TAB | CR | LF</TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="blank">blank</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP>SPACE | TAB</TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="comment">comment</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>(*</TT></FONT> (<A HREF="#comment">comment</A> | <A HREF="#string">string</A> | byte)*
<FONT COLOR="#AA4444"><TT>*)</TT></FONT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="lident">lident</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP>(<A HREF="#lower">lower</A> 
| <FONT COLOR="#AA4444"><TT>_</TT></FONT> <A HREF="#identchar">identchar</A>) <A HREF="#identchar">identchar</A>*</TD><TD ALIGN=left NOWRAP><I>lowercase identifier</I></TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="uident">uident</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><A HREF="#upper">upper</A> <A HREF="#identchar">identchar</A>*</TD><TD ALIGN=left NOWRAP><I>uppercase identifier</I></TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="tident">tident</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>&#X2019;</TT></FONT> <A HREF="#lident">lident</A></TD><TD ALIGN=left NOWRAP><I>type parameter</I></TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="lower">lower</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>a</TT></FONT>...<FONT COLOR="#AA4444"><TT>z</TT></FONT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="upper">upper</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>A</TT></FONT>...<FONT COLOR="#AA4444"><TT>Z</TT></FONT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="identchar">identchar</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><A HREF="#upper">upper</A> | <A HREF="#lower">lower</A> | <A HREF="#digit">digit</A>
| <FONT COLOR="#AA4444"><TT>_</TT></FONT> | <FONT COLOR="#AA4444"><TT>&#X2019;</TT></FONT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="string">string</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>"</TT></FONT> <A HREF="#substring">substring</A>* <FONT COLOR="#AA4444"><TT>"</TT></FONT></TD><TD ALIGN=left NOWRAP><I>string literal, used in annotations</I></TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="substring">substring</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>\\</TT></FONT></TD><TD ALIGN=left NOWRAP><I>single backslash</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>\</TT></FONT><FONT COLOR="#AA4444"><TT>"</TT></FONT></TD><TD ALIGN=left NOWRAP><I>double quote</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>\</TT></FONT><FONT COLOR="#AA4444"><TT>x</TT></FONT> <A HREF="#hex">hex</A> <A HREF="#hex">hex</A></TD><TD ALIGN=left NOWRAP><I>single byte in hexadecimal notation</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>\</TT></FONT>
<A HREF="#digit">digit</A> <A HREF="#digit">digit</A> <A HREF="#digit">digit</A></TD><TD ALIGN=left NOWRAP><I>single byte in decimal notation</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>\</TT></FONT><FONT COLOR="#AA4444"><TT>n</TT></FONT></TD><TD ALIGN=left NOWRAP><I>LF</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>\</TT></FONT><FONT COLOR="#AA4444"><TT>r</TT></FONT></TD><TD ALIGN=left NOWRAP><I>CR</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>\</TT></FONT><FONT COLOR="#AA4444"><TT>t</TT></FONT></TD><TD ALIGN=left NOWRAP><I>TAB</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>\</TT></FONT><FONT COLOR="#AA4444"><TT>b</TT></FONT></TD><TD ALIGN=left NOWRAP><I>BS</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>\</TT></FONT> CR? LF blank*</TD><TD ALIGN=left NOWRAP><I>discarded</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP>not-backslash</TD><TD ALIGN=left NOWRAP><I>any byte except </I><I><FONT COLOR="#AA4444"><TT>\</TT></FONT></I><I> or </I><I><FONT COLOR="#AA4444"><TT>"</TT></FONT></I></TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="digit">digit</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>0</TT></FONT>...<FONT COLOR="#AA4444"><TT>9</TT></FONT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="hex">hex</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>0</TT></FONT>...<FONT COLOR="#AA4444"><TT>9</TT></FONT> | <FONT COLOR="#AA4444"><TT>a</TT></FONT>...<FONT COLOR="#AA4444"><TT>f</TT></FONT> |
<FONT COLOR="#AA4444"><TT>A</TT></FONT>...<FONT COLOR="#AA4444"><TT>F</TT></FONT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="keyword">keyword</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>(</TT></FONT> | <FONT COLOR="#AA4444"><TT>)</TT></FONT> | <FONT COLOR="#AA4444"><TT>[</TT></FONT>
| <FONT COLOR="#AA4444"><TT>]</TT></FONT> | <FONT COLOR="#AA4444"><TT>{</TT></FONT> | <FONT COLOR="#AA4444"><TT>}</TT></FONT>
| <FONT COLOR="#AA4444"><TT>&lt;</TT></FONT> | <FONT COLOR="#AA4444"><TT>&gt;</TT></FONT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>&nbsp;</TD><TD ALIGN=left NOWRAP>| <FONT COLOR="#AA4444"><TT>;</TT></FONT> | <FONT COLOR="#AA4444"><TT>,</TT></FONT> | <FONT COLOR="#AA4444"><TT>:</TT></FONT> | <FONT COLOR="#AA4444"><TT>*</TT></FONT>
| <FONT COLOR="#AA4444"><TT>|</TT></FONT> | <FONT COLOR="#AA4444"><TT>=</TT></FONT> | <FONT COLOR="#AA4444"><TT>?</TT></FONT> | <FONT COLOR="#AA4444"><TT>~</TT></FONT></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>&nbsp;</TD><TD ALIGN=left NOWRAP>| <FONT COLOR="#AA4444"><TT>type</TT></FONT> | <FONT COLOR="#AA4444"><TT>of</TT></FONT> | <FONT COLOR="#AA4444"><TT>inherit</TT></FONT></TD><TD ALIGN=left NOWRAP><I>all keywords</I></TD></TR>
</TABLE><!--TOC subsection Grammar-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc8">2.3</A>  Grammar</H3><!--SEC END --><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD ALIGN=right NOWRAP><A NAME="module">module</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><A HREF="#annot">annot</A>* <A HREF="#typedef">typedef</A>*</TD><TD ALIGN=left NOWRAP><I>entry point</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>
<A NAME="annot">annot</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>&lt;</TT></FONT> <A HREF="#lident">lident</A> annot-field* <FONT COLOR="#AA4444"><TT>&gt;</TT></FONT></TD><TD ALIGN=left NOWRAP><I>annotation</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>
<A NAME="annot-field">annot-field</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP>(<A HREF="#lident">lident</A> (<FONT COLOR="#AA4444"><TT>=</TT></FONT> <A HREF="#string">string</A>)?)</TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP>
<A NAME="typedef">typedef</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>type</TT></FONT> <A HREF="#params">params</A>? lident annot
<FONT COLOR="#AA4444"><TT>=</TT></FONT> <A HREF="#expr">expr</A></TD><TD ALIGN=left NOWRAP><I>type definition</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>
<A NAME="params">params</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><A HREF="#tident">tident</A></TD><TD ALIGN=left NOWRAP>one parameter</TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>(</TT></FONT> <A HREF="#tident">tident</A> (<FONT COLOR="#AA4444"><TT>,</TT></FONT> <A HREF="#tident">tident</A>)+ <FONT COLOR="#AA4444"><TT>)</TT></FONT></TD><TD ALIGN=left NOWRAP><I>two or more parameters</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>
<A NAME="expr">expr</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><A HREF="#expr-body">expr-body</A> <A HREF="#annot">annot</A>*</TD><TD ALIGN=left NOWRAP><I>type expression</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><A HREF="#tident">tident</A></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP> 
<A NAME="expr-body">expr-body</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><A HREF="#args">args</A>? <A HREF="#lident">lident</A></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>(</TT></FONT>
<A HREF="#cell">cell</A> (<FONT COLOR="#AA4444"><TT>*</TT></FONT> <A HREF="#cell">cell</A>)*
<FONT COLOR="#AA4444"><TT>)</TT></FONT></TD><TD ALIGN=left NOWRAP><I>tuple type</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>{</TT></FONT>
((<A HREF="#field">field</A> (<FONT COLOR="#AA4444"><TT>;</TT></FONT> <A HREF="#field">field</A>)*) <FONT COLOR="#AA4444"><TT>;</TT></FONT>?)?
<FONT COLOR="#AA4444"><TT>}</TT></FONT></TD><TD ALIGN=left NOWRAP><I>record type</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>[</TT></FONT>
(<FONT COLOR="#AA4444"><TT>|</TT></FONT>? <A HREF="#variant">variant</A> (<FONT COLOR="#AA4444"><TT>|</TT></FONT> <A HREF="#variant">variant</A>)*)?
<FONT COLOR="#AA4444"><TT>]</TT></FONT></TD><TD ALIGN=left NOWRAP><I>sum type</I></TD></TR>
<TR><TD ALIGN=right NOWRAP><A NAME="args">args</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><A HREF="#expr">expr</A></TD><TD ALIGN=left NOWRAP><I>one argument</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>(</TT></FONT> <A HREF="#expr">expr</A> (<FONT COLOR="#AA4444"><TT>,</TT></FONT> <A HREF="#expr">expr</A>)+ <FONT COLOR="#AA4444"><TT>)</TT></FONT></TD><TD ALIGN=left NOWRAP><I>two or more arguments</I></TD></TR>
<TR><TD ALIGN=right NOWRAP>
<A NAME="cell">cell</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP>(<A HREF="#annot">annot</A>+ <FONT COLOR="#AA4444"><TT>:</TT></FONT>)? <A HREF="#expr">expr</A></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP>
<A NAME="field">field</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP>(<FONT COLOR="#AA4444"><TT>?</TT></FONT> | <FONT COLOR="#AA4444"><TT>~</TT></FONT>)? <A HREF="#lident">lident</A>
<FONT COLOR="#AA4444"><TT>=</TT></FONT> <A HREF="#expr">expr</A></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>inherit</TT></FONT> <A HREF="#expr">expr</A></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP>
<A NAME="variant">variant</A></TD><TD ALIGN=center NOWRAP>::=</TD><TD ALIGN=left NOWRAP><A HREF="#uident">uident</A> <A HREF="#annot">annot</A>* <FONT COLOR="#AA4444"><TT>of</TT></FONT> <A HREF="#expr">expr</A></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><A HREF="#uident">uident</A> <A HREF="#annot">annot</A>*</TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD ALIGN=right NOWRAP>&nbsp;</TD><TD ALIGN=center NOWRAP>|</TD><TD ALIGN=left NOWRAP><FONT COLOR="#AA4444"><TT>inherit</TT></FONT> <A HREF="#expr">expr</A></TD><TD ALIGN=left NOWRAP>&nbsp;</TD></TR>
</TABLE><!--TOC subsection Predefined type names-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc9">2.4</A>  Predefined type names</H3><!--SEC END --><P>The following types are considered predefined and may not be
redefined.</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD ALIGN=left NOWRAP>Type name</TD><TD ALIGN=left NOWRAP>Intended use</TD></TR>
<TR><TD CLASS="hbar" COLSPAN=2></TD></TR>
<TR><TD ALIGN=left NOWRAP><TT>unit</TT></TD><TD ALIGN=left NOWRAP>Type of just one value, useful with parametrized types</TD></TR>
<TR><TD ALIGN=left NOWRAP><TT>bool</TT></TD><TD ALIGN=left NOWRAP>Boolean</TD></TR>
<TR><TD ALIGN=left NOWRAP><TT>int</TT></TD><TD ALIGN=left NOWRAP>Integer</TD></TR>
<TR><TD ALIGN=left NOWRAP><TT>float</TT></TD><TD ALIGN=left NOWRAP>Floating-point number</TD></TR>
<TR><TD ALIGN=left NOWRAP><TT>string</TT></TD><TD ALIGN=left NOWRAP>Sequence of bytes or characters</TD></TR>
<TR><TD ALIGN=left NOWRAP><TT>&#X2019;a option</TT></TD><TD ALIGN=left NOWRAP>Zero or one element</TD></TR>
<TR><TD ALIGN=left NOWRAP><TT>&#X2019;a list</TT></TD><TD ALIGN=left NOWRAP>Collection or sequence of elements</TD></TR>
<TR><TD ALIGN=left NOWRAP><TT>&#X2019;a shared</TT></TD><TD ALIGN=left NOWRAP>Values for which sharing must be preserved</TD></TR>
<TR><TD ALIGN=left NOWRAP><TT>abstract</TT></TD><TD ALIGN=left NOWRAP>Type defined elsewhere</TD></TR>
</TABLE><!--TOC subsection Shared values-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc10">2.5</A>  Shared values</H3><!--SEC END --><P>ATD supports a special type <I>x</I> <TT>shared</TT> where <I>x</I> can be 
any monomorphic type expression.
It allows notably to represent cyclic values and to enforce that cycles
are preserved during transformations such as serialization.</P><PRE>
<FONT COLOR="#990000">(* Example of a simple graph type *)</FONT>
<FONT COLOR="#007F00">type</FONT> shared_node = node shared <FONT COLOR="#990000">(* sharing point *)</FONT>
<FONT COLOR="#007F00">type</FONT> graph = shared_node list
<FONT COLOR="#007F00">type</FONT> node = {
  label : string;
  neighbors : shared_node list;
}
</PRE><P>Two shared values that are physically identical must remain physically 
identical after any translation from one data format to another.</P><P>Each occurrence of a <TT>shared</TT> type expression in the ATD
source definition defines its own sharing point.
Therefore the following attempt at defining a graph type will not
preserve cycles because two sharing points are defined:</P><PRE>
<FONT COLOR="#990000">(* Incorrect definition of a graph type *)</FONT>
<FONT COLOR="#007F00">type</FONT> node = {
  label : string;
  neighbors : node shared <FONT COLOR="#990000">(* sharing point 1 *)</FONT> list;
}

<FONT COLOR="#990000">(* Second occurrence of "shared", won&#X2019;t preserve cycles! *)</FONT>
<FONT COLOR="#007F00">type</FONT> graph = node shared <FONT COLOR="#990000">(* sharing point 2 *)</FONT> list
</PRE><P>There is actually a way of having multiple <TT>shared</TT>
type expressions using the same sharing point
but this feature is designed for code generators and
should not be used in handwritten ATD definitions.
The technique consists in providing an annotation of the form
<TT>&lt;share id=</TT><TT><I>x</I></TT><TT>&gt;</TT> where <I>x</I> is any string identifying the sharing
point.
The graph example can be rewritten correctly as:</P><PRE>
<FONT COLOR="#007F00">type</FONT> node = {
  label : string;
  neighbors : node shared &lt;share id=<FONT COLOR="#AA4444">"1"</FONT>&gt; list;
}

<FONT COLOR="#007F00">type</FONT> graph = node shared &lt;share id=<FONT COLOR="#AA4444">"1"</FONT>&gt; list
</PRE><!--TOC section OCaml <TT>atd</TT> library-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc11">3</A>  OCaml <TT>atd</TT> library</H2><!--SEC END --><P>The documentation for the <TT>atd</TT> library is available in HTML
form at <A HREF="http://oss.wink.com/atd/atd-1.0.1/odoc/index.html"><TT>http://oss.wink.com/atd/atd-1.0.1/odoc/index.html</TT></A>.

</P><!--CUT END -->
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<HR SIZE=2><BLOCKQUOTE CLASS="quote"><EM>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</EM><A HREF="http://hevea.inria.fr/index.html"><EM>H</EM><EM><FONT SIZE=2><sup>E</sup></FONT></EM><EM>V</EM><EM><FONT SIZE=2><sup>E</sup></FONT></EM><EM>A</EM></A><EM>.</EM></BLOCKQUOTE></BODY>
</HTML>
libatd-ocaml-dev 1.0.1-1build2 / usr / share / doc / libatd-ocaml-dev / atd-manual.html
