/[svn]/web/ocaml.xml

Diff of /web/ocaml.xml

Parent Directory | Revision Log | View Patch Patch

-revision 1790 by abate,
Tue Jul 10 19:23:06 2007 UTC
+revision 1815 by abate,
Tue Jul 10 19:24:58 2007 UTC
 Line 27
  been reused.
  </p>
+ <p>
+ The theory behind OCamlDuce's type system is described in a <a
+ href="http://cristal.inria.fr/~frisch/ocamlcduce/">technical
+ report</a>.
+ </p>
  </box>
  <box title="Download and installation" link="install">
  <p>
- The build procedure for OCamlDuce is exactly the same as for OCaml:
+ Currently, OCamlDuce
- <tt>configure, make world, make install</tt>. The names of the tools
+ is based on OCaml 3.08.4 and on a CVS snapshots
- are unchanged: <tt>ocaml,ocamlc,ocamlopt</tt>. Currently, OCamlDuce
+ of CDuce (between 0.3.92 and the head).
- is based on CVS snapshots of OCaml (between 3.08.3 and the current
- <tt>release308</tt> branch) and CDuce (between 0.3.91 and the head).
  </p>
  <ul>
  <li><a
- href="http://pauillac.inria.fr/~frisch/ocamlcduce/download/cduce-ocaml-0.0.5.tar.gz">Compiler,
+ href="http://pauillac.inria.fr/~frisch/ocamlcduce/download/ocamlduce-3.08.4pl5.tar.gz">Compiler,
- version 0.0.5</a></li>
+ version 3.08.4, patch level 5</a></li>
- <!--<li><a
- href="http://pauillac.inria.fr/~frisch/ocamlcduce/download/xml-support-0.0.4.tar.gz">Support
- library, version 0.0.4</a></li>-->
  </ul>
  <p>
- GODI users can upgrade an existing installation by adding this
+ There are two different installation modes:
+ </p>
+ <ul>
+ <li><b>Stand-alone mode</b>. OCamlDuce is used as a drop-in
+ replacement for OCaml. The build procedure is unchanged:
+ <tt>./configure &amp;&amp; make world &amp;&amp; make install</tt>.
+ The tools are named <tt>ocaml, ocamlc, ocamlopt</tt>, ...
+ The standard library is extended with the <tt>num</tt> library
+ and the <tt>Ocamlduce</tt> module.
+ </li>
+ <li><b>Package mode</b>. OCamlDuce is installed on top of an existing
+ OCaml installation (whose version number must match), without touching
+ it. The build
+ procedure is: <tt>./configure &amp;&amp; make all &amp;&amp; make opt
+ &amp;&amp; make install</tt>.  The <tt>configure</tt> script should be called with
+ the same arguments as the ones used when you built OCaml. For instance,
+ the <tt>LIBDIR</tt> argument is used to find OCaml standard library.
+ The tools names are changed to <tt>ocamlduce, ocamlducec,
+ ocamlduceopt</tt>, ...  They use the existing standard library.
+ In addition, a library <tt>ocamlduce.cma</tt> is built.
+ It depends on the <tt>nums.cma</tt> library. The <tt>install</tt>
+ target implements a <tt>Findlib</tt>-based installation. It registers
+ a package named <tt>ocamlduce</tt> and it puts the tools
+ in the package sub-directory (the <tt>BINDIR</tt> and <tt>LIBDIR</tt>
+ arguments to <tt>configure</tt> are not used). The toplevel
+ can be called by <tt>ocamlfind ocamlduce/ocamlduce -I `ocamlfind query ocamlduce`</tt>.
+ </li>
+ </ul>
+ </box>
+ <box title="Ports and packages" link="ports">
+ <section title="GODI">
+ <p>
+ GODI users can choose any of the two installation modes.
+ In order to upgrade an existing installation so as to use
+ OCamlDuce in place of OCaml, they must add this
  line to their <tt>etc/godi.conf</tt> file:
  </p>
  <sample>
  GODI_BUILD_SITES += http://pauillac.inria.fr/~frisch/ocamlcduce/godi
  </sample>
  <p>
- and by forcing a recompilation of the <tt>godi-ocaml-src</tt>
+ and force a recompilation of the <tt>godi-ocaml-src</tt>
- and <tt>godi-ocaml</tt> packages. <!--They should also build
+ and <tt>godi-ocaml</tt> packages. The alternative is to install
- the <tt>godi-xml-support</tt> library.-->
+ OCamlDuce
+ as a GODI package over an existing installation. You don't need
+ to touch the <tt>etc/godi.conf</tt> file. The package
+ name is <tt>godi-ocamlduce</tt>. In order to use the new compilers
+ and tools, you can make the environment variable
+ <tt>OCAMLFIND_CONF</tt> point to the
+ <tt>$GODI/etc/findlib-ocamlduce.conf</tt> file and then
+ uses e.g. <tt>ocamlfind ocamlc -package ocamlduce</tt>.
  </p>
+ </section>
+ <section title="DarwinPorts and OpenBSD">
- <!--
  <p>
- Some simple examples can be found <a -->
+ Anil Madhavapeddy contributed two ports of OCamlDuce for DarwinPorts
- <!--href="http://pauillac.inria.fr/~frisch/ocamlcduce/tests/">here</a>.</p>
+ (in dports/lang/ocamlduce) and for OpenBSD (in ports/lang/ocamlduce).
- -->
+ </p>
+ </section>
  </box>
  <box title="Overview" link="overview">
  <p>
+ The goal of the OCamlDuce project is to extend the OCaml language with features
+ to make it easier to write safe and efficient complex applications
+ that need to deal with XML documents. In particular, it relies
+ on a notion of types and patterns to guarantee statically
+ that all the possible input documents are correctly processed, and
+ that only valid output documents are produced.
+ </p>
+ <p>
  In a nutshell, OCamlDuce extends OCaml with a new kind of values
  (<em>x-values</em>) to represent XML documents, fragments, tags, Unicode
  strings. In order to describe these values, it also extends the type algebra
-Line 488
+Line 548
     function {{p1}} -> e1 | ... | {{pn}} -> en
  </p>
+ <p>
+ Pattern matching follows is first-match policy. The first pattern
+ that succeeds triggers the corresponding branch.
+ </p>
  <note>
  currently it is impossible to mix normal OCaml patterns and x-patterns
  in a single pattern matching.
-Line 615
+Line 680
  </ul>
  <p>
- In record x-patterns, it is possible to omit the <code>=p</code> part of a field.
+ Here is a brief description of the semantics of patterns. Given
- The content is then replaced with the label name considered as
+ an input value, a pattern can either succeed or fail. If it succeeds,
- a capture variable. E.g.  <code>{ x y=p }</code> is equivalent to
+ it also produces a bindings from the capture variables in the pattern
- <code>{ x=x y=p }</code>.</p>
+ to x-values.
+ </p>
+ <ul>
+ <li>A pattern which is just a type (no capture variable) succeeds if
+ and only if the value has the type.</li>
+ <li>A pattern <code>p1 | p2</code> succeeds if either <code>p1</code>
+ or <code>p2</code> succeed, and returns the corresponding binding; if
+ both patterns succeeds, <code>p1</code> wins. It is required that
+ <code>p1</code> and <code>p2</code> have the same sets of capture
+ variables. </li>
+ <li>A pattern <code>p1 &amp; p2</code> succeeds if both <code>p1</code>
+ and <code>p2</code> succeed, and returns the concatenation of the two
+ bindings. It is required that <code>p1</code> and <code>p2</code> have
+ <em>disjoint</em> sets of capture variables. </li>
+ </ul>
+ <p>
+ In record x-patterns, it is possible to omit the <code>=p</code> part
+ of a field.  The content is then replaced with the label name
+ considered as a capture variable (or as a previously defined type).
+  E.g.  <code>{ x y=p }</code> is
+ equivalent to <code>{ x=x y=p }</code>.</p>
  <p>It is also possible to add an "else" clause:
  <code>{ x = (a,_)|(a:=3) }</code>
