Commit c201b0d1 authored by Pietro Abate's avatar Pietro Abate
Browse files

[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
parent 6e908cd3
<?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
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment