[r2004-03-09 21:40:29 by jdemouth] A beginning of manual page for interfacing CDuce with OCaml.

Original author: jdemouth
Date: 2004-03-09 21:40:29+00:00

web/manual/interface.xml

+<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
+<page name="interfacing_ocaml">
+
+<title>Interfacing CDuce with OCaml</title>
+
+<box title="Introduction" link="intro">
+
+<p>
+When you have to write a big program you always need to manage some 
+persistent datas. A really elegant and witespread technic, to fulfill
+this goal, is to use XML based documents. And a really safe and robust
+way to treat XML files is to write a small program in CDuce. In this,
+document, we will present a way to call CDuce functions from OCaml to
+let you couple the power of CDuce to the power of OCaml.
+</p>
+
+<p>
+This page explains how to write an interface file between CDuce and 
+OCaml and call CDuce code from OCaml one.
+</p>
+
+</box>
+
+<box title="The interface file" link="interface">
+
+<p>
+As you have probably seen CDuce uses regular expression based pattern-
+matching. This feature, combined with others, makes CDuce translation to
+OCaml a bit hard. That's why you are asked to provide an OCaml interface
+file to help the CDuce compiler in producing needed code to let you call
+CDuce from your ML programs.
+</p>
+
+<p>
+This file must contain declarations of all your functions and types you
+want to export from CDuce code.
+</p>
+
+<p>
+By example, consider the following CDuce code, written in file foo.cd:
+</p>
+
+<sample><![CDATA[
+type %%ML_int%% = -1073741824 -- 1073741823
+
+let %%f%% ( %%Int%% -> %%ML_int%% )
+   %%x%% & %%ML_int%% -> %%x%% 
+ | %%_%% -> raise "Overflow"
+]]</sample>
+
+<p>
+And now the OCaml code in file, foo.mli:
+</p>
+
+<sample><![CDATA[
+val %%f%% : %%int%% -> %%int%%
+]]</sample>
+
+<p>
+The function declared in foo.mli is the interface between CDuce and OCaml,
+you are free to call it from any of your OCaml programs, as in:
+</p>
+
+<sample>![CDATA[
+let () = 
+  if Foo.f 8 <> 8 then failwith "Error"
+]]</sample>
+
+<p>
+Note that there are two rules to respect when creating your interface file:
+</p>
+<ul>
+  <li>
+    Every function defined in your OCaml file (<code>.mli</code>) has to
+    be defined in your CDuce file. Whereas the opposite is absolutely not
+    needed (you can have much more functions in your CDuce file than in
+    your OCaml one.
+  </li>
+  <li>
+    Every function defined in your OCaml file has to be a subtype of your
+    CDuce function. By example, the previous example respects this rule (
+    <code>int</code> is a subtype of <code>Int</code> and <ML_int> and
+    <code>int</code> are equal, so <code>int -> int</code> is effectively
+    a subtype of <code>Int -> ML_int</code>). But <code>int -> int</code>
+    is not a subtype of <code>Int -> Int</code> and will be rejected by
+    the compiler.
+  </li>
+</ul>
+
+</box>
+
+<box title="Translation function" link="trans">
+
+<p>
+To know if a OCaml type is a subtype of a CDuce one, it is extremely simple,
+you just have to follow the translation function, <code>T</code>, given by:
+</p>
+
+<sample>![CDATA[
+T(%%bool%%)   = %%Bool%%
+T(%%char%%)   = %%Char%%
+T(%%int%%)    = -1073741824 -- 1073741823
+T(%%string%%) = %%Latin1%%
+T(%%unit%%)   = %%[]%%
+T(%%t->u%%)   = T(%%t%%)->T(%%u%%)
+T(%%A%%)      = `A
+T(%%A of t%%) = ( `A, T(%%t%%) )
+T(%%{ u : t }%%) = {| u : T(%%t%%) |} or { u : T(%%t%%) } (logically)
+]]</sample>
+
+</box>
+
+<box title="How to compile files" link="comp">
+
+<p>
+When you have created a good enough interface file, you have to build both
+CDuce and OCaml source codes. To do that simply the follow those instructions:
+</p>
+
+<ul>
+  <li>
+    Create a <code>.cmi</code> from your OCaml file with 
+    <code>ocamlc -c foo.mli</code>.
+  </li>
+  <li>
+    Compile your CDuce file <code>cduce --compile foo.cd</code>. This command
+    will create a CDuce bytecode file (<code>.cdo</code>) and a OCaml file
+    (<code>.ml</code>) containing implementation of your declared functions.
+  </li>
+  <li>
+    Build your final binary but do not forget to link it with 
+    <code>cDuce_all.cma</code> library with contains CDuce interpreter. To
+    do that, just run <code>ocamlc <...> cDuce_all.cma ...</code>.
+  </li>
+</ul>
+
+</box>
\ No newline at end of file