/[svn]/web/ocaml.xml
ViewVC logotype

Diff of /web/ocaml.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1791 by abate, Tue Jul 10 19:23:09 2007 UTC revision 1840 by abate, Tue Jul 10 19:26:20 2007 UTC
# Line 15  Line 15 
15  OCamlDuce is a merger between <a  OCamlDuce is a merger between <a
16  href="http://caml.inria.fr/">OCaml</a> and  href="http://caml.inria.fr/">OCaml</a> and
17  <local href="index">CDuce</local>. It comes as a modified  <local href="index">CDuce</local>. It comes as a modified
18  version of OCaml which integrates CDuce features: expressions, types,  version of OCaml which integrates CDuce features: XML expressions,
19  patterns.  regular expression types and patterns, iterators.
20  </p>  </p>
21    
22  <p>  <p>
23  OCamlDuce is distributed under the same licenses as Objective Caml:  OCamlDuce is distributed under the Q Public License version 1.0.
 the Q Public License version 1.0 for the Compiler, and the LGPL  
 version 2 for the Library. The extension has been written by Alain  
 Frisch. Parts of the CDuce implementation, by the same author, have  
 been reused.  
24  </p>  </p>
25    
26    <ul>
27    <li>A <a
28    href="http://cristal.inria.fr/~frisch/ocamlcduce/ocamlduce.pdf">technical
29    report</a> describes the theory behind OCamlDuce's type system (to be
30    presented in PLAN-X 2006).</li>
31    <li><local href="ocaml_install">How to get OCamlDuce:</local> download,
32    installation instructions, packages.</li>
33    <li><local href="ocaml_manual">User's manual</local>.</li>
34    <li><local href="ocaml_code">Code samples and
35    applications</local>.</li>
36    <li><local href="mailing">Mailing lists</local>.</li>
37    </ul>
38    
39  </box>  </box>
40    
41    <page name="ocaml_install">
42    <title>Getting OCamlDuce</title>
43    
44  <box title="Download and installation" link="install">  <box title="Download and installation" link="install">
45    
46  <p>  <p>
47  The build procedure for OCamlDuce is exactly the same as for OCaml:  Currently, OCamlDuce
48  <tt>configure, make world, make install</tt>. The names of the tools  is based on OCaml 3.09.1 and CDuce 0.4.0.
 are unchanged: <tt>ocaml,ocamlc,ocamlopt</tt>. Currently, OCamlDuce  
 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).  
