[r2004-06-28 23:10:12 by beppe] added syntax convention and table

Original author: beppe
Date: 2004-06-28 23:10:12+00:00

web/manual/interface.xml

@@ -9,12 +9,12 @@
 <box title="Introduction" link="intro">
 
 <p>
-This page describe the CDuce/OCaml interface. This interface allows
+This page describes the CDuce/OCaml interface. This interface allows
 the programmer to:
 </p>
 <ul>
 <li>call OCaml functions from a CDuce module;</li>
-<li>export a CDuce as an OCaml module, by giving it an explicit OCaml signature.</li>
+<li>export a CDuce model as an OCaml module, by giving it an explicit OCaml signature.</li>
 </ul>
 
 <p>
@@ -40,67 +40,69 @@ see the INSTALL file from the CDuce distribution.
 
 <p>
 The heart of the interface is a mapping from OCaml types to CDuce
-types. An OCaml type <code>t</code> is translated to a CDuce type
-<code>T(t)</code>, which is meant to be isomorphic to <code>t</code>:
-there is a canonical function <code>t</code> &rarr; <code>T(t)</code>
-from OCaml values of type <code>t</code> to CDuce values of type
-<code>T(t)</code>, and another canonical function <code>T(t)</code> &rarr; <code>t</code>.
+types. An OCaml type <code>%%t%%</code> is translated to a CDuce type
+<code>T(%%t%%)</code>, which is meant to be isomorphic to <code>%%t%%</code>:
+there is a canonical function <code>%%t%%</code> &rarr; <code>T(%%t%%)</code>
+from OCaml values of type <code>%%t%%</code> to CDuce values of type
+<code>T(%%t%%)</code>, and another canonical function <code>T(%%t%%)</code> &rarr; <code>%%t%%</code>.
 </p>
 
-<p>
+<ul>
+<li>
 Basic OCaml types <code>char</code>, <code>int</code>, <code>string</code>,
 <code>unit</code> are translated respectively to
 <code>Byte = '\0;'--'\255;'</code>, <code>-1073741824 --
 1073741823</code>, <code>Latin1 = [ Byte* ]</code>, <code>[] = `nil</code>.
-</p>
+</li>
 
-<p>
-Tuple types <code>t1 * ... * tn</code> are translated to nested CDuce
-product types <code>(T(t1),(...,T(tn))...)</code>. A function type
-<code>t -> s</code> is translated to <code>T(t) -> T(s)</code>.
+<li>
+Tuple types <code>%%t%%1 * ... * %%t%%n</code> are translated to nested CDuce
+product types <code>(T(%%t%%1),(...,T(%%t%%n))...)</code>. A function type
+<code>%%t%% -> %%s%%</code> is translated to <code>T(%%t%%) -> T(%%s%%)</code>.
 Labels and optional labels on the argument of the arrow are discarded.
-</p>
+</li>
 
-<p>
-A list type <code>t list</code> is translated to an homogenous
-sequence type <code>[ T(t)* ]</code>.
-</p>
+<li>
+A list type <code>%%t%% list</code> is translated to an homogenous
+sequence type <code>[ T(%%t%%)* ]</code>.
+</li>
 
-<p>
-A variant type with a declaration <code>A1 of t1 | ... | An of
-tn</code> is translated to a type <code>(`A1,T(t1)) | ... |
-(`An,T(tn))</code>. If a constructor <code>Ai</code> has no argument, the resulting
+<li>
+A variant type with a declaration <code>A1 of %%t%%1 | ... | An of
+%%t%%n</code> is translated to a type <code>(`A1,T(%%t%%1)) | ... |
+(`An,T(%%t%%n))</code>. If a constructor <code>Ai</code> has no argument, the resulting
 term is <code>`Ai</code>, not <code>(`Ai,[])</code>.
 Polymorphic variant types are treated similarly.
-</p>
+</li>
 
-<p>
-A record type with a declaration <code>{ l1 : t1; ...; ln : tn
-}</code> is translated to a closed record type <code>{| l1 = T(t1);
-... ; ln = T(tn) |}</code>. Mutable fields are just copied.
-</p>
+<li>
+A record type with a declaration <code>{ l1 : %%t%%1; ...; ln : %%t%%n
+}</code> is translated to a closed record type <code>{| l1 = T(%%t%%1);
+... ; ln = T(%%t%%n) |}</code>. Mutable fields are just copied.
+</li>
 
-<p>
+<li>
 Private variant and record types are treated correctly: the interface
 never tries to generate OCaml values of these types, but it will happily
 translate them to CDuce values.
-</p>
+</li>
 
-<p>
-A reference type <code>t ref</code> is translated to the CDuce
-reference type <code>ref T(t)</code>. When converting a Caml reference
+<li>
+A reference type <code>%%t%% ref</code> is translated to the CDuce
+reference type <code>ref T(%%t%%)</code>. When converting a Caml reference
 to CDuce, the operation (set,get) on the resulting reference refers
 to the original reference. However, when converting a CDuce reference
 to OCaml, the content of the reference is fetched (set), and a fresh
 OCaml reference is created (copy semantics).
-</p>
+</li>
 
-<p>
+<li>
 The type <code>CDuce_all.Value.t</code> is translated to the CDuce
 type <code>Any</code>. The corresponding translation functions are the
 identity. This can be used to avoid multiple copies when translating
 a complex value back and forth between CDuce and OCaml.
-</p>
+</li>
+</ul>
 
 <p>
 The canonical translation is summarized in the following box
@@ -108,20 +110,20 @@ The canonical translation is summarized in the following box
 
 <sample><![CDATA[
 T($$bool$$)      =  Bool
-T($$char$$)      =  Char
+T($$char$$)      =  Byte
 T($$int$$)       =  -1073741824 -- 1073741823
 T($$string$$)    =  Latin1
 T($$unit$$)      =  []
-T($$%%t%%$$ $$*$$ $$%%u%%$$)     =  ( T($$%%t%%$$) , T($$%%u%%$$) )
+T($$%%t1%%$$$$*$$...$$*$$$$%%tn%%$$) =  ( T($$%%t1%%$$), (...,T($$%%tn%%$$))... )
 T($$%%t%%$$ $$->$$ $$%%u%%$$)    =  T($$%%t%%$$) -> T($$%%u%%$$)
 T($$%%t%%$$ $$|$$ $$%%u%%$$)     =  T($$%%t%%$$) | T($$%%u%%$$)
 T($$%%t%%$$ $$list$$)    =  [ T($$%%t%%$$)* ]
+T($$%%t%%$$ $$ref$$)     =  ref T($$%%t%%$$)  
 T($$A$$)         =  `A
 T($$A of$$ $$%%t%%$$)    =  ( `A, T($$%%t%%$$) )
                 | { u : T($$%%t%%$$) }       if in contravariant (argument) position 
 T($${ u :$$ $$%%t%%$$ $$}$$) = <
                 | {| u : T($$%%t%%$$) |}     if in covariant (result) position 
-
 ]]></sample>
 
 <p>