-Line 636
+Line 727
  repetition) in a regexp, it is bound to the concatenation of all
  matched subsequences. E.g.: <code>[ (x::Int | _)* ]</code> will
  collect in <code>x</code> all the elements of type <code>Int</code> from
- a sequence.</p>
+ a sequence. It is not legal to have repeated simple capture variables.
+ </p>
  <p>
  The regexp operators <code>+,*,?</code> are greedy by default (they match as long
-Line 931
+Line 1023
  </box>
- <box title="Code samples" link="code">
+ <box title="Marshaling" link="marshal">
+ <p>
+ OCamlDuce use some tricks on its internal representation of x-values
+ to reduce memory usage and improve performance. You need to pay
+ special attention if you want to use OCaml serialization functions
+ (module <code>Marshal</code>, functions
+ <code>input_value/output_value</code>) on x-values. In addition to
+ your values, you also need to save and restore some piece of internal data
+ using the functions <code>Cduce_types.Value.extract_all</code> and
+ <code>Cduce_types.Value.intract_all</code>. Of course, this also
+ applies if the value to be serialized contains deeply nested x-values.
+ </p>
+ <p>
+ Here are generic
+ serialization/deserializations functions that illustrate how to do it:
+ </p>
+ <sample>
+ let my_output_value oc v =
+   let p = Cduce_types.Value.extract_all () in
+   output_value oc (p,v)
+ let my_input_value ic =
+   let (p,v) = input_value ic in
+   Cduce_types.Value.intract_all p;
+   v
+ </sample>
+ </box>
+ <box title="Performance" link="perf">
+ <section title="Strings">
+ <p>
+ OCaml users might be surprised by the fact that x-strings are simply
+ represented as sequences in OCamlDuce. Does this mean that they are
+ actually stored in memory as linked list? Certainly not!  The internal
+ representation of sequence values uses several tricks to improve
+ performance and memory usage. In particular, a special form in the
+ representation can store strings as byte buffers, as in OCaml.
+ It an XML document is loaded, or if a Caml string is converted
+ to an x-value, this compact representation will be used.
+ </p>
+ </section>
+ <section title="Concatenation">
+ <p>
+ Similarly, OCaml users might be relectutant to use the sequence
+ concatenation <code>@</code> on sequences. In OCaml, the complexity
+ of this operator is linear in the size of its first argument (which
+ need to be copied). OCamlDuce use a special form in its internal
+ representation to store concatenation in a lazy way. The concatenation
+ will really by computed only when the value is accessed. This means
+ that it's perfectly ok to build a long sequence by adding
+ new elements at the end one by one, as long as you don't
+ simultaneously inspect the sequence.
+ </p>
+ </section>
+ <section title="Pattern matching">
+ <p>
+ Another point which is worth knowing when programming in OCamlDuce
+ is that patterns can be written in a declarative style without
+ affective performance. The compiler uses static type information
+ about matched values to produce efficient code for pattern matching.
+ To illustrate this, consider the following sample:
+ </p>
+ <sample><![CDATA[{{ON}}
+ x.ml:
+ type a = {{ <a>[ a* ] }}
+ type b = {{ <b>[ b* ] }}
+ let f : {{ a|b }} -> int = function {{ a }} -> 0 | {{ _ }} -> 1
+ ]]></sample>
+ <sample><![CDATA[{{ON}}
+ y.ml:
+ type a = {{ <a>[ a* ] }}
+ type b = {{ <b>[ b* ] }}
+ let f : {{ a|b }} -> int = function {{ <a>_ }} -> 0 | {{ _ }} -> 1
+ ]]></sample>
+ <p>
+ The two functions have exactly the same semantics, but the first
+ implementation is more declarative: it uses type checks to distinguish
+ between <code>a</code> and <code>b</code> instead of saying
+ <em>how</em> to distinguish between these two types. Imagine
+ that the definition of these types change to:
+ </p>
+ <sample><![CDATA[{{ON}}
+ type a = {{ <x kind="a">[ a* ] }}
+ type b = {{ <x kind="b">[ b* ] }}
+ ]]></sample>
+ <p>
+ Then the first implementation still works as expected, but the
+ second one needs to be rewritten.</p>
+ <p>Now one might believe that the second implementation is more
+ efficient because it tells the compiler to check only the root tag,
+ whereas the first implementation would force
+ the compiler to produce code to check that all tags in the tree
+ are <code>a</code>s. But this is not what happens! Actually,
+ you can check that the compiler will produce exactly the same code
+ for both implementations. It considers the static type information
+ about the argument of the pattern matching (here, the input type
+ of the function), and computes an efficient way to evaluate
+ patterns for the values of this type.
+ </p>
+ </section>
+ <section title="The map iterator">
+ <p>
+ The <code>map ... with ...</code> iterator is implemented in a
+ tail-recursive way. You can safely use it on very long sequences.
+ </p>
+ </section>
+ </box>
+ <box title="OCaml and OCamlDuce" link="ocaml">
+ <p>
+ Since the 3.08.4 release, OCamlDuce is binary compatible with the corresponding
+ OCaml release. This means that OCamlDuce can use OCaml-generated
+ <tt>.cmi</tt> files and that it produces an OCaml-compatible
+ <tt>.cmi</tt> file if the interface does not use any x-type
+ (this file is equal to what would have been obtained by using OCaml).
+ </p>
+ <p>
+ It is thus possible to use existing libraries which were compiled for
+ OCaml 3.08.4. It is also possible to use OCamlDuce to compile
+ some modules and use them in an OCaml project provided their interface
+ is pure OCaml.
+ </p>
+ </box>
+ <box title="Code samples" link="code">
  <section title="Parsing XML files">
-Line 989
+Line 1235
  <p>
  It it interesting to introduce errors in the parser
  <code>schema_loader.ml</code> or the printer
- <code>dump_schema.ml</code> and see how the type system catch them.
+ <code>dump_schema.ml</code> and see how the type system catches them.
  </p>
  <note>
-Line 1001
+Line 1247
  <code>redefine</code> elements or substitution groups.
  </note>
+ <note>
+ To compile the application with the provided Makefile,
+ you must make the environment variable <code>OCAMLFIND_CONF</code>
+ point to the <code>$GODI/etc/findlib-ocamlduce.conf</code> file.
+ </note>
+ </section>
+ <section title="String regular expressions">
+ <p>
+ OCamlDuce supports regular expression types and patterns, not only
+ for sequences of XML elements, but also for strings. The following
+ example shows how to use regular expressions to split a string
+ of the form <code>name1=val1,...,namen=valn</code> with
+ <code>n>0</code> into
+ a list of pairs <code>[ (name1,val1); ...; (namen,valn) ]</code>.
+ The <code>*?</code> operator in regular expressions means ``ungreedy
+ match'' (match the shortest possible subsequence). The last
+ pattern describes precisely strings which are not matched by
+ the other cases. It would be possible to replace it with
+ the wildcard <code>_</code>.
+ </p>
+ <sample><![CDATA[{{ON}}
+ let rec split (s : {{ String }}) =
+   match s with
+     | {{ [ n::_*? '=' v::_*? ',' rest::_* ] }} -> (n,v)::(split rest)
+     | {{ [ n::_*? '=' v::_*? ] }} -> [ (n,v) ]
+     | {{ Any - [ _* '=' _* ] }} -> failwith "split"
+ ]]></sample>
  </section>
  </box>
+ <box title="Applications in OCamlDuce" link="appli">
+ <ul>
+ <li><a
+ href="http://anil.recoil.org/projects/review2atom.html">Review2Atom</a>
+ by Anil Madhavapeddy: translates paper review files in XML format into
+ an Atom feed suitable for aggregation.
+ </li>
+ </ul>
+ </box>
  </page>

 Legend:



Removed from v.1790
 


changed lines


 
Added in v.1815
 Legend:



Removed from v.1790
 


changed lines


 
Added in v.1815
-Removed from v.1790
+Added in v.1815

CVS Admin">CVS Admin	ViewVC Help
Powered by ViewVC 1.1.5