49  </p>  </p>
50    
51  <ul>  <ul>
52  <li><a  <li><a
53  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,
54  version 0.0.5</a></li>  version 3.08.4, patch level 5</a> (to be used with OCaml 3.08.4)</li>
55  <!--<li><a  <li><a
56  href="http://pauillac.inria.fr/~frisch/ocamlcduce/download/xml-support-0.0.4.tar.gz">Support  href="http://pauillac.inria.fr/~frisch/ocamlcduce/download/ocamlduce-3.09.1pl1.tar.gz">Compiler,
57  library, version 0.0.4</a></li>-->  version 3.09.1</a> (to be used with OCaml 3.09.1)</li>
58  </ul>  </ul>
59    
60  <p>  <p>
61  GODI users can upgrade an existing installation by adding this    The following describes the installation procedure for the version
62  line to their <tt>etc/godi.conf</tt> file:    3.09.1.  OCamlDuce is installed on top of an existing OCaml
63      installation (whose version number must match). The build procedure
64      is: <tt>make all &amp;&amp; make opt &amp;&amp; make
65      install</tt>. The configuration is taken from OCaml's
66      <tt>Makefile.config</tt>.
67  </p>  </p>
68    
69    <p>
70      The tools are named <tt>ocamlduce, ocamlducec, ocamlduceopt,
71      ocamlducedep</tt> (and their <tt>.opt</tt> variants). In addition, a
72      library called <tt>ocamlduce.cma/.cmxa</tt> is built.  It depends on
73      the <tt>nums</tt> library.
74    </p>
75    
76    <p>
77      The <tt>install</tt>
78      target requires <tt>findlib</tt>. It
79      registers a package named <tt>ocamlduce</tt>. The tools
80      go into the same directory as <tt>ocaml</tt>. You can override
81      this directory: <tt>make install BINDIR=...</tt>.
82      E.g. the
83      toplevel can be called by <tt>ocamlduce -I
84      `ocamlfind query ocamlduce` nums.cma ocamlduce.cma</tt>.
85    </p>
86    
87    <p>
88      To generate the ocamldoc documentation for the <tt>Ocamlduce</tt>
89      module: <tt>make htdoc</tt>.
90    </p>
91    
92    <section title="Building from the CVS">
93    
94    <p>
95    The following commands will extract the current development version of
96     OCamlDuce (from OCaml and CDuce CVS repositories):
97    </p>
98    
99  <sample>  <sample>
100  GODI_BUILD_SITES += http://pauillac.inria.fr/~frisch/ocamlcduce/godi          cvs -f -d ":pserver:anoncvs@camlcvs.inria.fr:/caml" co -r cducetrunk ocaml
101            cvs -f -d ":pserver:anonymous@cvs.cduce.org:/cvsroot" co cduce
102            (cd ocaml/cduce; make link)
103  </sample>  </sample>
104    
105    </section>
106    
107    </box>
108    
109    <box title="Ports and packages" link="ports">
110    
111    <section title="GODI">
112    
113    <p>
114      There is a <tt>godi-ocamlduce</tt> package available in GODI
115      (sections 3.08 and 3.09). Note that for the section 3.09, you must
116      install OCaml from CVS (set <tt>OCAML_CVS_CHECKOUT=true</tt> in the
117      <tt>godi-ocaml-src</tt> package and reinstall <tt>godi-ocaml</tt>).
118    </p>
119    
120  <p>  <p>
121  and by forcing a recompilation of the <tt>godi-ocaml-src</tt>    In order to use the new compilers and tools, you can make the
122  and <tt>godi-ocaml</tt> packages. <!--They should also build    environment variable <tt>OCAMLFIND_CONF</tt> point to the
123  the <tt>godi-xml-support</tt> library.-->    <tt>$GODI/etc/findlib-ocamlduce.conf</tt> file and then uses
124      e.g. <tt>ocamlfind ocamlc -package ocamlduce</tt>.
125  </p>  </p>
126    
127  <!--  </section>
128    
129    <section title="DarwinPorts and OpenBSD">
130    
131  <p>  <p>
132  Some simple examples can be found <a -->  Anil Madhavapeddy contributed two ports of OCamlDuce for DarwinPorts
133  <!--href="http://pauillac.inria.fr/~frisch/ocamlcduce/tests/">here</a>.</p>  (in dports/lang/ocamlduce) and for OpenBSD (in ports/lang/ocamlduce).
134  -->  </p>
135    
136    </section>
137    
138  </box>  </box>
139    
140    </page>
141    
142    <page name="ocaml_manual">
143    <title>OCamlDuce: manual</title>
144    
145  <box title="Overview" link="overview">  <box title="Overview" link="overview">
146    
147  <p>  <p>
# Line 497  Line 570 
570     function {{p1}} -> e1 | ... | {{pn}} -> en     function {{p1}} -> e1 | ... | {{pn}} -> en
571  </p>  </p>
572    
573    <p>
574    Pattern matching follows is first-match policy. The first pattern
575    that succeeds triggers the corresponding branch.
576    </p>
577    
578  <note>  <note>
579  currently it is impossible to mix normal OCaml patterns and x-patterns  currently it is impossible to mix normal OCaml patterns and x-patterns
580  in a single pattern matching.  in a single pattern matching.
# Line 624  Line 702 
702  </ul>  </ul>
703    
704  <p>  <p>
705  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
706  The content is then replaced with the label name considered as  an input value, a pattern can either succeed or fail. If it succeeds,
707  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
708  <code>{ x=x y=p }</code>.</p>  to x-values.
709    </p>
710    
711    <ul>
712    
713    <li>A pattern which is just a type (no capture variable) succeeds if
714    and only if the value has the type.</li>
715    
716    <li>A pattern <code>p1 | p2</code> succeeds if either <code>p1</code>
717    or <code>p2</code> succeed, and returns the corresponding binding; if
718    both patterns succeeds, <code>p1</code> wins. It is required that
719    <code>p1</code> and <code>p2</code> have the same sets of capture
720    variables. </li>
721    
722    <li>A pattern <code>p1 &amp; p2</code> succeeds if both <code>p1</code>
723    and <code>p2</code> succeed, and returns the concatenation of the two
724    bindings. It is required that <code>p1</code> and <code>p2</code> have
725    <em>disjoint</em> sets of capture variables. </li>
726    
727    </ul>
728    
729    <p>
730    In record x-patterns, it is possible to omit the <code>=p</code> part
731    of a field.  The content is then replaced with the label name
732    considered as a capture variable (or as a previously defined type).
733     E.g.  <code>{ x y=p }</code> is
734    equivalent to <code>{ x=x y=p }</code>.</p>
735    
736  <p>It is also possible to add an "else" clause:  <p>It is also possible to add an "else" clause:
737  <code>{ x = (a,_)|(a:=3) }</code>  <code>{ x = (a,_)|(a:=3) }</code>
# Line 645  Line 749 
749  repetition) in a regexp, it is bound to the concatenation of all  repetition) in a regexp, it is bound to the concatenation of all
750  matched subsequences. E.g.: <code>[ (x::Int | _)* ]</code> will  matched subsequences. E.g.: <code>[ (x::Int | _)* ]</code> will
751  collect in <code>x</code> all the elements of type <code>Int</code> from  collect in <code>x</code> all the elements of type <code>Int</code> from
752  a sequence.</p>  a sequence. It is not legal to have repeated simple capture variables.
753    </p>
754    
755  <p>  <p>
756  The regexp operators <code>+,*,?</code> are greedy by default (they match as long  The regexp operators <code>+,*,?</code> are greedy by default (they match as long
# Line 940  Line 1045 
1045    
1046  </box>  </box>
1047    
1048  <box title="Code samples" link="code">  <box title="Marshaling" link="marshal">
1049    
1050    <p>
1051    OCamlDuce use some tricks on its internal representation of x-values
1052    to reduce memory usage and improve performance. You need to pay
1053    special attention if you want to use OCaml serialization functions
1054    (module <code>Marshal</code>, functions
1055    <code>input_value/output_value</code>) on x-values. In addition to
1056    your values, you also need to save and restore some piece of internal data
1057    using the functions <code>Cduce_types.Value.extract_all</code> and
1058    <code>Cduce_types.Value.intract_all</code>. Of course, this also
1059    applies if the value to be serialized contains deeply nested x-values.
1060    </p>
1061    
1062    <p>
1063    Here are generic
1064    serialization/deserializations functions that illustrate how to do it:
1065    </p>
1066    
1067    <sample>
1068    let my_output_value oc v =
1069      let p = Cduce_types.Value.extract_all () in
1070      output_value oc (p,v)
1071    
1072    let my_input_value ic =
1073      let (p,v) = input_value ic in
1074      Cduce_types.Value.intract_all p;
1075      v
1076    </sample>
1077    
1078    </box>
1079    
1080    <box title="Performance" link="perf">
1081    
1082    <section title="Strings">
1083    
1084    <p>
1085    OCaml users might be surprised by the fact that x-strings are simply
1086    represented as sequences in OCamlDuce. Does this mean that they are
1087    actually stored in memory as linked list? Certainly not!  The internal
1088    representation of sequence values uses several tricks to improve
1089    performance and memory usage. In particular, a special form in the
1090    representation can store strings as byte buffers, as in OCaml.
1091    It an XML document is loaded, or if a Caml string is converted
1092    to an x-value, this compact representation will be used.
1093    </p>
1094    
1095    </section>
1096    
1097    <section title="Concatenation">
1098    
1099    <p>
1100    Similarly, OCaml users might be relectutant to use the sequence
1101    concatenation <code>@</code> on sequences. In OCaml, the complexity
1102    of this operator is linear in the size of its first argument (which
1103    need to be copied). OCamlDuce use a special form in its internal
1104    representation to store concatenation in a lazy way. The concatenation
1105    will really by computed only when the value is accessed. This means
1106    that it's perfectly ok to build a long sequence by adding
1107    new elements at the end one by one, as long as you don't
1108    simultaneously inspect the sequence.
1109    </p>
1110    
1111    </section>
1112    
1113    <section title="Pattern matching">
1114    
1115    <p>
1116    Another point which is worth knowing when programming in OCamlDuce
1117    is that patterns can be written in a declarative style without
1118    affective performance. The compiler uses static type information
1119    about matched values to produce efficient code for pattern matching.
1120    To illustrate this, consider the following sample:
1121    </p>
1122    
1123    <sample><![CDATA[{{ON}}
1124    x.ml:
1125    
1126    type a = {{ <a>[ a* ] }}
1127    type b = {{ <b>[ b* ] }}
1128    
1129    let f : {{ a|b }} -> int = function {{ a }} -> 0 | {{ _ }} -> 1
1130    ]]></sample>
1131    
1132    <sample><![CDATA[{{ON}}
1133    y.ml:
1134    
1135    type a = {{ <a>[ a* ] }}
1136    type b = {{ <b>[ b* ] }}
1137    
1138    let f : {{ a|b }} -> int = function {{ <a>_ }} -> 0 | {{ _ }} -> 1
1139    ]]></sample>
1140    
1141    <p>
1142    The two functions have exactly the same semantics, but the first
1143    implementation is more declarative: it uses type checks to distinguish
1144    between <code>a</code> and <code>b</code> instead of saying
1145    <em>how</em> to distinguish between these two types. Imagine
1146    that the definition of these types change to:
1147    </p>
1148    
1149    <sample><![CDATA[{{ON}}
1150    type a = {{ <x kind="a">[ a* ] }}
1151    type b = {{ <x kind="b">[ b* ] }}
1152    ]]></sample>
1153    
1154    <p>
1155    Then the first implementation still works as expected, but the
1156    second one needs to be rewritten.</p>
1157    
1158    <p>Now one might believe that the second implementation is more
1159    efficient because it tells the compiler to check only the root tag,
1160    whereas the first implementation would force
1161    the compiler to produce code to check that all tags in the tree
1162    are <code>a</code>s. But this is not what happens! Actually,
1163    you can check that the compiler will produce exactly the same code
1164    for both implementations. It considers the static type information
1165    about the argument of the pattern matching (here, the input type
1166    of the function), and computes an efficient way to evaluate
1167    patterns for the values of this type.
1168    </p>
1169    
1170    </section>
1171    
1172    <section title="The map iterator">
1173    
1174    <p>
1175    The <code>map ... with ...</code> iterator is implemented in a
1176    tail-recursive way. You can safely use it on very long sequences.
1177    </p>
1178    
1179    </section>
1180    
1181    </box>
1182    
1183    <box title="OCaml and OCamlDuce" link="ocaml">
1184    
1185    <p>
1186    Since the 3.08.4 release, OCamlDuce is binary compatible with the corresponding
1187    OCaml release. This means that OCamlDuce can use OCaml-generated
1188    <tt>.cmi</tt> files and that it produces an OCaml-compatible
1189    <tt>.cmi</tt> file if the interface does not use any x-type
1190    (this file is equal to what would have been obtained by using OCaml).
1191    </p>
1192    
1193    <p>
1194    It is thus possible to use existing libraries which were compiled for
1195    OCaml. It is also possible to use OCamlDuce to compile
1196    some modules and use them in an OCaml project provided their interface
1197    is pure OCaml.
1198    </p>
1199    
1200    </box>
1201    
1202    </page>
1203    
1204    <page name="ocaml_code">
1205    <title>OCamlDuce: code samples and applications</title>
1206    
1207    <box title="Code samples" link="code">
1208    
1209  <section title="Parsing XML files">  <section title="Parsing XML files">
1210    
# Line 998  Line 1261 
1261  <p>  <p>
1262  It it interesting to introduce errors in the parser  It it interesting to introduce errors in the parser
1263  <code>schema_loader.ml</code> or the printer  <code>schema_loader.ml</code> or the printer
1264  <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.
1265  </p>  </p>
1266    
1267  <note>  <note>
# Line 1010  Line 1273 
1273  <code>redefine</code> elements or substitution groups.  <code>redefine</code> elements or substitution groups.
1274  </note>  </note>
1275    
1276    <note>
1277    To compile the application with the provided Makefile,
1278    you must make the environment variable <code>OCAMLFIND_CONF</code>
1279    point to the <code>$GODI/etc/findlib-ocamlduce.conf</code> file.
1280    </note>
1281    
1282    </section>
1283    
1284    <section title="String regular expressions">
1285    
1286    <p>
1287    OCamlDuce supports regular expression types and patterns, not only
1288    for sequences of XML elements, but also for strings. The following
1289    example shows how to use regular expressions to split a string
1290    of the form <code>name1=val1,...,namen=valn</code> with
1291    <code>n>0</code> into
1292    a list of pairs <code>[ (name1,val1); ...; (namen,valn) ]</code>.
1293    The <code>*?</code> operator in regular expressions means ``ungreedy
1294    match'' (match the shortest possible subsequence). The last
1295    pattern describes precisely strings which are not matched by
1296    the other cases. It would be possible to replace it with
1297    the wildcard <code>_</code>.
1298    </p>
1299    
1300    <sample><![CDATA[{{ON}}
1301    let rec split (s : {{ String }}) =
1302      match s with
1303        | {{ [ n::_*? '=' v::_*? ',' rest::_* ] }} -> (n,v)::(split rest)
1304        | {{ [ n::_*? '=' v::_*? ] }} -> [ (n,v) ]
1305        | {{ Any - [ _* '=' _* ] }} -> failwith "split"
1306    ]]></sample>
1307    
1308  </section>  </section>
1309    
1310  </box>  </box>
1311    
1312    <box title="Applications in OCamlDuce" link="appli">
1313    
1314    <ul>
1315    <li><a
1316    href="http://anil.recoil.org/projects/review2atom.html">Review2Atom</a>
1317    by Anil Madhavapeddy: translates paper review files in XML format into
1318    an Atom feed suitable for aggregation.
1319    </li>
1320    </ul>
1321    
1322    </box>
1323    
1324    </page>
1325    
1326  </page>  </page>
Legend:
Removed from v.1791  
changed lines
  Added in v.1840
CVS Admin">CVS Admin
 ViewVC Help
Powered by ViewVC 1.1.5