File: manual.html

package info (click to toggle)
ocaml-doc 4.11-2
links: PTS, VCS
area: non-free
in suites: bookworm, bullseye, forky, sid, trixie
size: 20,580 kB
sloc: sh: 37; makefile: 11
file content (24970 lines) | stat: -rw-r--r-- 1,781,507 bytes
<!DOCTYPE html>
<html>
<head>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="hevea 2.32">
<style type="text/css">
.c000{border-spacing:0;width:80%}
.c001{border-spacing:6px;border-collapse:separate;}
.c002{color:blue}
.c003{font-family:monospace}
.c004{font-family:monospace;color:blue}
.c005{font-family:monospace;font-style:italic}
.c006{font-family:monospace;font-weight:bold}
.c007{font-family:sans-serif}
.c008{font-size:small}
.c009{font-style:italic}
.c010{font-style:italic;color:maroon}
.c011{font-style:italic;font-weight:bold}
.c012{font-style:oblique}
.c013{font-weight:bold}
.c014{text-align:center;border:solid 1px;white-space:nowrap}
.c015{text-align:center;white-space:nowrap}
.c016{text-align:left;border:solid 1px;white-space:nowrap}
.c017{text-align:left;white-space:nowrap}
.c018{text-align:right;white-space:nowrap}
.c019{vertical-align:middle}
.c020{vertical-align:top;text-align:left;}
.c021{vertical-align:top;text-align:left;border:solid 1px;}
.c022{vertical-align:top;text-align:left;border:solid 1px;white-space:nowrap}
.c023{vertical-align:top;text-align:left;white-space:nowrap}
.c024{vertical-align:top;text-align:right;white-space:nowrap}
.li-itemize{margin:1ex 0ex;}
.li-enumerate{margin:1ex 0ex;}
.dd-description{margin:0ex 0ex 1ex 4ex;}
.dt-description{margin:0ex;}
.toc{list-style:none;}
.footnotetext{margin:0ex; padding:0ex;}
div.footnotetext P{margin:0px; text-indent:1em;}
.thefootnotes{text-align:left;margin:0ex;}
.dt-thefootnotes{margin:0em;}
.dd-thefootnotes{margin:0em 0em 0em 2em;}
.footnoterule{margin:1em auto 1em 0px;width:50%;}
.center{text-align:center;margin-left:auto;margin-right:auto;}
div table{margin-left:inherit;margin-right:inherit;margin-bottom:2px;margin-top:2px}
td table{margin:auto;}
table{border-collapse:collapse;}
td{padding:0;}
.cellpadding1 tr td{padding:1px;}
pre{text-align:left;margin-left:0ex;margin-right:auto;}
blockquote{margin-left:4ex;margin-right:4ex;text-align:left;}
td p{margin:0px;}
.hbar{border:none;height:2px;width:100%;background-color:black;}
.display{border-collapse:separate;border-spacing:2px;width:auto; border:none;}
.dcell{white-space:nowrap;padding:0px; border:none;}
.dcenter{margin:0ex auto;}
.theorem{text-align:left;margin:1ex auto 1ex 0ex;}
.part{margin:2ex auto;text-align:center}
a.section-anchor::after{content:"🔗";
font-size:smaller;
margin-left:-1.5em;
padding-right:0.5em;
}
a.section-anchor{visibility:hidden;
color:grey !important;
text-decoration:none !important;
}
*:hover>a.section-anchor{visibility:visible;
}
a:link{color:#4286f4;text-decoration:underline;}
a:visited{color:#0d46a3;text-decoration:underline;}
a:hover{color:black;text-decoration:underline;}
@media all{@font-face {
/* fira-sans-regular - latin */
font-family: 'Fira Sans';
font-style: normal;
font-weight: 400;
src: url('fonts/fira-sans-v8-latin-regular.eot'); /* IE9 Compat Modes */
src: local('Fira Sans Regular'), local('FiraSans-Regular'),
url('fonts/fira-sans-v8-latin-regular.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */
url('fonts/fira-sans-v8-latin-regular.woff2') format('woff2'), /* Super Modern Browsers */
url('fonts/fira-sans-v8-latin-regular.woff') format('woff'), /* Modern Browsers */
url('fonts/fira-sans-v8-latin-regular.ttf') format('truetype'), /* Safari, Android, iOS */
url('fonts/fira-sans-v8-latin-regular.svg#FiraSans') format('svg'); /* Legacy iOS */
}
}
body{max-width:750px;
width: 85%;
margin: auto;
background: #f7f7f7;
margin-top: 80px;
font-size: 1rem;
}
.maintitle{font-family: "Fira Sans", sans-serif;
text-align: center;
}
h1, h2, h3{font-family: "Fira Sans", sans-serif;
font-weight: normal;
border-bottom: 1px solid black;
}
div.ocaml{margin:2ex 0px;
font-size: 1rem;
background: beige;
border: 1px solid grey;
padding: 10px;
overflow-y:auto;
display:flex;
flex-direction: column;
flex-wrap: nowrap;
}
div.ocaml .pre{white-space: pre;
font-family: monospace;
}
.ocamlkeyword{font-weight:bold;
}
.ocamlhighlight{font-weight:bold;
text-decoration:underline;
}
.ocamlerror{font-weight:bold;
color:red;
}
.ocamlwarning{font-weight:bold;
color:purple;
}
.ocamlcomment{color:grey;
}
.ocamlstring{opacity:0.75;
}
#cc_license_logo{float:left;
margin-right: 1em;
}
p,ul{line-height:1.3em}
.cellpadding1 tr td{padding:1px 4px}
div.caml-output{color:maroon;}
div.caml-example.toplevel div.caml-input::before{content:"#"; color:black;}
div.caml-example.toplevel div.caml-input{color:#006000;}
.tableau, .syntax, .syntaxleft{/* same width as body */
max-width: 750px;
overflow-y: auto;
}
.li-links{margin:0ex 0ex;}
a.syntax:link{color:maroon;text-decoration:underline}
a.syntax:visited{color:maroon;text-decoration:underline}
a.syntax:hover{color:black;text-decoration:none;background-color:#FF6060}
</style>

  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1">

<title>The OCaml system, release 4.11
</title>
</head>
<body>
<!--HEVEA command line is: hevea -fix -exec xxdate.exe -O -I .. -I ../cmds -I ../library -I ../refman -I ../tutorials -I ../../styles -I ../texstuff manual.hva -e macros.tex ../manual.tex -->
<!--CUT STYLE book--><!--CUT DEF chapter 1 --><div class="maintitle">
 <span style="font-size:xx-large"><span style="font-size:150%">The OCaml system <br>
 release 4.11<br>
<span style="font-size:x-large">Documentation and user’s manual <br>
<span style="font-size:large">Xavier Leroy, <br>
 Damien Doligez, Alain Frisch, Jacques Garrigue, Didier Rémy and Jérôme Vouillon <br>
 August 19, 2020<br>
  
<span style="font-size:medium">Copyright © 2020 Institut National de
Recherche en Informatique et en Automatique
</span></span></span></span></span></div><blockquote class="quote">
<hr style="height:2">
This manual is also available in
<a href="https://ocaml.org/releases/4.11/ocaml-4.11-refman.pdf">PDF</a>.
<a href="https://ocaml.org/releases/4.11/ocaml-4.11-refman.txt">plain text</a>,
as a
<a href="https://ocaml.org/releases/4.11/ocaml-4.11-refman-html.tar.gz">bundle of HTML files</a>,
and as a
<a href="https://ocaml.org/releases/4.11/ocaml-4.11-refman.info.tar.gz">bundle of Emacs Info files</a>.
<hr style="height:2">
</blockquote><!--TOC chapter id="sec1" Contents-->
<h1 class="chapter" id="sec1">Contents</h1><!--SEC END --><ul class="toc"><li class="li-toc">
<a href="#sec6">Part I  An introduction to OCaml</a>
<ul class="toc"><li class="li-toc">
<a href="#sec7">Chapter 1  The core language</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Abasics">1.1  Basics</a>
</li><li class="li-toc"><a href="#s%3Adatatypes">1.2  Data types</a>
</li><li class="li-toc"><a href="#s%3Afunctions-as-values">1.3  Functions as values</a>
</li><li class="li-toc"><a href="#s%3Atut-recvariants">1.4  Records and variants</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Arecord-and-variant-disambiguation">1.4.1  Record and variant disambiguation</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aimperative-features">1.5  Imperative features</a>
</li><li class="li-toc"><a href="#s%3Aexceptions">1.6  Exceptions</a>
</li><li class="li-toc"><a href="#s%3Alazy-expr">1.7  Lazy expressions</a>
</li><li class="li-toc"><a href="#s%3Asymb-expr">1.8  Symbolic processing of expressions</a>
</li><li class="li-toc"><a href="#s%3Apretty-printing">1.9  Pretty-printing</a>
</li><li class="li-toc"><a href="#s%3Aprintf">1.10  Printf formats</a>
</li><li class="li-toc"><a href="#s%3Astandalone-programs">1.11  Standalone OCaml programs</a>
</li></ul>
</li><li class="li-toc"><a href="#sec20">Chapter 2  The module system</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Amodule%3Astructures">2.1  Structures</a>
</li><li class="li-toc"><a href="#s%3Asignature">2.2  Signatures</a>
</li><li class="li-toc"><a href="#s%3Afunctors">2.3  Functors</a>
</li><li class="li-toc"><a href="#s%3Afunctors-and-abstraction">2.4  Functors and type abstraction</a>
</li><li class="li-toc"><a href="#s%3Aseparate-compilation">2.5  Modules and separate compilation</a>
</li></ul>
</li><li class="li-toc"><a href="#sec26">Chapter 3  Objects in OCaml</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Aclasses-and-objects">3.1  Classes and objects</a>
</li><li class="li-toc"><a href="#s%3Aimmediate-objects">3.2  Immediate objects</a>
</li><li class="li-toc"><a href="#s%3Areference-to-self">3.3  Reference to self</a>
</li><li class="li-toc"><a href="#s%3Ainitializers">3.4  Initializers</a>
</li><li class="li-toc"><a href="#s%3Avirtual-methods">3.5  Virtual methods</a>
</li><li class="li-toc"><a href="#s%3Aprivate-methods">3.6  Private methods</a>
</li><li class="li-toc"><a href="#s%3Aclass-interfaces">3.7  Class interfaces</a>
</li><li class="li-toc"><a href="#s%3Ainheritance">3.8  Inheritance</a>
</li><li class="li-toc"><a href="#s%3Amultiple-inheritance">3.9  Multiple inheritance</a>
</li><li class="li-toc"><a href="#s%3Aparameterized-classes">3.10  Parameterized classes</a>
</li><li class="li-toc"><a href="#s%3Apolymorphic-methods">3.11  Polymorphic methods</a>
</li><li class="li-toc"><a href="#s%3Ausing-coercions">3.12  Using coercions</a>
</li><li class="li-toc"><a href="#s%3Afunctional-objects">3.13  Functional objects</a>
</li><li class="li-toc"><a href="#s%3Acloning-objects">3.14  Cloning objects</a>
</li><li class="li-toc"><a href="#s%3Arecursive-classes">3.15  Recursive classes</a>
</li><li class="li-toc"><a href="#s%3Abinary-methods">3.16  Binary methods</a>
</li><li class="li-toc"><a href="#s%3Afriends">3.17  Friends</a>
</li></ul>
</li><li class="li-toc"><a href="#sec44">Chapter 4  Labels and variants</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Alabels">4.1  Labels</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aoptional-arguments">4.1.1  Optional arguments</a>
</li><li class="li-toc"><a href="#ss%3Alabel-inference">4.1.2  Labels and type inference</a>
</li><li class="li-toc"><a href="#ss%3Alabel-suggestions">4.1.3  Suggestions for labeling</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Apolymorphic-variants">4.2  Polymorphic variants</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Apolyvariant-weaknesses">4.2.1  Weaknesses of polymorphic variants</a>
</li></ul>
</li></ul>
</li><li class="li-toc"><a href="#sec53">Chapter 5  Polymorphism and its limitations</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Aweak-polymorphism">5.1  Weak polymorphism and mutation</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aweak-types">5.1.1  Weakly polymorphic types</a>
</li><li class="li-toc"><a href="#ss%3Avaluerestriction">5.1.2  The value restriction</a>
</li><li class="li-toc"><a href="#ss%3Arelaxed-value-restriction">5.1.3  The relaxed value restriction</a>
</li><li class="li-toc"><a href="#ss%3Avariance-and-value-restriction">5.1.4  Variance and value restriction</a>
</li><li class="li-toc"><a href="#ss%3Avariance%3Aabstract-data-types">5.1.5  Abstract data types</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Apolymorphic-recursion">5.2  Polymorphic recursion</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aexplicit-polymorphism">5.2.1  Explicitly polymorphic annotations</a>
</li><li class="li-toc"><a href="#ss%3Arecursive-poly-examples">5.2.2  More examples</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Ahigher-rank-poly">5.3  Higher-rank polymorphic functions</a>
</li></ul>
</li><li class="li-toc"><a href="#sec64">Chapter 6  Advanced examples with classes and modules</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Aextended-bank-accounts">6.1  Extended example: bank accounts</a>
</li><li class="li-toc"><a href="#s%3Amodules-as-classes">6.2  Simple modules as classes</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Astring-as-class">6.2.1  Strings</a>
</li><li class="li-toc"><a href="#ss%3Ahashtbl-as-class">6.2.2  Hashtbl</a>
</li><li class="li-toc"><a href="#ss%3Aset-as-class">6.2.3  Sets</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Asubject-observer">6.3  The subject/observer pattern</a>
</li></ul>
</li></ul>
</li><li class="li-toc"><a href="#sec72">Part II  The OCaml language</a>
<ul class="toc"><li class="li-toc">
<a href="#sec73">Chapter 7  The OCaml language</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Alexical-conventions">7.1  Lexical conventions</a>
</li><li class="li-toc"><a href="#s%3Avalues">7.2  Values</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Avalues%3Abase">7.2.1  Base values</a>
</li><li class="li-toc"><a href="#ss%3Avalues%3Atuple">7.2.2  Tuples</a>
</li><li class="li-toc"><a href="#ss%3Avalues%3Arecords">7.2.3  Records</a>
</li><li class="li-toc"><a href="#ss%3Avalues%3Aarray">7.2.4  Arrays</a>
</li><li class="li-toc"><a href="#ss%3Avalues%3Avariant">7.2.5  Variant values</a>
</li><li class="li-toc"><a href="#ss%3Avalues%3Apolyvars">7.2.6  Polymorphic variants</a>
</li><li class="li-toc"><a href="#ss%3Avalues%3Afun">7.2.7  Functions</a>
</li><li class="li-toc"><a href="#ss%3Avalues%3Aobj">7.2.8  Objects</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Anames">7.3  Names</a>
</li><li class="li-toc"><a href="#s%3Atypexpr">7.4  Type expressions</a>
</li><li class="li-toc"><a href="#s%3Aconst">7.5  Constants</a>
</li><li class="li-toc"><a href="#s%3Apatterns">7.6  Patterns</a>
</li><li class="li-toc"><a href="#s%3Avalue-expr">7.7  Expressions</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aprecedence-and-associativity">7.7.1  Precedence and associativity</a>
</li><li class="li-toc"><a href="#ss%3Aexpr-basic">7.7.2  Basic expressions</a>
</li><li class="li-toc"><a href="#ss%3Aexpr-control">7.7.3  Control structures</a>
</li><li class="li-toc"><a href="#ss%3Aexpr-ops-on-data">7.7.4  Operations on data structures</a>
</li><li class="li-toc"><a href="#ss%3Aexpr-operators">7.7.5  Operators</a>
</li><li class="li-toc"><a href="#ss%3Aexpr-obj">7.7.6  Objects</a>
</li><li class="li-toc"><a href="#ss%3Aexpr-coercions">7.7.7  Coercions</a>
</li><li class="li-toc"><a href="#ss%3Aexpr-other">7.7.8  Other</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Atydef">7.8  Type and exception definitions</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Atypedefs">7.8.1  Type definitions</a>
</li><li class="li-toc"><a href="#ss%3Aexndef">7.8.2  Exception definitions</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aclasses">7.9  Classes</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aclasses%3Aclass-types">7.9.1  Class types</a>
</li><li class="li-toc"><a href="#ss%3Aclass-expr">7.9.2  Class expressions</a>
</li><li class="li-toc"><a href="#ss%3Aclass-def">7.9.3  Class definitions</a>
</li><li class="li-toc"><a href="#ss%3Aclass-spec">7.9.4  Class specifications</a>
</li><li class="li-toc"><a href="#ss%3Aclasstype">7.9.5  Class type definitions</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Amodtypes">7.10  Module types (module specifications)</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Amty-simple">7.10.1  Simple module types</a>
</li><li class="li-toc"><a href="#ss%3Amty-signatures">7.10.2  Signatures</a>
</li><li class="li-toc"><a href="#ss%3Amty-functors">7.10.3  Functor types</a>
</li><li class="li-toc"><a href="#ss%3Amty-with">7.10.4  The <span class="c003">with</span> operator</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Amodule-expr">7.11  Module expressions (module implementations)</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Amexpr-simple">7.11.1  Simple module expressions</a>
</li><li class="li-toc"><a href="#ss%3Amexpr-structures">7.11.2  Structures</a>
</li><li class="li-toc"><a href="#ss%3Amexpr-functors">7.11.3  Functors</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Acompilation-units">7.12  Compilation units</a>
</li></ul>
</li><li class="li-toc"><a href="#sec238">Chapter 8  Language extensions</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Aletrecvalues">8.1  Recursive definitions of values</a>
</li><li class="li-toc"><a href="#s%3Arecursive-modules">8.2  Recursive modules</a>
</li><li class="li-toc"><a href="#s%3Aprivate-types">8.3  Private types</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aprivate-types-variant">8.3.1  Private variant and record types</a>
</li><li class="li-toc"><a href="#ss%3Aprivate-types-abbrev">8.3.2  Private type abbreviations</a>
</li><li class="li-toc"><a href="#ss%3Aprivate-rows">8.3.3  Private row types</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Alocally-abstract">8.4  Locally abstract types</a>
</li><li class="li-toc"><a href="#s%3Afirst-class-modules">8.5  First-class modules</a>
</li><li class="li-toc"><a href="#s%3Amodule-type-of">8.6  Recovering the type of a module</a>
</li><li class="li-toc"><a href="#s%3Asignature-substitution">8.7  Substituting inside a signature</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Adestructive-substitution">8.7.1  Destructive substitutions</a>
</li><li class="li-toc"><a href="#ss%3Alocal-substitution">8.7.2  Local substitution declarations</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Amodule-alias">8.8  Type-level module aliases</a>
</li><li class="li-toc"><a href="#s%3Aexplicit-overriding-open">8.9  Overriding in open statements</a>
</li><li class="li-toc"><a href="#s%3Agadts">8.10  Generalized algebraic datatypes</a>
</li><li class="li-toc"><a href="#s%3Abigarray-access">8.11  Syntax for Bigarray access</a>
</li><li class="li-toc"><a href="#s%3Aattributes">8.12  Attributes</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Abuiltin-attributes">8.12.1  Built-in attributes</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aextension-nodes">8.13  Extension nodes</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Abuiltin-extension-nodes">8.13.1  Built-in extension nodes</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aextensible-variants">8.14  Extensible variant types</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aprivate-extensible">8.14.1  Private extensible variant types</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Agenerative-functors">8.15  Generative functors</a>
</li><li class="li-toc"><a href="#s%3Aextension-syntax">8.16  Extension-only syntax</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aextension-operators">8.16.1  Extension operators</a>
</li><li class="li-toc"><a href="#ss%3Aextension-literals">8.16.2  Extension literals</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Ainline-records">8.17  Inline records</a>
</li><li class="li-toc"><a href="#s%3Adoc-comments">8.18  Documentation comments</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Afloating-comments">8.18.1  Floating comments</a>
</li><li class="li-toc"><a href="#ss%3Aitem-comments">8.18.2  Item comments</a>
</li><li class="li-toc"><a href="#ss%3Alabel-comments">8.18.3  Label comments</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aindex-operators">8.19  Extended indexing operators </a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Amultiindexing">8.19.1  Multi-index notation</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aempty-variants">8.20  Empty variant types</a>
</li><li class="li-toc"><a href="#s%3Aalerts">8.21  Alerts</a>
</li><li class="li-toc"><a href="#s%3Ageneralized-open">8.22  Generalized open statements</a>
</li><li class="li-toc"><a href="#s%3Abinding-operators">8.23  Binding operators</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aletops-rationale">8.23.1  Rationale</a>
</li></ul>
</li></ul>
</li></ul>
</li><li class="li-toc"><a href="#sec286">Part III  The OCaml tools</a>
<ul class="toc"><li class="li-toc">
<a href="#sec287">Chapter 9  Batch compilation (ocamlc)</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Acomp-overview">9.1  Overview of the compiler</a>
</li><li class="li-toc"><a href="#s%3Acomp-options">9.2  Options</a>
</li><li class="li-toc"><a href="#s%3Amodules-file-system">9.3  Modules and the file system</a>
</li><li class="li-toc"><a href="#s%3Acomp-errors">9.4  Common errors</a>
</li><li class="li-toc"><a href="#s%3Acomp-warnings">9.5  Warning reference</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Awarn9">9.5.1  Warning 9: missing fields in a record pattern</a>
</li><li class="li-toc"><a href="#ss%3Awarn52">9.5.2  Warning 52: fragile constant pattern</a>
</li><li class="li-toc"><a href="#ss%3Awarn57">9.5.3  Warning 57: Ambiguous or-pattern variables under guard</a>
</li></ul>
</li></ul>
</li><li class="li-toc"><a href="#sec297">Chapter 10  The toplevel system or REPL (ocaml)</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Atoplevel-options">10.1  Options</a>
</li><li class="li-toc"><a href="#s%3Atoplevel-directives">10.2  Toplevel directives</a>
</li><li class="li-toc"><a href="#s%3Atoplevel-modules">10.3  The toplevel and the module system</a>
</li><li class="li-toc"><a href="#s%3Atoplevel-common-errors">10.4  Common errors</a>
</li><li class="li-toc"><a href="#s%3Acustom-toplevel">10.5  Building custom toplevel systems: <span class="c003">ocamlmktop</span></a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aocamlmktop-options">10.5.1  Options</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aocamlnat">10.6  The native toplevel: <span class="c003">ocamlnat</span> (experimental)</a>
</li></ul>
</li><li class="li-toc"><a href="#sec305">Chapter 11  The runtime system (ocamlrun)</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Aocamlrun-overview">11.1  Overview</a>
</li><li class="li-toc"><a href="#s%3Aocamlrun-options">11.2  Options</a>
</li><li class="li-toc"><a href="#s%3Aocamlrun-dllpath">11.3  Dynamic loading of shared libraries</a>
</li><li class="li-toc"><a href="#s%3Aocamlrun-common-errors">11.4  Common errors</a>
</li></ul>
</li><li class="li-toc"><a href="#sec310">Chapter 12  Native-code compilation (ocamlopt)</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Anative-overview">12.1  Overview of the compiler</a>
</li><li class="li-toc"><a href="#s%3Anative-options">12.2  Options</a>
</li><li class="li-toc"><a href="#s%3Anative-common-errors">12.3  Common errors</a>
</li><li class="li-toc"><a href="#s%3Anative%3Arunning-executable">12.4  Running executables produced by ocamlopt</a>
</li><li class="li-toc"><a href="#s%3Acompat-native-bytecode">12.5  Compatibility with the bytecode compiler</a>
</li></ul>
</li><li class="li-toc"><a href="#sec320">Chapter 13  Lexer and parser generators (ocamllex, ocamlyacc)</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Aocamllex-overview">13.1  Overview of <span class="c003">ocamllex</span></a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aocamllex-options">13.1.1  Options</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aocamllex-syntax">13.2  Syntax of lexer definitions</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aocamllex-header-trailer">13.2.1  Header and trailer</a>
</li><li class="li-toc"><a href="#ss%3Aocamllex-named-regexp">13.2.2  Naming regular expressions</a>
</li><li class="li-toc"><a href="#ss%3Aocamllex-entry-points">13.2.3  Entry points</a>
</li><li class="li-toc"><a href="#ss%3Aocamllex-regexp">13.2.4  Regular expressions</a>
</li><li class="li-toc"><a href="#ss%3Aocamllex-actions">13.2.5  Actions</a>
</li><li class="li-toc"><a href="#ss%3Aocamllex-variables">13.2.6  Variables in regular expressions</a>
</li><li class="li-toc"><a href="#ss%3Arefill-handlers">13.2.7  Refill handlers</a>
</li><li class="li-toc"><a href="#ss%3Aocamllex-reserved-ident">13.2.8  Reserved identifiers</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aocamlyacc-overview">13.3  Overview of <span class="c003">ocamlyacc</span></a>
</li><li class="li-toc"><a href="#s%3Aocamlyacc-syntax">13.4  Syntax of grammar definitions</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aocamlyacc-header-trailer">13.4.1  Header and trailer</a>
</li><li class="li-toc"><a href="#ss%3Aocamlyacc-declarations">13.4.2  Declarations</a>
</li><li class="li-toc"><a href="#ss%3Aocamlyacc-rules">13.4.3  Rules</a>
</li><li class="li-toc"><a href="#ss%3Aocamlyacc-error-handling">13.4.4  Error handling</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aocamlyacc-options">13.5  Options</a>
</li><li class="li-toc"><a href="#s%3Alexyacc-example">13.6  A complete example</a>
</li><li class="li-toc"><a href="#s%3Alexyacc-common-errors">13.7  Common errors</a>
</li></ul>
</li><li class="li-toc"><a href="#sec341">Chapter 14  Dependency generator (ocamldep)</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Aocamldep-options">14.1  Options</a>
</li><li class="li-toc"><a href="#s%3Aocamldep-makefile">14.2  A typical Makefile</a>
</li></ul>
</li><li class="li-toc"><a href="#sec344">Chapter 15  The browser/editor (ocamlbrowser)</a>
</li><li class="li-toc"><a href="#sec345">Chapter 16  The documentation generator (ocamldoc)</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Aocamldoc-usage">16.1  Usage</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aocamldoc-invocation">16.1.1  Invocation</a>
</li><li class="li-toc"><a href="#ss%3Aocamldoc-merge">16.1.2  Merging of module information</a>
</li><li class="li-toc"><a href="#ss%3Aocamldoc-rules">16.1.3  Coding rules</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aocamldoc-comments">16.2  Syntax of documentation comments</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aocamldoc-placement">16.2.1  Placement of documentation comments</a>
</li><li class="li-toc"><a href="#ss%3Aocamldoc-stop">16.2.2  The Stop special comment</a>
</li><li class="li-toc"><a href="#ss%3Aocamldoc-syntax">16.2.3  Syntax of documentation comments</a>
</li><li class="li-toc"><a href="#ss%3Aocamldoc-formatting">16.2.4  Text formatting</a>
</li><li class="li-toc"><a href="#ss%3Aocamldoc-tags">16.2.5  Documentation tags (@-tags)</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aocamldoc-custom-generators">16.3  Custom generators</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aocamldoc-generators">16.3.1  The generator modules</a>
</li><li class="li-toc"><a href="#ss%3Aocamldoc-handling-custom-tags">16.3.2  Handling custom tags</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aocamldoc-adding-flags">16.4  Adding command line options</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aocamldoc-compilation-and-usage">16.4.1  Compilation and usage</a>
</li></ul>
</li></ul>
</li><li class="li-toc"><a href="#sec382">Chapter 17  The debugger (ocamldebug)</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Adebugger-compilation">17.1  Compiling for debugging</a>
</li><li class="li-toc"><a href="#s%3Adebugger-invocation">17.2  Invocation</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Adebugger-start">17.2.1  Starting the debugger</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-init-file">17.2.2  Initialization file</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-exut">17.2.3  Exiting the debugger</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Adebugger-commands">17.3  Commands</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Adebugger-help">17.3.1  Getting help</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-state">17.3.2  Accessing the debugger state</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Adebugger-execution">17.4  Executing a program</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Adebugger-events">17.4.1  Events</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-starting-program">17.4.2  Starting the debugged program</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-running">17.4.3  Running the program</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-time-travel">17.4.4  Time travel</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-kill">17.4.5  Killing the program</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Abreakpoints">17.5  Breakpoints</a>
</li><li class="li-toc"><a href="#s%3Adebugger-callstack">17.6  The call stack</a>
</li><li class="li-toc"><a href="#s%3Adebugger-examining-values">17.7  Examining variable values</a>
</li><li class="li-toc"><a href="#s%3Adebugger-control">17.8  Controlling the debugger</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Adebugger-name-and-arguments">17.8.1  Setting the program name and arguments</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-loading">17.8.2  How programs are loaded</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-search-path">17.8.3  Search path for files</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-working-dir">17.8.4  Working directory</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-reverse-execution">17.8.5  Turning reverse execution on and off</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-fork">17.8.6  Behavior of the debugger with respect to <span class="c003">fork</span></a>
</li><li class="li-toc"><a href="#ss%3Adebugger-stop-at-new-load">17.8.7  Stopping execution when new code is loaded</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-communication">17.8.8  Communication between the debugger and the program</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-fine-tuning">17.8.9  Fine-tuning the debugger</a>
</li><li class="li-toc"><a href="#ss%3Adebugger-printers">17.8.10  User-defined printers</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Adebugger-misc-cmds">17.9  Miscellaneous commands</a>
</li><li class="li-toc"><a href="#s%3Ainf-debugger">17.10  Running the debugger under Emacs</a>
</li></ul>
</li><li class="li-toc"><a href="#sec413">Chapter 18  Profiling (ocamlprof)</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Aocamlprof-compiling">18.1  Compiling for profiling</a>
</li><li class="li-toc"><a href="#s%3Aocamlprof-profiling">18.2  Profiling an execution</a>
</li><li class="li-toc"><a href="#s%3Aocamlprof-printing">18.3  Printing profiling information</a>
</li><li class="li-toc"><a href="#s%3Aocamlprof-time-profiling">18.4  Time profiling</a>
</li></ul>
</li><li class="li-toc"><a href="#sec421">Chapter 19  The ocamlbuild compilation manager</a>
</li><li class="li-toc"><a href="#c%3Aintf-c">Chapter 20  Interfacing C with OCaml</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Ac-overview">20.1  Overview and compilation information</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Ac-prim-decl">20.1.1  Declaring primitives</a>
</li><li class="li-toc"><a href="#ss%3Ac-prim-impl">20.1.2  Implementing primitives</a>
</li><li class="li-toc"><a href="#ss%3Astaticlink-c-code">20.1.3  Statically linking C code with OCaml code</a>
</li><li class="li-toc"><a href="#ss%3Adynlink-c-code">20.1.4  Dynamically linking C code with OCaml code</a>
</li><li class="li-toc"><a href="#ss%3Ac-static-vs-dynamic">20.1.5  Choosing between static linking and dynamic linking</a>
</li><li class="li-toc"><a href="#ss%3Acustom-runtime">20.1.6  Building standalone custom runtime systems</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Ac-value">20.2  The <span class="c003">value</span> type</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Ac-int">20.2.1  Integer values</a>
</li><li class="li-toc"><a href="#ss%3Ac-blocks">20.2.2  Blocks</a>
</li><li class="li-toc"><a href="#ss%3Ac-outside-head">20.2.3  Pointers outside the heap</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Ac-ocaml-datatype-repr">20.3  Representation of OCaml data types</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Ac-atomic">20.3.1  Atomic types</a>
</li><li class="li-toc"><a href="#ss%3Ac-tuples-and-records">20.3.2  Tuples and records</a>
</li><li class="li-toc"><a href="#ss%3Ac-arrays">20.3.3  Arrays</a>
</li><li class="li-toc"><a href="#ss%3Ac-concrete-datatypes">20.3.4  Concrete data types</a>
</li><li class="li-toc"><a href="#ss%3Ac-objects">20.3.5  Objects</a>
</li><li class="li-toc"><a href="#ss%3Ac-polyvar">20.3.6  Polymorphic variants</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Ac-ops-on-values">20.4  Operations on values</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Ac-kind-tests">20.4.1  Kind tests</a>
</li><li class="li-toc"><a href="#ss%3Ac-int-ops">20.4.2  Operations on integers</a>
</li><li class="li-toc"><a href="#ss%3Ac-block-access">20.4.3  Accessing blocks</a>
</li><li class="li-toc"><a href="#ss%3Ac-block-allocation">20.4.4  Allocating blocks</a>
</li><li class="li-toc"><a href="#ss%3Ac-exceptions">20.4.5  Raising exceptions</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Ac-gc-harmony">20.5  Living in harmony with the garbage collector</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Ac-simple-gc-harmony">20.5.1  Simple interface</a>
</li><li class="li-toc"><a href="#ss%3Ac-low-level-gc-harmony">20.5.2  Low-level interface</a>
</li><li class="li-toc"><a href="#ss%3Ac-process-pending-actions">20.5.3  Pending actions and asynchronous exceptions</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Ac-intf-example">20.6  A complete example</a>
</li><li class="li-toc"><a href="#s%3Ac-callback">20.7  Advanced topic: callbacks from C to OCaml</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Ac-callbacks">20.7.1  Applying OCaml closures from C</a>
</li><li class="li-toc"><a href="#ss%3Ac-closures">20.7.2  Obtaining or registering OCaml closures for use in C functions</a>
</li><li class="li-toc"><a href="#ss%3Ac-register-exn">20.7.3  Registering OCaml exceptions for use in C functions</a>
</li><li class="li-toc"><a href="#ss%3Amain-c">20.7.4  Main program in C</a>
</li><li class="li-toc"><a href="#ss%3Ac-embedded-code">20.7.5  Embedding the OCaml code in the C code</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Ac-advexample">20.8  Advanced example with callbacks</a>
</li><li class="li-toc"><a href="#s%3Ac-custom">20.9  Advanced topic: custom blocks</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Ac-custom-ops">20.9.1  The <span class="c003">struct custom_operations</span></a>
</li><li class="li-toc"><a href="#ss%3Ac-custom-alloc">20.9.2  Allocating custom blocks</a>
</li><li class="li-toc"><a href="#ss%3Ac-custom-access">20.9.3  Accessing custom blocks</a>
</li><li class="li-toc"><a href="#ss%3Ac-custom-serialization">20.9.4  Writing custom serialization and deserialization functions</a>
</li><li class="li-toc"><a href="#ss%3Ac-custom-idents">20.9.5  Choosing identifiers</a>
</li><li class="li-toc"><a href="#ss%3Ac-finalized">20.9.6  Finalized blocks</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3AC-Bigarrays">20.10  Advanced topic: Bigarrays and the OCaml-C interface</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3AC-Bigarrays-include">20.10.1  Include file</a>
</li><li class="li-toc"><a href="#ss%3AC-Bigarrays-access">20.10.2  Accessing an OCaml bigarray from C or Fortran</a>
</li><li class="li-toc"><a href="#ss%3AC-Bigarrays-wrap">20.10.3  Wrapping a C or Fortran array as an OCaml Bigarray</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3AC-cheaper-call">20.11  Advanced topic: cheaper C call</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Ac-unboxed">20.11.1  Passing unboxed values</a>
</li><li class="li-toc"><a href="#ss%3Ac-direct-call">20.11.2  Direct C call</a>
</li><li class="li-toc"><a href="#ss%3Ac-direct-call-example">20.11.3  Example: calling C library functions without indirection</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3AC-multithreading">20.12  Advanced topic: multithreading</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Ac-thread-register">20.12.1  Registering threads created from C</a>
</li><li class="li-toc"><a href="#ss%3Aparallel-execution-long-running-c-code">20.12.2  Parallel execution of long-running C code</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Ainterfacing-windows-unicode-apis">20.13  Advanced topic: interfacing with Windows Unicode APIs</a>
</li><li class="li-toc"><a href="#s%3Aocamlmklib">20.14  Building mixed C/OCaml libraries: <span class="c003">ocamlmklib</span></a>
</li><li class="li-toc"><a href="#s%3Ac-internal-guidelines">20.15  Cautionary words: the internal runtime API</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Ac-internals">20.15.1  Internal variables and CAML_INTERNALS</a>
</li><li class="li-toc"><a href="#ss%3Ac-internal-macros">20.15.2  OCaml version macros</a>
</li></ul>
</li></ul>
</li><li class="li-toc"><a href="#sec496">Chapter 21  Optimisation with Flambda</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Aflambda-overview">21.1  Overview</a>
</li><li class="li-toc"><a href="#s%3Aflambda-cli">21.2  Command-line flags</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aflambda-rounds">21.2.1  Specification of optimisation parameters by round</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aflambda-inlining">21.3  Inlining</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aflambda-classic">21.3.1  Classic inlining heuristic</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-inlining-overview">21.3.2  Overview of “Flambda” inlining heuristics</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-by-constructs">21.3.3  Handling of specific language constructs</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-inlining-reports">21.3.4  Inlining reports</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-assessment-inlining">21.3.5  Assessment of inlining benefit</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-speculation">21.3.6  Control of speculation</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aflambda-specialisation">21.4  Specialisation</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aflambda-assessment-specialisation">21.4.1  Assessment of specialisation benefit</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aflambda-defaults">21.5  Default settings of parameters</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aflambda-o2">21.5.1  Settings at -O2 optimisation level</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-o3">21.5.2  Settings at -O3 optimisation level</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aflambda-manual-control">21.6  Manual control of inlining and specialisation</a>
</li><li class="li-toc"><a href="#s%3Aflambda-simplification">21.7  Simplification</a>
</li><li class="li-toc"><a href="#s%3Aflambda-other-transfs">21.8  Other code motion transformations</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aflambda-lift-const">21.8.1  Lifting of constants</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-lift-toplevel-let">21.8.2  Lifting of toplevel let bindings</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aflambda-unboxing">21.9  Unboxing transformations</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aflambda-unbox-fvs">21.9.1  Unboxing of closure variables</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-unbox-spec-args">21.9.2  Unboxing of specialised arguments</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-unbox-closures">21.9.3  Unboxing of closures</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aflambda-remove-unused">21.10  Removal of unused code and values</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aflambda-redundant-let">21.10.1  Removal of redundant let expressions</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-redundant">21.10.2  Removal of redundant program constructs</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-remove-unused-args">21.10.3  Removal of unused arguments</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-removal-closure-vars">21.10.4  Removal of unused closure variables</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aflambda-other">21.11  Other code transformations</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aflambda-non-escaping-refs">21.11.1  Transformation of non-escaping references into mutable variables</a>
</li><li class="li-toc"><a href="#ss%3Aflambda-subst-closure-vars">21.11.2  Substitution of closure variables for specialised arguments</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aflambda-effects">21.12  Treatment of effects</a>
</li><li class="li-toc"><a href="#s%3Aflambda-static-modules">21.13  Compilation of statically-allocated modules</a>
</li><li class="li-toc"><a href="#s%3Aflambda-inhibition">21.14  Inhibition of optimisation</a>
</li><li class="li-toc"><a href="#s%3Aflambda-unsafe">21.15  Use of unsafe operations</a>
</li><li class="li-toc"><a href="#s%3Aflambda-glossary">21.16  Glossary</a>
</li></ul>
</li><li class="li-toc"><a href="#sec547">Chapter 22  Memory profiling with Spacetime</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Aspacetime-overview">22.1  Overview</a>
</li><li class="li-toc"><a href="#s%3Aspacetime-howto">22.2  How to use it</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aspacetime-building">22.2.1  Building</a>
</li><li class="li-toc"><a href="#ss%3Aspacetime-running">22.2.2  Running</a>
</li><li class="li-toc"><a href="#ss%3Aspacetime-analysis">22.2.3  Analysis</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aspacetime-runtimeoverhead">22.3  Runtime overhead</a>
</li><li class="li-toc"><a href="#s%3Aspacetime-dev">22.4  For developers</a>
</li></ul>
</li><li class="li-toc"><a href="#sec555">Chapter 23  Fuzzing with afl-fuzz</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Aafl-overview">23.1  Overview</a>
</li><li class="li-toc"><a href="#s%3Aafl-generate">23.2  Generating instrumentation</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Aafl-advanced">23.2.1  Advanced options</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Aafl-example">23.3  Example</a>
</li></ul>
</li><li class="li-toc"><a href="#sec560">Chapter 24  Runtime tracing with the instrumented runtime</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Ainstr-runtime-overview">24.1  Overview</a>
</li><li class="li-toc"><a href="#s%3Ainstr-runtime-enabling">24.2  Enabling runtime instrumentation</a>
</li><li class="li-toc"><a href="#s%3Ainstr-runtime-read">24.3  Reading traces</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Ainstr-runtime-tools">24.3.1  eventlog-tools</a>
</li><li class="li-toc"><a href="#ss%3Ainstr-runtime-babeltrace">24.3.2  babeltrace</a>
</li></ul>
</li><li class="li-toc"><a href="#s%3Ainstr-runtime-more">24.4  Controlling instrumentation and limitations</a>
<ul class="toc"><li class="li-toc">
<a href="#ss%3Ainstr-runtime-prefix">24.4.1  Trace filename</a>
</li><li class="li-toc"><a href="#ss%3Ainstr-runtime-pause">24.4.2  Pausing and resuming tracing</a>
</li><li class="li-toc"><a href="#ss%3Ainstr-runtime-limitations">24.4.3  Limitations</a>
</li></ul>
</li></ul>
</li></ul>
</li><li class="li-toc"><a href="#sec571">Part IV  The OCaml library</a>
<ul class="toc"><li class="li-toc">
<a href="#sec572">Chapter 25  The core library</a>
<ul class="toc"><li class="li-toc">
<a href="#s%3Acore-builtins">25.1  Built-in types and predefined exceptions</a>
</li><li class="li-toc"><a href="#s%3Astdlib-module">25.2  Module <span class="c003">Stdlib</span>: the initially opened module</a>
</li></ul>
</li><li class="li-toc"><a href="#sec578">Chapter 26  The standard library</a>
</li><li class="li-toc"><a href="#sec580">Chapter 27  The compiler front-end</a>
</li><li class="li-toc"><a href="#sec581">Chapter 28  The unix library: Unix system calls</a>
</li><li class="li-toc"><a href="#sec582">Chapter 29  The num library: arbitrary-precision rational arithmetic</a>
</li><li class="li-toc"><a href="#sec583">Chapter 30  The str library: regular expressions and string processing</a>
</li><li class="li-toc"><a href="#sec584">Chapter 31  The threads library</a>
</li><li class="li-toc"><a href="#sec585">Chapter 32  The graphics library</a>
</li><li class="li-toc"><a href="#sec586">Chapter 33  The dynlink library: dynamic loading and linking of object files</a>
</li><li class="li-toc"><a href="#sec587">Chapter 34  The bigarray library</a>
</li></ul>
</li><li class="li-toc"><a href="#sec588">Part V  Appendix</a>
</li></ul><!--TOC chapter id="sec2" Foreword-->
<h1 class="chapter" id="sec2">Foreword</h1><!--SEC END --><!--NAME foreword.html-->
<p>This manual documents the release 4.11 of the OCaml
system. It is organized as follows.
</p><ul class="itemize"><li class="li-itemize">
Part <a href="#p%3Atutorials">I</a>, “An introduction to OCaml”,
gives an overview of the language.
</li><li class="li-itemize">Part <a href="#p%3Arefman">II</a>, “The OCaml language”, is the
reference description of the language.
</li><li class="li-itemize">Part <a href="#p%3Acommands">III</a>, “The OCaml tools”, documents
the compilers, toplevel system, and programming utilities.
</li><li class="li-itemize">Part <a href="#p%3Alibrary">IV</a>, “The OCaml library”, describes the
modules provided in the standard library.

</li></ul><!--TOC section id="conventions" Conventions-->
<h2 class="section" id="conventions"><a class="section-anchor" href="#conventions" aria-hidden="true"></a>Conventions</h2><!--SEC END --><p>OCaml runs on several operating systems. The parts of
this manual that are specific to one operating system are presented as
shown below:</p><blockquote class="quote"><span class="c007">Unix:</span>   This is material specific to the Unix family of operating
systems, including Linux and macOS.
</blockquote><blockquote class="quote"><span class="c007">Windows:</span>   This is material specific to Microsoft Windows
(XP, Vista, 7, 8, 10).
</blockquote><!--TOC section id="license" License-->
<h2 class="section" id="license"><a class="section-anchor" href="#license" aria-hidden="true"></a>License</h2><!--SEC END --><p>The OCaml system is copyright © 1996–2020
Institut National de Recherche en Informatique et en
Automatique (INRIA).
INRIA holds all ownership rights to the OCaml system.</p><p>The OCaml system is open source and can be freely
redistributed. See the file <span class="c003">LICENSE</span> in the distribution for
licensing information.</p><p>The OCaml documentation and user’s manual is
copyright © 2020
Institut National de Recherche en Informatique et en
Automatique (INRIA).</p><p>
<a id="cc_license_logo" rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png"></a>
The OCaml documentation and user's manual is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.

</p><!--TOC section id="availability" Availability-->
<h2 class="section" id="availability"><a class="section-anchor" href="#availability" aria-hidden="true"></a>Availability</h2><!--SEC END --><p>
The complete OCaml distribution can be accessed via the
<a href="https://ocaml.org/">ocaml.org website</a>.
This site contains a lot of additional information on OCaml.

</p>
<!--TOC part id="sec6" Part I  An introduction to OCaml-->
<table class="center"><tr><td><h1 class="part" id="sec6">Part I<br>
An introduction to OCaml</h1></td></tr>
</table><!--SEC END --><p>
<a id="p:tutorials"></a>
</p>
<!--TOC chapter id="sec7" Chapter 1  The core language-->
<h1 class="chapter" id="sec7">Chapter 1  The core language</h1><!--SEC END --><p> <a id="c:core-xamples"></a>
</p><!--NAME coreexamples.html-->
<p>This part of the manual is a tutorial introduction to the
OCaml language. A good familiarity with programming in a conventional
languages (say, C or Java) is assumed, but no prior exposure to
functional languages is required. The present chapter introduces the
core language. Chapter <a href="#c%3Amoduleexamples">2</a> deals with the
module system, chapter <a href="#c%3Aobjectexamples">3</a> with the
object-oriented features, chapter <a href="#c%3Alabl-examples">4</a> with
extensions to the core language (labeled arguments and polymorphic
variants), and chapter <a href="#c%3Aadvexamples">6</a> gives some advanced examples.</p>
<!--TOC section id="s:basics" 1.1  Basics-->
<h2 class="section" id="s:basics"><a class="section-anchor" href="#s:basics" aria-hidden="true"></a>1.1  Basics</h2><!--SEC END --><p>For this overview of OCaml, we use the interactive system, which
is started by running <span class="c003">ocaml</span> from the Unix shell, or by launching the
<span class="c003">OCamlwin.exe</span> application under Windows. This tutorial is presented
as the transcript of a session with the interactive system:
lines starting with <span class="c003">#</span> represent user input; the system responses are
printed below, without a leading <span class="c003">#</span>.</p><p>Under the interactive system, the user types OCaml phrases terminated
by <span class="c003">;;</span> in response to the <span class="c003">#</span> prompt, and the system compiles them
on the fly, executes them, and prints the outcome of evaluation.
Phrases are either simple expressions, or <span class="c003">let</span> definitions of
identifiers (either values or functions).


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> 1+2*3;;</div>



<div class="pre caml-output ok">- : int = 7</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> pi = 4.0 *. atan 1.0;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> pi : float = 3.14159265358979312</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> square x = x *. x;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> square : float -&gt; float = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> square (sin pi) +. square (cos pi);;</div>



<div class="pre caml-output ok">- : float = 1.</div></div>

</div><p>


The OCaml system computes both the value and the type for
each phrase. Even function parameters need no explicit type declaration:
the system infers their types from their usage in the
function. Notice also that integers and floating-point numbers are
distinct types, with distinct operators: <span class="c003">+</span> and <span class="c003">*</span> operate on
integers, but <span class="c003">+.</span> and <span class="c003">*.</span> operate on floats.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlhighlight">1.0</span> * 2;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type float but an expression was expected of type
         int</div></div>

</div><p>Recursive functions are defined with the <span class="c003">let rec</span> binding:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> fib n =
   <span class="ocamlkeyword">if</span> n &lt; 2 <span class="ocamlkeyword">then</span> n <span class="ocamlkeyword">else</span> fib (n-1) + fib (n-2);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> fib : int -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> fib 10;;</div>



<div class="pre caml-output ok">- : int = 55</div></div>

</div>
<!--TOC section id="s:datatypes" 1.2  Data types-->
<h2 class="section" id="s:datatypes"><a class="section-anchor" href="#s:datatypes" aria-hidden="true"></a>1.2  Data types</h2><!--SEC END --><p>In addition to integers and floating-point numbers, OCaml offers the
usual basic data types:
</p><ul class="itemize"><li class="li-itemize">booleans


<div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> (1 &lt; 2) = <span class="ocamlkeyword">false</span>;;</div>



<div class="pre caml-output ok">- : bool = <span class="ocamlkeyword">false</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> one = <span class="ocamlkeyword">if</span> <span class="ocamlkeyword">true</span> <span class="ocamlkeyword">then</span> 1 <span class="ocamlkeyword">else</span> 2;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> one : int = 1</div></div>

</div>


</li><li class="li-itemize">characters


<div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">  'a';;</div>



<div class="pre caml-output ok">- : char = 'a'</div></div>
<div class="ocaml">



<div class="pre caml-input">  int_of_char '\n';;</div>



<div class="pre caml-output ok">- : int = 10</div></div>

</div>


</li><li class="li-itemize">immutable character strings


<div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlstring">"Hello"</span> ^ <span class="ocamlstring">" "</span> ^ <span class="ocamlstring">"world"</span>;;</div>



<div class="pre caml-output ok">- : string = <span class="ocamlstring">"Hello world"</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlstring">{|This is a quoted string, here, neither \ nor " are special characters|}</span>;;</div>



<div class="pre caml-output ok">- : string =
<span class="ocamlstring">"This is a quoted string, here, neither \\ nor \" are special characters"</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlstring">{|"\\"|}</span>=<span class="ocamlstring">"\"\\\\\""</span>;;</div>



<div class="pre caml-output ok">- : bool = <span class="ocamlkeyword">true</span></div></div>
<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlstring">{delimiter|the end of this|}quoted string is here|delimiter}</span>
 =           <span class="ocamlstring">"the end of this|}quoted string is here"</span>;;</div>



<div class="pre caml-output ok">- : bool = <span class="ocamlkeyword">true</span></div></div>

</div>


</li></ul><p>Predefined data structures include tuples, arrays, and lists. There are also
general mechanisms for defining your own data structures, such as records and
variants, which will be covered in more detail later; for now, we concentrate
on lists. Lists are either given in extension as a bracketed list of
semicolon-separated elements, or built from the empty list <span class="c003">[]</span>
(pronounce “nil”) by adding elements in front using the <span class="c003">::</span>
(“cons”) operator.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> l = [<span class="ocamlstring">"is"</span>; <span class="ocamlstring">"a"</span>; <span class="ocamlstring">"tale"</span>; <span class="ocamlstring">"told"</span>; <span class="ocamlstring">"etc."</span>];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> l : string list = [<span class="ocamlstring">"is"</span>; <span class="ocamlstring">"a"</span>; <span class="ocamlstring">"tale"</span>; <span class="ocamlstring">"told"</span>; <span class="ocamlstring">"etc."</span>]</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlstring">"Life"</span> :: l;;</div>



<div class="pre caml-output ok">- : string list = [<span class="ocamlstring">"Life"</span>; <span class="ocamlstring">"is"</span>; <span class="ocamlstring">"a"</span>; <span class="ocamlstring">"tale"</span>; <span class="ocamlstring">"told"</span>; <span class="ocamlstring">"etc."</span>]</div></div>

</div><p>


As with all other OCaml data structures, lists do not need to be
explicitly allocated and deallocated from memory: all memory
management is entirely automatic in OCaml. Similarly, there is no
explicit handling of pointers: the OCaml compiler silently introduces
pointers where necessary.</p><p>As with most OCaml data structures, inspecting and destructuring lists
is performed by pattern-matching. List patterns have exactly the same
form as list expressions, with identifiers representing unspecified
parts of the list. As an example, here is insertion sort on a list:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> sort lst =
   <span class="ocamlkeyword">match</span> lst <span class="ocamlkeyword">with</span>
     [] -&gt; []
   | head :: tail -&gt; insert head (sort tail)
 <span class="ocamlkeyword">and</span> insert elt lst =
   <span class="ocamlkeyword">match</span> lst <span class="ocamlkeyword">with</span>
     [] -&gt; [elt]
   | head :: tail -&gt; <span class="ocamlkeyword">if</span> elt &lt;= head <span class="ocamlkeyword">then</span> elt :: lst <span class="ocamlkeyword">else</span> head :: insert elt tail
 ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> sort : 'a list -&gt; 'a list = &lt;<span class="ocamlkeyword">fun</span>&gt;
<span class="ocamlkeyword">val</span> insert : 'a -&gt; 'a list -&gt; 'a list = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> sort l;;</div>



<div class="pre caml-output ok">- : string list = [<span class="ocamlstring">"a"</span>; <span class="ocamlstring">"etc."</span>; <span class="ocamlstring">"is"</span>; <span class="ocamlstring">"tale"</span>; <span class="ocamlstring">"told"</span>]</div></div>

</div><p>The type inferred for <span class="c003">sort</span>, <span class="c003">'a list -&gt; 'a list</span>, means that <span class="c003">sort</span>
can actually apply to lists of any type, and returns a list of the
same type. The type <span class="c003">'a</span> is a <em>type variable</em>, and stands for any
given type. The reason why <span class="c003">sort</span> can apply to lists of any type is
that the comparisons (<span class="c003">=</span>, <span class="c003">&lt;=</span>, etc.) are <em>polymorphic</em> in OCaml:
they operate between any two values of the same type. This makes
<span class="c003">sort</span> itself polymorphic over all list types.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> sort [6;2;5;3];;</div>



<div class="pre caml-output ok">- : int list = [2; 3; 5; 6]</div></div>
<div class="ocaml">



<div class="pre caml-input"> sort [3.14; 2.718];;</div>



<div class="pre caml-output ok">- : float list = [2.718; 3.14]</div></div>

</div><p>The <span class="c003">sort</span> function above does not modify its input list: it builds
and returns a new list containing the same elements as the input list,
in ascending order. There is actually no way in OCaml to modify
a list in-place once it is built: we say that lists are <em>immutable</em>
data structures. Most OCaml data structures are immutable, but a few
(most notably arrays) are <em>mutable</em>, meaning that they can be
modified in-place at any time.</p><p>The OCaml notation for the type of a function with multiple arguments is <br>
<span class="c003">arg1_type -&gt; arg2_type -&gt; ... -&gt; return_type</span>. For example,
the type inferred for <span class="c003">insert</span>, <span class="c003">'a -&gt; 'a list -&gt; 'a list</span>, means that <span class="c003">insert</span>
takes two arguments, an element of any type <span class="c003">'a</span> and a list with elements of
the same type <span class="c003">'a</span> and returns a list of the same type.
</p>
<!--TOC section id="s:functions-as-values" 1.3  Functions as values-->
<h2 class="section" id="s:functions-as-values"><a class="section-anchor" href="#s:functions-as-values" aria-hidden="true"></a>1.3  Functions as values</h2><!--SEC END --><p>OCaml is a functional language: functions in the full mathematical
sense are supported and can be passed around freely just as any other
piece of data. For instance, here is a <span class="c003">deriv</span> function that takes any
float function as argument and returns an approximation of its
derivative function:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> deriv f dx = <span class="ocamlkeyword">function</span> x -&gt; (f (x +. dx) -. f x) /. dx;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> deriv : (float -&gt; float) -&gt; float -&gt; float -&gt; float = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> sin' = deriv sin 1e-6;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> sin' : float -&gt; float = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> sin' pi;;</div>



<div class="pre caml-output ok">- : float = -1.00000000013961143</div></div>

</div><p>


Even function composition is definable:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> compose f g = <span class="ocamlkeyword">function</span> x -&gt; f (g x);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> compose : ('a -&gt; 'b) -&gt; ('c -&gt; 'a) -&gt; 'c -&gt; 'b = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> cos2 = compose square cos;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> cos2 : float -&gt; float = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>Functions that take other functions as arguments are called
“functionals”, or “higher-order functions”. Functionals are
especially useful to provide iterators or similar generic operations
over a data structure. For instance, the standard OCaml library
provides a <span class="c003">List.map</span> functional that applies a given function to each
element of a list, and returns the list of the results:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> List.map (<span class="ocamlkeyword">function</span> n -&gt; n * 2 + 1) [0;1;2;3;4];;</div>



<div class="pre caml-output ok">- : int list = [1; 3; 5; 7; 9]</div></div>

</div><p>


This functional, along with a number of other list and array
functionals, is predefined because it is often useful, but there is
nothing magic with it: it can easily be defined as follows.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> map f l =
   <span class="ocamlkeyword">match</span> l <span class="ocamlkeyword">with</span>
     [] -&gt; []
   | hd :: tl -&gt; f hd :: map f tl;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> map : ('a -&gt; 'b) -&gt; 'a list -&gt; 'b list = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div>
<!--TOC section id="s:tut-recvariants" 1.4  Records and variants-->
<h2 class="section" id="s:tut-recvariants"><a class="section-anchor" href="#s:tut-recvariants" aria-hidden="true"></a>1.4  Records and variants</h2><!--SEC END --><p>User-defined data structures include records and variants. Both are
defined with the <span class="c003">type</span> declaration. Here, we declare a record type to
represent rational numbers.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> ratio = {num: int; denom: int};;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> ratio = { num : int; denom : int; }</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> add_ratio r1 r2 =
   {num = r1.num * r2.denom + r2.num * r1.denom;
    denom = r1.denom * r2.denom};;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> add_ratio : ratio -&gt; ratio -&gt; ratio = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> add_ratio {num=1; denom=3} {num=2; denom=5};;</div>



<div class="pre caml-output ok">- : ratio = {num = 11; denom = 15}</div></div>

</div><p>


Record fields can also be accessed through pattern-matching:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> integer_part r =
   <span class="ocamlkeyword">match</span> r <span class="ocamlkeyword">with</span>
     {num=num; denom=denom} -&gt; num / denom;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> integer_part : ratio -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


Since there is only one case in this pattern matching, it
is safe to expand directly the argument <span class="c003">r</span> in a record pattern:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> integer_part {num=num; denom=denom} = num / denom;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> integer_part : ratio -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


Unneeded fields can be omitted:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> get_denom {denom=denom} = denom;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> get_denom : ratio -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


Optionally, missing fields can be made explicit by ending the list of
fields with a trailing wildcard <span class="c003">_</span>::


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> get_num {num=num; _ } = num;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> get_num : ratio -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


When both sides of the <span class="c003">=</span> sign are the same, it is possible to avoid
repeating the field name by eliding the <span class="c003">=field</span> part:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> integer_part {num; denom} = num / denom;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> integer_part : ratio -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


This short notation for fields also works when constructing records:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> ratio num denom = {num; denom};;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> ratio : int -&gt; int -&gt; ratio = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


At last, it is possible to update few fields of a record at once:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> integer_product integer ratio = { ratio <span class="ocamlkeyword">with</span> num = integer * ratio.num };;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> integer_product : int -&gt; ratio -&gt; ratio = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


With this functional update notation, the record on the left-hand side
of <span class="c003">with</span> is copied except for the fields on the right-hand side which
are updated.</p><p>The declaration of a variant type lists all possible forms for values
of that type. Each case is identified by a name, called a constructor,
which serves both for constructing values of the variant type and
inspecting them by pattern-matching. Constructor names are capitalized
to distinguish them from variable names (which must start with a
lowercase letter). For instance, here is a variant
type for doing mixed arithmetic (integers and floats):


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> number = Int <span class="ocamlkeyword">of</span> int | Float <span class="ocamlkeyword">of</span> float | Error;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> number = Int <span class="ocamlkeyword">of</span> int | Float <span class="ocamlkeyword">of</span> float | Error</div></div>

</div><p>


This declaration expresses that a value of type <span class="c003">number</span> is either an
integer, a floating-point number, or the constant <span class="c003">Error</span> representing
the result of an invalid operation (e.g. a division by zero).</p><p>Enumerated types are a special case of variant types, where all
alternatives are constants:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> sign = Positive | Negative;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> sign = Positive | Negative</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> sign_int n = <span class="ocamlkeyword">if</span> n &gt;= 0 <span class="ocamlkeyword">then</span> Positive <span class="ocamlkeyword">else</span> Negative;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> sign_int : int -&gt; sign = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>To define arithmetic operations for the <span class="c003">number</span> type, we use
pattern-matching on the two numbers involved:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> add_num n1 n2 =
   <span class="ocamlkeyword">match</span> (n1, n2) <span class="ocamlkeyword">with</span>
     (Int i1, Int i2) -&gt;
       <span class="ocamlcomment">(* Check for overflow of integer addition *)</span>
       <span class="ocamlkeyword">if</span> sign_int i1 = sign_int i2 &amp;&amp; sign_int (i1 + i2) &lt;&gt; sign_int i1
       <span class="ocamlkeyword">then</span> Float(float i1 +. float i2)
       <span class="ocamlkeyword">else</span> Int(i1 + i2)
   | (Int i1, Float f2) -&gt; Float(float i1 +. f2)
   | (Float f1, Int i2) -&gt; Float(f1 +. float i2)
   | (Float f1, Float f2) -&gt; Float(f1 +. f2)
   | (Error, _) -&gt; Error
   | (_, Error) -&gt; Error;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> add_num : number -&gt; number -&gt; number = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> add_num (Int 123) (Float 3.14159);;</div>



<div class="pre caml-output ok">- : number = Float 126.14159</div></div>

</div><p>Another interesting example of variant type is the built-in
<span class="c003">'a option</span> type which represents either a value of type <span class="c003">'a</span> or an
absence of value:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> 'a option = Some <span class="ocamlkeyword">of</span> 'a | None;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> 'a option = Some <span class="ocamlkeyword">of</span> 'a | None</div></div>

</div><p>


This type is particularly useful when defining function that can
fail in common situations, for instance


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> safe_square_root x = <span class="ocamlkeyword">if</span> x &gt; 0. <span class="ocamlkeyword">then</span> Some(sqrt x) <span class="ocamlkeyword">else</span> None;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> safe_square_root : float -&gt; float option = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>The most common usage of variant types is to describe recursive data
structures. Consider for example the type of binary trees:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> 'a btree = Empty | Node <span class="ocamlkeyword">of</span> 'a * 'a btree * 'a btree;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> 'a btree = Empty | Node <span class="ocamlkeyword">of</span> 'a * 'a btree * 'a btree</div></div>

</div><p>


This definition reads as follows: a binary tree containing values of
type <span class="c003">'a</span> (an arbitrary type) is either empty, or is a node containing
one value of type <span class="c003">'a</span> and two subtrees also containing values of type
<span class="c003">'a</span>, that is, two <span class="c003">'a btree</span>.</p><p>Operations on binary trees are naturally expressed as recursive functions
following the same structure as the type definition itself. For
instance, here are functions performing lookup and insertion in
ordered binary trees (elements increase from left to right):


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> member x btree =
   <span class="ocamlkeyword">match</span> btree <span class="ocamlkeyword">with</span>
     Empty -&gt; <span class="ocamlkeyword">false</span>
   | Node(y, left, right) -&gt;
       <span class="ocamlkeyword">if</span> x = y <span class="ocamlkeyword">then</span> <span class="ocamlkeyword">true</span> <span class="ocamlkeyword">else</span>
       <span class="ocamlkeyword">if</span> x &lt; y <span class="ocamlkeyword">then</span> member x left <span class="ocamlkeyword">else</span> member x right;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> member : 'a -&gt; 'a btree -&gt; bool = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> insert x btree =
   <span class="ocamlkeyword">match</span> btree <span class="ocamlkeyword">with</span>
     Empty -&gt; Node(x, Empty, Empty)
   | Node(y, left, right) -&gt;
       <span class="ocamlkeyword">if</span> x &lt;= y <span class="ocamlkeyword">then</span> Node(y, insert x left, right)
                 <span class="ocamlkeyword">else</span> Node(y, left, insert x right);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> insert : 'a -&gt; 'a btree -&gt; 'a btree = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div>
<!--TOC subsection id="ss:record-and-variant-disambiguation" 1.4.1  Record and variant disambiguation-->
<h3 class="subsection" id="ss:record-and-variant-disambiguation"><a class="section-anchor" href="#ss:record-and-variant-disambiguation" aria-hidden="true"></a>1.4.1  Record and variant disambiguation</h3><!--SEC END --><p>
( This subsection can be skipped on the first reading )</p><p>Astute readers may have wondered what happens when two or more record
fields or constructors share the same name</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> first_record  = { x:int; y:int; z:int }
 <span class="ocamlkeyword">type</span> middle_record = { x:int; z:int }
 <span class="ocamlkeyword">type</span> last_record   = { x:int };;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> first_variant = A | B | C
 <span class="ocamlkeyword">type</span> last_variant  = A;;</div></div>

</div><p>The answer is that when confronted with multiple options, OCaml tries to
use locally available information to disambiguate between the various fields
and constructors. First, if the type of the record or variant is known,
OCaml can pick unambiguously the corresponding field or constructor.
For instance:</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> look_at_x_then_z (r:first_record) =
   <span class="ocamlkeyword">let</span> x = r.x <span class="ocamlkeyword">in</span>
   x + r.z;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> look_at_x_then_z : first_record -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> permute (x:first_variant) = <span class="ocamlkeyword">match</span> x <span class="ocamlkeyword">with</span>
   | A -&gt; (B:first_variant)
   | B -&gt; A
   | C -&gt; C;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> permute : first_variant -&gt; first_variant = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> wrapped = First <span class="ocamlkeyword">of</span> first_record
 <span class="ocamlkeyword">let</span> f (First r) = r, r.x;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> wrapped = First <span class="ocamlkeyword">of</span> first_record
<span class="ocamlkeyword">val</span> f : wrapped -&gt; first_record * int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>In the first example, <span class="c003">(r:first_record)</span> is an explicit annotation
telling OCaml that the type of <span class="c003">r</span> is <span class="c003">first_record</span>. With this
annotation, Ocaml knows that <span class="c003">r.x</span> refers to the <span class="c003">x</span> field of the first
record type. Similarly, the type annotation in the second example makes
it clear to OCaml that the constructors <span class="c003">A</span>, <span class="c003">B</span> and <span class="c003">C</span> come from the
first variant type. Contrarily, in the last example, OCaml has inferred
by itself that the type of <span class="c003">r</span> can only be <span class="c003">first_record</span> and there are
no needs for explicit type annotations.</p><p>Those explicit type annotations can in fact be used anywhere.
Most of the time they are unnecessary, but they are useful to guide
disambiguation, to debug unexpected type errors, or combined with some
of the more advanced features of OCaml described in later chapters.</p><p>Secondly, for records, OCaml can also deduce the right record type by
looking at the whole set of fields used in a expression or pattern:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> project_and_rotate {x;y; _ } = { x= - y; y = x ; z = 0} ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> project_and_rotate : first_record -&gt; first_record = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


Since the fields <span class="c003">x</span> and <span class="c003">y</span> can only appear simultaneously in the first
record type, OCaml infers that the type of <span class="c003">project_and_rotate</span> is
<span class="c003">first_record -&gt; first_record</span>.</p><p>In last resort, if there is not enough information to disambiguate between
different fields or constructors, Ocaml picks the last defined type
amongst all locally valid choices:</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> look_at_xz {x;z} = x;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> look_at_xz : middle_record -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>Here, OCaml has inferred that the possible choices for the type of
<span class="c003">{x;z}</span> are <span class="c003">first_record</span> and <span class="c003">middle_record</span>, since the type
<span class="c003">last_record</span> has no field <span class="c003">z</span>. Ocaml then picks the type <span class="c003">middle_record</span>
as the last defined type between the two possibilities.</p><p>Beware that this last resort disambiguation is local: once Ocaml has
chosen a disambiguation, it sticks to this choice, even if it leads to
an ulterior type error:</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> look_at_x_then_y r =
   <span class="ocamlkeyword">let</span> x = r.x <span class="ocamlkeyword">in</span> <span class="ocamlcomment">(* Ocaml deduces [r: last_record] *)</span>
   x + r.<span class="ocamlhighlight">y</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type last_record
       The field y does not belong to type last_record</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> is_a_or_b x = <span class="ocamlkeyword">match</span> x <span class="ocamlkeyword">with</span>
   | A -&gt; <span class="ocamlkeyword">true</span> <span class="ocamlcomment">(* OCaml infers [x: last_variant] *)</span>
   | <span class="ocamlhighlight">B</span> -&gt; <span class="ocamlkeyword">true</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This variant pattern is expected to have type last_variant
       The constructor B does not belong to type last_variant</div></div>

</div><p>Moreover, being the last defined type is a quite unstable position that
may change surreptitiously after adding or moving around a type
definition, or after opening a module (see chapter <a href="#c%3Amoduleexamples">2</a>).
Consequently, adding explicit type annotations to guide disambiguation is
more robust than relying on the last defined type disambiguation.</p>
<!--TOC section id="s:imperative-features" 1.5  Imperative features-->
<h2 class="section" id="s:imperative-features"><a class="section-anchor" href="#s:imperative-features" aria-hidden="true"></a>1.5  Imperative features</h2><!--SEC END --><p>Though all examples so far were written in purely applicative style,
OCaml is also equipped with full imperative features. This includes the
usual <span class="c003">while</span> and <span class="c003">for</span> loops, as well as mutable data structures such
as arrays. Arrays are either created by listing semicolon-separated element
values between <span class="c003">[|</span> and <span class="c003">|]</span> brackets, or allocated and initialized with the
<span class="c003">Array.make</span> function, then filled up later by assignments. For instance, the
function below sums two vectors (represented as float arrays) componentwise.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> add_vect v1 v2 =
   <span class="ocamlkeyword">let</span> len = min (Array.length v1) (Array.length v2) <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">let</span> res = Array.make len 0.0 <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">for</span> i = 0 <span class="ocamlkeyword">to</span> len - 1 <span class="ocamlkeyword">do</span>
     res.(i) &lt;- v1.(i) +. v2.(i)
   <span class="ocamlkeyword">done</span>;
   res;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> add_vect : float array -&gt; float array -&gt; float array = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> add_vect [| 1.0; 2.0 |] [| 3.0; 4.0 |];;</div>



<div class="pre caml-output ok">- : float array = [|4.; 6.|]</div></div>

</div><p>Record fields can also be modified by assignment, provided they are
declared <span class="c003">mutable</span> in the definition of the record type:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> mutable_point = { <span class="ocamlkeyword">mutable</span> x: float; <span class="ocamlkeyword">mutable</span> y: float };;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> mutable_point = { <span class="ocamlkeyword">mutable</span> x : float; <span class="ocamlkeyword">mutable</span> y : float; }</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> translate p dx dy =
   p.x &lt;- p.x +. dx; p.y &lt;- p.y +. dy;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> translate : mutable_point -&gt; float -&gt; float -&gt; unit = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> mypoint = { x = 0.0; y = 0.0 };;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> mypoint : mutable_point = {x = 0.; y = 0.}</div></div>
<div class="ocaml">



<div class="pre caml-input"> translate mypoint 1.0 2.0;;</div>



<div class="pre caml-output ok">- : unit = ()</div></div>
<div class="ocaml">



<div class="pre caml-input"> mypoint;;</div>



<div class="pre caml-output ok">- : mutable_point = {x = 1.; y = 2.}</div></div>

</div><p>OCaml has no built-in notion of variable – identifiers whose current
value can be changed by assignment. (The <span class="c003">let</span> binding is not an
assignment, it introduces a new identifier with a new scope.)
However, the standard library provides references, which are mutable
indirection cells, with operators <span class="c003">!</span> to fetch
the current contents of the reference and <span class="c003">:=</span> to assign the contents.
Variables can then be emulated by <span class="c003">let</span>-binding a reference. For
instance, here is an in-place insertion sort over arrays:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> insertion_sort a =
   <span class="ocamlkeyword">for</span> i = 1 <span class="ocamlkeyword">to</span> Array.length a - 1 <span class="ocamlkeyword">do</span>
     <span class="ocamlkeyword">let</span> val_i = a.(i) <span class="ocamlkeyword">in</span>
     <span class="ocamlkeyword">let</span> j = <span class="ocamlkeyword">ref</span> i <span class="ocamlkeyword">in</span>
     <span class="ocamlkeyword">while</span> !j &gt; 0 &amp;&amp; val_i &lt; a.(!j - 1) <span class="ocamlkeyword">do</span>
       a.(!j) &lt;- a.(!j - 1);
       j := !j - 1
     <span class="ocamlkeyword">done</span>;
     a.(!j) &lt;- val_i
   <span class="ocamlkeyword">done</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> insertion_sort : 'a array -&gt; unit = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>References are also useful to write functions that maintain a current
state between two calls to the function. For instance, the following
pseudo-random number generator keeps the last returned number in a
reference:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> current_rand = <span class="ocamlkeyword">ref</span> 0;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> current_rand : int <span class="ocamlkeyword">ref</span> = {contents = 0}</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> random () =
   current_rand := !current_rand * 25713 + 1345;
   !current_rand;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> random : unit -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>Again, there is nothing magical with references: they are implemented as
a single-field mutable record, as follows.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> 'a <span class="ocamlkeyword">ref</span> = { <span class="ocamlkeyword">mutable</span> contents: 'a };;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> 'a <span class="ocamlkeyword">ref</span> = { <span class="ocamlkeyword">mutable</span> contents : 'a; }</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> ( ! ) r = r.contents;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> ( ! ) : 'a <span class="ocamlkeyword">ref</span> -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> ( := ) r newval = r.contents &lt;- newval;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> ( := ) : 'a <span class="ocamlkeyword">ref</span> -&gt; 'a -&gt; unit = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>In some special cases, you may need to store a polymorphic function in
a data structure, keeping its polymorphism. Doing this requires
user-provided type annotations, since polymorphism is only introduced
automatically for global definitions. However, you can explicitly give
polymorphic types to record fields.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> idref = { <span class="ocamlkeyword">mutable</span> id: 'a. 'a -&gt; 'a };;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> idref = { <span class="ocamlkeyword">mutable</span> id : 'a. 'a -&gt; 'a; }</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> r = {id = <span class="ocamlkeyword">fun</span> x -&gt; x};;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> r : idref = {id = &lt;<span class="ocamlkeyword">fun</span>&gt;}</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> g s = (s.id 1, s.id <span class="ocamlkeyword">true</span>);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> g : idref -&gt; int * bool = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> r.id &lt;- (<span class="ocamlkeyword">fun</span> x -&gt; print_string <span class="ocamlstring">"called id\n"</span>; x);;</div>



<div class="pre caml-output ok">- : unit = ()</div></div>
<div class="ocaml">



<div class="pre caml-input"> g r;;</div>



<div class="pre caml-output ok">called id
called id
- : int * bool = (1, <span class="ocamlkeyword">true</span>)</div></div>

</div>
<!--TOC section id="s:exceptions" 1.6  Exceptions-->
<h2 class="section" id="s:exceptions"><a class="section-anchor" href="#s:exceptions" aria-hidden="true"></a>1.6  Exceptions</h2><!--SEC END --><p>OCaml provides exceptions for signalling and handling exceptional
conditions. Exceptions can also be used as a general-purpose non-local
control structure, although this should not be overused since it can
make the code harder to understand. Exceptions are declared with the
<span class="c003">exception</span> construct, and signalled with the <span class="c003">raise</span> operator. For instance,
the function below for taking the head of a list uses an exception to
signal the case where an empty list is given.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">exception</span> Empty_list;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">exception</span> Empty_list</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> head l =
   <span class="ocamlkeyword">match</span> l <span class="ocamlkeyword">with</span>
     [] -&gt; raise Empty_list
   | hd :: tl -&gt; hd;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> head : 'a list -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> head [1;2];;</div>



<div class="pre caml-output ok">- : int = 1</div></div>
<div class="ocaml">



<div class="pre caml-input"> head [];;</div>



<div class="pre caml-output ok">Exception: Empty_list.</div></div>

</div><p>Exceptions are used throughout the standard library to signal cases
where the library functions cannot complete normally. For instance,
the <span class="c003">List.assoc</span> function, which returns the data associated with a
given key in a list of (key, data) pairs, raises the predefined
exception <span class="c003">Not_found</span> when the key does not appear in the list:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> List.assoc 1 [(0, <span class="ocamlstring">"zero"</span>); (1, <span class="ocamlstring">"one"</span>)];;</div>



<div class="pre caml-output ok">- : string = <span class="ocamlstring">"one"</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> List.assoc 2 [(0, <span class="ocamlstring">"zero"</span>); (1, <span class="ocamlstring">"one"</span>)];;</div>



<div class="pre caml-output ok">Exception: Not_found.</div></div>

</div><p>Exceptions can be trapped with the <span class="c003">try</span>…<span class="c003">with</span> construct:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> name_of_binary_digit digit =
   <span class="ocamlkeyword">try</span>
     List.assoc digit [0, <span class="ocamlstring">"zero"</span>; 1, <span class="ocamlstring">"one"</span>]
   <span class="ocamlkeyword">with</span> Not_found -&gt;
     <span class="ocamlstring">"not a binary digit"</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> name_of_binary_digit : int -&gt; string = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> name_of_binary_digit 0;;</div>



<div class="pre caml-output ok">- : string = <span class="ocamlstring">"zero"</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> name_of_binary_digit (-1);;</div>



<div class="pre caml-output ok">- : string = <span class="ocamlstring">"not a binary digit"</span></div></div>

</div><p>The <span class="c003">with</span> part does pattern matching on the
exception value with the same syntax and behavior as <span class="c003">match</span>. Thus,
several exceptions can be caught by one
<span class="c003">try</span>…<span class="c003">with</span> construct:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> first_named_value values names =
   <span class="ocamlkeyword">try</span>
     List.assoc (head values) names
   <span class="ocamlkeyword">with</span>
   | Empty_list -&gt; <span class="ocamlstring">"no named value"</span>
   | Not_found -&gt; first_named_value (List.tl values) names;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> first_named_value : 'a list -&gt; ('a * string) list -&gt; string = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> first_named_value [ 0; 10 ] [ 1, <span class="ocamlstring">"one"</span>; 10, <span class="ocamlstring">"ten"</span>];;</div>



<div class="pre caml-output ok">- : string = <span class="ocamlstring">"ten"</span></div></div>

</div><p>Also, finalization can be performed by
trapping all exceptions, performing the finalization, then re-raising
the exception:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> temporarily_set_reference <span class="ocamlkeyword">ref</span> newval funct =
   <span class="ocamlkeyword">let</span> oldval = !<span class="ocamlkeyword">ref</span> <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">try</span>
     <span class="ocamlkeyword">ref</span> := newval;
     <span class="ocamlkeyword">let</span> res = funct () <span class="ocamlkeyword">in</span>
     <span class="ocamlkeyword">ref</span> := oldval;
     res
   <span class="ocamlkeyword">with</span> x -&gt;
     <span class="ocamlkeyword">ref</span> := oldval;
     raise x;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> temporarily_set_reference : 'a <span class="ocamlkeyword">ref</span> -&gt; 'a -&gt; (unit -&gt; 'b) -&gt; 'b = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>An alternative to <span class="c003">try</span>…<span class="c003">with</span> is to catch the exception while
pattern matching:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> assoc_may_map f x l =
   <span class="ocamlkeyword">match</span> List.assoc x l <span class="ocamlkeyword">with</span>
   | <span class="ocamlkeyword">exception</span> Not_found -&gt; None
   | y -&gt; f y;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> assoc_may_map : ('a -&gt; 'b option) -&gt; 'c -&gt; ('c * 'a) list -&gt; 'b option =
  &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


Note that this construction is only useful if the exception is raised
between <span class="c003">match</span>…<span class="c003">with</span>. Exception patterns can be combined
with ordinary patterns at the toplevel,


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> flat_assoc_opt x l =
   <span class="ocamlkeyword">match</span> List.assoc x l <span class="ocamlkeyword">with</span>
   | None | <span class="ocamlkeyword">exception</span> Not_found -&gt; None
   | Some _ <span class="ocamlkeyword">as</span> v -&gt; v;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> flat_assoc_opt : 'a -&gt; ('a * 'b option) list -&gt; 'b option = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


but they cannot be nested inside other patterns. For instance,
the pattern <span class="c003">Some (exception A)</span> is invalid.</p><p>When exceptions are used as a control structure, it can be useful to make
them as local as possible by using a locally defined exception.
For instance, with


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> fixpoint f x =
   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">exception</span> Done <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">let</span> x = <span class="ocamlkeyword">ref</span> x <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">try</span> <span class="ocamlkeyword">while</span> <span class="ocamlkeyword">true</span> <span class="ocamlkeyword">do</span>
       <span class="ocamlkeyword">let</span> y = f !x <span class="ocamlkeyword">in</span>
       <span class="ocamlkeyword">if</span> !x = y <span class="ocamlkeyword">then</span> raise Done <span class="ocamlkeyword">else</span> x := y
     <span class="ocamlkeyword">done</span>; <span class="ocamlkeyword">assert</span> <span class="ocamlkeyword">false</span>
   <span class="ocamlkeyword">with</span> Done -&gt; !x;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> fixpoint : ('a -&gt; 'a) -&gt; 'a -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


the function <span class="c003">f</span> cannot raise a <span class="c003">Done</span> exception, which removes an
entire class of misbehaving functions.</p>
<!--TOC section id="s:lazy-expr" 1.7  Lazy expressions-->
<h2 class="section" id="s:lazy-expr"><a class="section-anchor" href="#s:lazy-expr" aria-hidden="true"></a>1.7  Lazy expressions</h2><!--SEC END --><p>OCaml allows us to defer some computation until later when we need the result of
that computation. </p><p>We use <span class="c003">lazy (expr)</span> to delay the evaluation of some expression <span class="c003">expr</span>. For 
example, we can defer the computation of <span class="c003">1+1</span> until we need the result of that
expression, <span class="c003">2</span>. Let us see how we initialize a lazy expression. </p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> lazy_two = <span class="ocamlkeyword">lazy</span> ( print_endline <span class="ocamlstring">"lazy_two evaluation"</span>; 1 + 1 );;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> lazy_two : int lazy_t = &lt;<span class="ocamlkeyword">lazy</span>&gt;</div></div>

</div><p>We added <span class="c003">print_endline "lazy_two evaluation"</span> to see when the lazy
expression is being evaluated.</p><p>The value of <span class="c003">lazy_two</span> is displayed as <span class="c003">&lt;lazy&gt;</span>, which means the expression 
has not been evaluated yet, and its final value is unknown.</p><p>Note that <span class="c003">lazy_two</span> has type <span class="c003">int lazy_t</span>. However, the type <span class="c003">'a lazy_t</span> is an 
internal type name, so the type <span class="c003">'a Lazy.t</span> should be preferred when possible.</p><p>When we finally need the result of a lazy expression, we can call <span class="c003">Lazy.force</span> 
on that expression to force its evaluation. The function <span class="c003">force</span> comes from 
standard-library module <a href="libref/Lazy.html"><span class="c003">Lazy</span></a>.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   Lazy.force lazy_two;;</div>



<div class="pre caml-output ok">lazy_two evaluation
- : int = 2</div></div>

</div><p>Notice that our function call above prints “lazy_two evaluation” and then 
returns the plain value of the computation. </p><p>Now if we look at the value of <span class="c003">lazy_two</span>, we see that it is not displayed as 
<span class="c003">&lt;lazy&gt;</span> anymore but as <span class="c003">lazy 2</span>.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   lazy_two;;</div>



<div class="pre caml-output ok">- : int lazy_t = <span class="ocamlkeyword">lazy</span> 2</div></div>

</div><p>This is because <span class="c003">Lazy.force</span> memoizes the result of the forced expression. In other 
words, every subsequent call of <span class="c003">Lazy.force</span> on that expression returns the 
result of the first computation without recomputing the lazy expression. Let us 
force <span class="c003">lazy_two</span> once again. </p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   Lazy.force lazy_two;;</div>



<div class="pre caml-output ok">- : int = 2</div></div>

</div><p>The expression is not evaluated this time; notice that “lazy_two evaluation” is
not printed. The result of the initial computation is simply returned. </p><p>Lazy patterns provide another way to force a lazy expression. </p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> lazy_l = <span class="ocamlkeyword">lazy</span> ([1; 2] @ [3; 4]);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> lazy_l : int list lazy_t = &lt;<span class="ocamlkeyword">lazy</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">lazy</span> l = lazy_l;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> l : int list = [1; 2; 3; 4]</div></div>

</div><p>We can also use lazy patterns in pattern matching.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> maybe_eval lazy_guard lazy_expr =
     <span class="ocamlkeyword">match</span> lazy_guard, lazy_expr <span class="ocamlkeyword">with</span>
     | <span class="ocamlkeyword">lazy</span> <span class="ocamlkeyword">false</span>, _ -&gt; <span class="ocamlstring">"matches if (Lazy.force lazy_guard = false); lazy_expr not forced"</span>
     | <span class="ocamlkeyword">lazy</span> <span class="ocamlkeyword">true</span>, <span class="ocamlkeyword">lazy</span> _ -&gt; <span class="ocamlstring">"matches if (Lazy.force lazy_guard = true); lazy_expr forced"</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> maybe_eval : bool lazy_t -&gt; 'a lazy_t -&gt; string = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>The lazy expression <span class="c003">lazy_expr</span> is forced only if the <span class="c003">lazy_guard</span> value yields 
<span class="c003">true</span> once computed. Indeed, a simple wildcard pattern (not lazy) never forces 
the lazy expression’s evaluation. However, a pattern with keyword <span class="c003">lazy</span>, even 
if it is wildcard, always forces the evaluation of the deferred computation.</p>
<!--TOC section id="s:symb-expr" 1.8  Symbolic processing of expressions-->
<h2 class="section" id="s:symb-expr"><a class="section-anchor" href="#s:symb-expr" aria-hidden="true"></a>1.8  Symbolic processing of expressions</h2><!--SEC END --><p>We finish this introduction with a more complete example
representative of the use of OCaml for symbolic processing: formal
manipulations of arithmetic expressions containing variables. The
following variant type describes the expressions we shall manipulate:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> expression =
     Const <span class="ocamlkeyword">of</span> float
   | Var <span class="ocamlkeyword">of</span> string
   | Sum <span class="ocamlkeyword">of</span> expression * expression    <span class="ocamlcomment">(* e1 + e2 *)</span>
   | Diff <span class="ocamlkeyword">of</span> expression * expression   <span class="ocamlcomment">(* e1 - e2 *)</span>
   | Prod <span class="ocamlkeyword">of</span> expression * expression   <span class="ocamlcomment">(* e1 * e2 *)</span>
   | Quot <span class="ocamlkeyword">of</span> expression * expression   <span class="ocamlcomment">(* e1 / e2 *)</span>
 ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> expression =
    Const <span class="ocamlkeyword">of</span> float
  | Var <span class="ocamlkeyword">of</span> string
  | Sum <span class="ocamlkeyword">of</span> expression * expression
  | Diff <span class="ocamlkeyword">of</span> expression * expression
  | Prod <span class="ocamlkeyword">of</span> expression * expression
  | Quot <span class="ocamlkeyword">of</span> expression * expression</div></div>

</div><p>We first define a function to evaluate an expression given an
environment that maps variable names to their values. For simplicity,
the environment is represented as an association list.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">exception</span> Unbound_variable <span class="ocamlkeyword">of</span> string;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">exception</span> Unbound_variable <span class="ocamlkeyword">of</span> string</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> eval env exp =
   <span class="ocamlkeyword">match</span> exp <span class="ocamlkeyword">with</span>
     Const c -&gt; c
   | Var v -&gt;
       (<span class="ocamlkeyword">try</span> List.assoc v env <span class="ocamlkeyword">with</span> Not_found -&gt; raise (Unbound_variable v))
   | Sum(f, g) -&gt; eval env f +. eval env g
   | Diff(f, g) -&gt; eval env f -. eval env g
   | Prod(f, g) -&gt; eval env f *. eval env g
   | Quot(f, g) -&gt; eval env f /. eval env g;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> eval : (string * float) list -&gt; expression -&gt; float = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> eval [(<span class="ocamlstring">"x"</span>, 1.0); (<span class="ocamlstring">"y"</span>, 3.14)] (Prod(Sum(Var <span class="ocamlstring">"x"</span>, Const 2.0), Var <span class="ocamlstring">"y"</span>));;</div>



<div class="pre caml-output ok">- : float = 9.42</div></div>

</div><p>Now for a real symbolic processing, we define the derivative of an
expression with respect to a variable <span class="c003">dv</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> deriv exp dv =
   <span class="ocamlkeyword">match</span> exp <span class="ocamlkeyword">with</span>
     Const c -&gt; Const 0.0
   | Var v -&gt; <span class="ocamlkeyword">if</span> v = dv <span class="ocamlkeyword">then</span> Const 1.0 <span class="ocamlkeyword">else</span> Const 0.0
   | Sum(f, g) -&gt; Sum(deriv f dv, deriv g dv)
   | Diff(f, g) -&gt; Diff(deriv f dv, deriv g dv)
   | Prod(f, g) -&gt; Sum(Prod(f, deriv g dv), Prod(deriv f dv, g))
   | Quot(f, g) -&gt; Quot(Diff(Prod(deriv f dv, g), Prod(f, deriv g dv)),
                        Prod(g, g))
 ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> deriv : expression -&gt; string -&gt; expression = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> deriv (Quot(Const 1.0, Var <span class="ocamlstring">"x"</span>)) <span class="ocamlstring">"x"</span>;;</div>



<div class="pre caml-output ok">- : expression =
Quot (Diff (Prod (Const 0., Var <span class="ocamlstring">"x"</span>), Prod (Const 1., Const 1.)),
 Prod (Var <span class="ocamlstring">"x"</span>, Var <span class="ocamlstring">"x"</span>))</div></div>

</div>
<!--TOC section id="s:pretty-printing" 1.9  Pretty-printing-->
<h2 class="section" id="s:pretty-printing"><a class="section-anchor" href="#s:pretty-printing" aria-hidden="true"></a>1.9  Pretty-printing</h2><!--SEC END --><p>As shown in the examples above, the internal representation (also
called <em>abstract syntax</em>) of expressions quickly becomes hard to
read and write as the expressions get larger. We need a printer and a
parser to go back and forth between the abstract syntax and the <em>concrete syntax</em>, which in the case of expressions is the familiar
algebraic notation (e.g. <span class="c003">2*x+1</span>).</p><p>For the printing function, we take into account the usual precedence
rules (i.e. <span class="c003">*</span> binds tighter than <span class="c003">+</span>) to avoid printing unnecessary
parentheses. To this end, we maintain the current operator precedence
and print parentheses around an operator only if its precedence is
less than the current precedence.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> print_expr exp =
   <span class="ocamlcomment">(* Local function definitions *)</span>
   <span class="ocamlkeyword">let</span> open_paren prec op_prec =
     <span class="ocamlkeyword">if</span> prec &gt; op_prec <span class="ocamlkeyword">then</span> print_string <span class="ocamlstring">"("</span> <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">let</span> close_paren prec op_prec =
     <span class="ocamlkeyword">if</span> prec &gt; op_prec <span class="ocamlkeyword">then</span> print_string <span class="ocamlstring">")"</span> <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> print prec exp =     <span class="ocamlcomment">(* prec is the current precedence *)</span>
     <span class="ocamlkeyword">match</span> exp <span class="ocamlkeyword">with</span>
       Const c -&gt; print_float c
     | Var v -&gt; print_string v
     | Sum(f, g) -&gt;
         open_paren prec 0;
         print 0 f; print_string <span class="ocamlstring">" + "</span>; print 0 g;
         close_paren prec 0
     | Diff(f, g) -&gt;
         open_paren prec 0;
         print 0 f; print_string <span class="ocamlstring">" - "</span>; print 1 g;
         close_paren prec 0
     | Prod(f, g) -&gt;
         open_paren prec 2;
         print 2 f; print_string <span class="ocamlstring">" * "</span>; print 2 g;
         close_paren prec 2
     | Quot(f, g) -&gt;
         open_paren prec 2;
         print 2 f; print_string <span class="ocamlstring">" / "</span>; print 3 g;
         close_paren prec 2
   <span class="ocamlkeyword">in</span> print 0 exp;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> print_expr : expression -&gt; unit = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> e = Sum(Prod(Const 2.0, Var <span class="ocamlstring">"x"</span>), Const 1.0);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> e : expression = Sum (Prod (Const 2., Var <span class="ocamlstring">"x"</span>), Const 1.)</div></div>
<div class="ocaml">



<div class="pre caml-input"> print_expr e; print_newline ();;</div>



<div class="pre caml-output ok">2. * x + 1.
- : unit = ()</div></div>
<div class="ocaml">



<div class="pre caml-input"> print_expr (deriv e <span class="ocamlstring">"x"</span>); print_newline ();;</div>



<div class="pre caml-output ok">2. * 1. + 0. * x + 0.
- : unit = ()</div></div>

</div>
<!--TOC section id="s:printf" 1.10  Printf formats-->
<h2 class="section" id="s:printf"><a class="section-anchor" href="#s:printf" aria-hidden="true"></a>1.10  Printf formats</h2><!--SEC END --><p>There is a <span class="c003">printf</span> function in the <a href="libref/Printf.html"><span class="c003">Printf</span></a> module
(see chapter <a href="#c%3Amoduleexamples">2</a>) that allows you to make formatted
output more concisely.
It follows the behavior of the <span class="c003">printf</span> function from the C standard library.
The <span class="c003">printf</span> function takes a format string that describes the desired output
as a text interspered with specifiers (for instance <span class="c003">%d</span>, <span class="c003">%f</span>).
Next, the specifiers are substituted by the following arguments in their order
of apparition in the format string:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> Printf.printf <span class="ocamlstring">"%i + %i is an integer value, %F * %F is a float, %S\n"</span>
 3 2 4.5 1. <span class="ocamlstring">"this is a string"</span>;;</div>



<div class="pre caml-output ok">3 + 2 is an integer value, 4.5 * 1. is a float, <span class="ocamlstring">"this is a string"</span>
- : unit = ()</div></div>

</div><p>


The OCaml type system checks that the type of the arguments and the specifiers are
compatible. If you pass it an argument of a type that does not correspond to
the format specifier, the compiler will display an error message:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> Printf.printf <span class="ocamlstring">"Float value: %F"</span> <span class="ocamlhighlight">42</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type int but an expression was expected of type
         float
  Hint: Did you mean `42.'?</div></div>

</div><p>


The <span class="c003">fprintf</span> function is like <span class="c003">printf</span> except that it takes an output channel as
the first argument. The <span class="c003">%a</span> specifier can be useful to define custom printer
(for custom types). For instance, we can create a printing template that converts
an integer argument to signed decimal:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> pp_int ppf n = Printf.fprintf ppf <span class="ocamlstring">"%d"</span> n;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> pp_int : out_channel -&gt; int -&gt; unit = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> Printf.printf <span class="ocamlstring">"Outputting an integer using a custom printer: %a "</span> pp_int 42;;</div>



<div class="pre caml-output ok">Outputting an integer using a custom printer: 42 - : unit = ()</div></div>

</div><p>


The advantage of those printers based on the <span class="c003">%a</span> specifier is that they can be
composed together to create more complex printers step by step.
We can define a combinator that can turn a printer for <span class="c003">'a</span> type into a printer
for <span class="c003">'a optional</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> pp_option printer ppf = <span class="ocamlkeyword">function</span>
   | None -&gt; Printf.fprintf ppf <span class="ocamlstring">"None"</span>
   | Some v -&gt; Printf.fprintf ppf <span class="ocamlstring">"Some(%a)"</span> printer v;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> pp_option :
  (out_channel -&gt; 'a -&gt; unit) -&gt; out_channel -&gt; 'a option -&gt; unit = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> Printf.fprintf stdout
   <span class="ocamlstring">"The current setting is %a. \nThere is only %a\n"</span>
   (pp_option pp_int) (Some 3)
   (pp_option pp_int) None
 ;;</div>



<div class="pre caml-output ok">The current setting is Some(3).
There is only None
- : unit = ()</div></div>

</div><p>


If the value of its argument its <span class="c003">None</span>, the printer returned by pp_option
printer prints <span class="c003">None</span> otherwise it uses the provided printer to print <span class="c003">Some </span>.</p><p>Here is how to rewrite the pretty-printer using <span class="c003">fprintf</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> pp_expr ppf expr =
   <span class="ocamlkeyword">let</span> open_paren prec op_prec output =
     <span class="ocamlkeyword">if</span> prec &gt; op_prec <span class="ocamlkeyword">then</span> Printf.fprintf output <span class="ocamlstring">"%s"</span> <span class="ocamlstring">"("</span> <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">let</span> close_paren prec op_prec output =
     <span class="ocamlkeyword">if</span> prec &gt; op_prec <span class="ocamlkeyword">then</span> Printf.fprintf output <span class="ocamlstring">"%s"</span> <span class="ocamlstring">")"</span> <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> print prec ppf expr =
       <span class="ocamlkeyword">match</span> expr <span class="ocamlkeyword">with</span>
       | Const c -&gt; Printf.fprintf ppf <span class="ocamlstring">"%F"</span> c
       | Var v -&gt; Printf.fprintf ppf <span class="ocamlstring">"%s"</span> v
       | Sum(f, g) -&gt;
           open_paren prec 0 ppf;
           Printf.fprintf ppf <span class="ocamlstring">"%a + %a"</span> (print 0) f (print 0) g;
           close_paren prec 0 ppf
       | Diff(f, g) -&gt;
           open_paren prec 0 ppf;
           Printf.fprintf ppf <span class="ocamlstring">"%a - %a"</span> (print 0) f (print 1) g;
           close_paren prec 0 ppf
       | Prod(f, g) -&gt;
           open_paren prec 2 ppf;
           Printf.fprintf ppf <span class="ocamlstring">"%a * %a"</span> (print 2) f (print 2) g;
           close_paren prec 2 ppf
       | Quot(f, g) -&gt;
           open_paren prec 2 ppf;
           Printf.fprintf ppf <span class="ocamlstring">"%a / %a"</span> (print 2) f (print 3) g;
           close_paren prec 2 ppf
   <span class="ocamlkeyword">in</span> print 0 ppf expr;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> pp_expr : out_channel -&gt; expression -&gt; unit = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> pp_expr stdout e; print_newline ();;</div>



<div class="pre caml-output ok">2. * x + 1.
- : unit = ()</div></div>
<div class="ocaml">



<div class="pre caml-input"> pp_expr stdout (deriv e <span class="ocamlstring">"x"</span>); print_newline ();;</div>



<div class="pre caml-output ok">2. * 1. + 0. * x + 0.
- : unit = ()</div></div>

</div><p>Due to the way that format string are build, storing a format string requires
an explicit type annotation:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> str : _ format =
     <span class="ocamlstring">"%i is an integer value, %F is a float, %S\n"</span>;;</div></div>

</div><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> Printf.printf str 3 4.5 <span class="ocamlstring">"string value"</span>;;</div>



<div class="pre caml-output ok">3 is an integer value, 4.5 is a float, <span class="ocamlstring">"string value"</span>
- : unit = ()</div></div>

</div>
<!--TOC section id="s:standalone-programs" 1.11  Standalone OCaml programs-->
<h2 class="section" id="s:standalone-programs"><a class="section-anchor" href="#s:standalone-programs" aria-hidden="true"></a>1.11  Standalone OCaml programs</h2><!--SEC END --><p>All examples given so far were executed under the interactive system.
OCaml code can also be compiled separately and executed
non-interactively using the batch compilers <span class="c003">ocamlc</span> and <span class="c003">ocamlopt</span>.
The source code must be put in a file with extension <span class="c003">.ml</span>. It
consists of a sequence of phrases, which will be evaluated at runtime
in their order of appearance in the source file. Unlike in interactive
mode, types and values are not printed automatically; the program must
call printing functions explicitly to produce some output. The <span class="c003">;;</span> used
in the interactive examples is not required in
source files created for use with OCaml compilers, but can be helpful
to mark the end of a top-level expression unambiguously even when
there are syntax errors.
Here is a
sample standalone program to print the greatest common divisor
(gcd) of two numbers:
</p><pre>(* File gcd.ml *)
let rec gcd a b =
  if b = 0 then a
  else gcd b (a mod b);;

let main () =
  let a = int_of_string Sys.argv.(1) in
  let b = int_of_string Sys.argv.(2) in
  Printf.printf "%d\n" (gcd a b);
  exit 0;;
main ();;
</pre><p><span class="c003">Sys.argv</span> is an array of strings containing the command-line
parameters. <span class="c003">Sys.argv.(1)</span> is thus the first command-line parameter.
The program above is compiled and executed with the following shell
commands:
</p><pre>$ ocamlc -o gcd gcd.ml
$ ./gcd 6 9
3
$ ./fib 7 11
1
</pre><p>
More complex standalone OCaml programs are typically composed of
multiple source files, and can link with precompiled libraries.
Chapters <a href="#c%3Acamlc">9</a> and <a href="#c%3Anativecomp">12</a> explain how to use the
batch compilers <span class="c003">ocamlc</span> and <span class="c003">ocamlopt</span>. Recompilation of
multi-file OCaml projects can be automated using third-party
build systems, such as the
<a href="https://github.com/ocaml/ocamlbuild/">ocamlbuild</a>
compilation manager.

</p>
<!--TOC chapter id="sec20" Chapter 2  The module system-->
<h1 class="chapter" id="sec20">Chapter 2  The module system</h1><!--SEC END --><p> <a id="c:moduleexamples"></a>
</p><!--NAME moduleexamples.html-->
<p>This chapter introduces the module system of OCaml.</p>
<!--TOC section id="s:module:structures" 2.1  Structures-->
<h2 class="section" id="s:module:structures"><a class="section-anchor" href="#s:module:structures" aria-hidden="true"></a>2.1  Structures</h2><!--SEC END --><p>A primary motivation for modules is to package together related
definitions (such as the definitions of a data type and associated
operations over that type) and enforce a consistent naming scheme for
these definitions. This avoids running out of names or accidentally
confusing names. Such a package is called a <em>structure</em> and
is introduced by the <span class="c003">struct</span>…<span class="c003">end</span> construct, which contains an
arbitrary sequence of definitions. The structure is usually given a
name with the <span class="c003">module</span> binding. Here is for instance a structure
packaging together a type of priority queues and their operations:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> PrioQueue =
   <span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">type</span> priority = int
     <span class="ocamlkeyword">type</span> 'a queue = Empty | Node <span class="ocamlkeyword">of</span> priority * 'a * 'a queue * 'a queue
     <span class="ocamlkeyword">let</span> empty = Empty
     <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> insert queue prio elt =
       <span class="ocamlkeyword">match</span> queue <span class="ocamlkeyword">with</span>
         Empty -&gt; Node(prio, elt, Empty, Empty)
       | Node(p, e, left, right) -&gt;
           <span class="ocamlkeyword">if</span> prio &lt;= p
           <span class="ocamlkeyword">then</span> Node(prio, elt, insert right p e, left)
           <span class="ocamlkeyword">else</span> Node(p, e, insert right prio elt, left)
     <span class="ocamlkeyword">exception</span> Queue_is_empty
     <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> remove_top = <span class="ocamlkeyword">function</span>
         Empty -&gt; raise Queue_is_empty
       | Node(prio, elt, left, Empty) -&gt; left
       | Node(prio, elt, Empty, right) -&gt; right
       | Node(prio, elt, (Node(lprio, lelt, _, _) <span class="ocamlkeyword">as</span> left),
                         (Node(rprio, relt, _, _) <span class="ocamlkeyword">as</span> right)) -&gt;
           <span class="ocamlkeyword">if</span> lprio &lt;= rprio
           <span class="ocamlkeyword">then</span> Node(lprio, lelt, remove_top left, right)
           <span class="ocamlkeyword">else</span> Node(rprio, relt, left, remove_top right)
     <span class="ocamlkeyword">let</span> extract = <span class="ocamlkeyword">function</span>
         Empty -&gt; raise Queue_is_empty
       | Node(prio, elt, _, _) <span class="ocamlkeyword">as</span> queue -&gt; (prio, elt, remove_top queue)
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> PrioQueue :
  <span class="ocamlkeyword">sig</span>
    <span class="ocamlkeyword">type</span> priority = int
    <span class="ocamlkeyword">type</span> 'a queue = Empty | Node <span class="ocamlkeyword">of</span> priority * 'a * 'a queue * 'a queue
    <span class="ocamlkeyword">val</span> empty : 'a queue
    <span class="ocamlkeyword">val</span> insert : 'a queue -&gt; priority -&gt; 'a -&gt; 'a queue
    <span class="ocamlkeyword">exception</span> Queue_is_empty
    <span class="ocamlkeyword">val</span> remove_top : 'a queue -&gt; 'a queue
    <span class="ocamlkeyword">val</span> extract : 'a queue -&gt; priority * 'a * 'a queue
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


Outside the structure, its components can be referred to using the
“dot notation”, that is, identifiers qualified by a structure name.
For instance, <span class="c003">PrioQueue.insert</span> is the function <span class="c003">insert</span> defined
inside the structure <span class="c003">PrioQueue</span> and <span class="c003">PrioQueue.queue</span> is the type
<span class="c003">queue</span> defined in <span class="c003">PrioQueue</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> PrioQueue.insert PrioQueue.empty 1 <span class="ocamlstring">"hello"</span>;;</div>



<div class="pre caml-output ok">- : string PrioQueue.queue =
PrioQueue.Node (1, <span class="ocamlstring">"hello"</span>, PrioQueue.Empty, PrioQueue.Empty)</div></div>

</div><p>Another possibility is to open the module, which brings all
identifiers defined inside the module in the scope of the current
structure.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">open</span> PrioQueue;;</div></div>
<div class="ocaml">



<div class="pre caml-input">   insert empty 1 <span class="ocamlstring">"hello"</span>;;</div>



<div class="pre caml-output ok">- : string PrioQueue.queue = Node (1, <span class="ocamlstring">"hello"</span>, Empty, Empty)</div></div>

</div><p>Opening a module enables lighter access to its components, at the
cost of making it harder to identify in which module a identifier
has been defined. In particular, opened modules can shadow
identifiers present in the current scope, potentially leading
to confusing errors:</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> empty = []
   <span class="ocamlkeyword">open</span> PrioQueue;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> empty : 'a list = []</div></div>
<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> x = 1 :: <span class="ocamlhighlight">empty</span> ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type 'a PrioQueue.queue
       but an expression was expected of type int list</div></div>

</div><p>A partial solution to this conundrum is to open modules locally,
making the components of the module available only in the
concerned expression. This can also make the code easier to read
– the open statement is closer to where it is used– and to refactor
– the code fragment is more self-contained.
Two constructions are available for this purpose:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">open</span> PrioQueue <span class="ocamlkeyword">in</span>
   insert empty 1 <span class="ocamlstring">"hello"</span>;;</div>



<div class="pre caml-output ok">- : string PrioQueue.queue = Node (1, <span class="ocamlstring">"hello"</span>, Empty, Empty)</div></div>

</div><p>


and


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   PrioQueue.(insert empty 1 <span class="ocamlstring">"hello"</span>);;</div>



<div class="pre caml-output ok">- : string PrioQueue.queue = Node (1, <span class="ocamlstring">"hello"</span>, Empty, Empty)</div></div>

</div><p>


In the second form, when the body of a local open is itself delimited
by parentheses, braces or bracket, the parentheses of the local open
can be omitted. For instance,


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   PrioQueue.[empty] = PrioQueue.([empty]);;</div>



<div class="pre caml-output ok">- : bool = <span class="ocamlkeyword">true</span></div></div>
<div class="ocaml">



<div class="pre caml-input">   PrioQueue.[|empty|] = PrioQueue.([|empty|]);;</div>



<div class="pre caml-output ok">- : bool = <span class="ocamlkeyword">true</span></div></div>
<div class="ocaml">



<div class="pre caml-input">    PrioQueue.{ contents = empty } = PrioQueue.({ contents = empty });;</div>



<div class="pre caml-output ok">- : bool = <span class="ocamlkeyword">true</span></div></div>

</div><p>


becomes


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   PrioQueue.[insert empty 1 <span class="ocamlstring">"hello"</span>];;</div>



<div class="pre caml-output ok">- : string PrioQueue.queue list = [Node (1, <span class="ocamlstring">"hello"</span>, Empty, Empty)]</div></div>

</div><p>


This second form also works for patterns:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> at_most_one_element x = <span class="ocamlkeyword">match</span> x <span class="ocamlkeyword">with</span>
   | PrioQueue.( Empty| Node (_,_, Empty,Empty) ) -&gt; <span class="ocamlkeyword">true</span>
   | _ -&gt; <span class="ocamlkeyword">false</span> ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> at_most_one_element : 'a PrioQueue.queue -&gt; bool = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>It is also possible to copy the components of a module inside
another module by using an <span class="c003">include</span> statement. This can be
particularly useful to extend existing modules. As an illustration,
we could add functions that returns an optional value rather than
an exception when the priority queue is empty.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">module</span> PrioQueueOpt =
   <span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">include</span> PrioQueue

     <span class="ocamlkeyword">let</span> remove_top_opt x =
       <span class="ocamlkeyword">try</span> Some(remove_top x) <span class="ocamlkeyword">with</span> Queue_is_empty -&gt; None

     <span class="ocamlkeyword">let</span> extract_opt x =
       <span class="ocamlkeyword">try</span> Some(extract x) <span class="ocamlkeyword">with</span> Queue_is_empty -&gt; None
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> PrioQueueOpt :
  <span class="ocamlkeyword">sig</span>
    <span class="ocamlkeyword">type</span> priority = int
    <span class="ocamlkeyword">type</span> 'a queue =
      'a PrioQueue.queue =
        Empty
      | Node <span class="ocamlkeyword">of</span> priority * 'a * 'a queue * 'a queue
    <span class="ocamlkeyword">val</span> empty : 'a queue
    <span class="ocamlkeyword">val</span> insert : 'a queue -&gt; priority -&gt; 'a -&gt; 'a queue
    <span class="ocamlkeyword">exception</span> Queue_is_empty
    <span class="ocamlkeyword">val</span> remove_top : 'a queue -&gt; 'a queue
    <span class="ocamlkeyword">val</span> extract : 'a queue -&gt; priority * 'a * 'a queue
    <span class="ocamlkeyword">val</span> remove_top_opt : 'a queue -&gt; 'a queue option
    <span class="ocamlkeyword">val</span> extract_opt : 'a queue -&gt; (priority * 'a * 'a queue) option
  <span class="ocamlkeyword">end</span></div></div>

</div>
<!--TOC section id="s:signature" 2.2  Signatures-->
<h2 class="section" id="s:signature"><a class="section-anchor" href="#s:signature" aria-hidden="true"></a>2.2  Signatures</h2><!--SEC END --><p>Signatures are interfaces for structures. A signature specifies
which components of a structure are accessible from the outside, and
with which type. It can be used to hide some components of a structure
(e.g. local function definitions) or export some components with a
restricted type. For instance, the signature below specifies the three
priority queue operations <span class="c003">empty</span>, <span class="c003">insert</span> and <span class="c003">extract</span>, but not the
auxiliary function <span class="c003">remove_top</span>. Similarly, it makes the <span class="c003">queue</span> type
abstract (by not providing its actual representation as a concrete type).


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> PRIOQUEUE =
   <span class="ocamlkeyword">sig</span>
     <span class="ocamlkeyword">type</span> priority = int         <span class="ocamlcomment">(* still concrete *)</span>
     <span class="ocamlkeyword">type</span> 'a queue               <span class="ocamlcomment">(* now abstract *)</span>
     <span class="ocamlkeyword">val</span> empty : 'a queue
     <span class="ocamlkeyword">val</span> insert : 'a queue -&gt; int -&gt; 'a -&gt; 'a queue
     <span class="ocamlkeyword">val</span> extract : 'a queue -&gt; int * 'a * 'a queue
     <span class="ocamlkeyword">exception</span> Queue_is_empty
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> PRIOQUEUE =
  <span class="ocamlkeyword">sig</span>
    <span class="ocamlkeyword">type</span> priority = int
    <span class="ocamlkeyword">type</span> 'a queue
    <span class="ocamlkeyword">val</span> empty : 'a queue
    <span class="ocamlkeyword">val</span> insert : 'a queue -&gt; int -&gt; 'a -&gt; 'a queue
    <span class="ocamlkeyword">val</span> extract : 'a queue -&gt; int * 'a * 'a queue
    <span class="ocamlkeyword">exception</span> Queue_is_empty
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


Restricting the <span class="c003">PrioQueue</span> structure by this signature results in
another view of the <span class="c003">PrioQueue</span> structure where the <span class="c003">remove_top</span>
function is not accessible and the actual representation of priority
queues is hidden:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> AbstractPrioQueue = (PrioQueue : PRIOQUEUE);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> AbstractPrioQueue : PRIOQUEUE</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlhighlight">AbstractPrioQueue.remove_top</span> ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: Unbound value AbstractPrioQueue.remove_top</div></div>
<div class="ocaml">



<div class="pre caml-input"> AbstractPrioQueue.insert AbstractPrioQueue.empty 1 <span class="ocamlstring">"hello"</span>;;</div>



<div class="pre caml-output ok">- : string AbstractPrioQueue.queue = &lt;abstr&gt;</div></div>

</div><p>


The restriction can also be performed during the definition of the
structure, as in
</p><pre>module PrioQueue = (struct ... end : PRIOQUEUE);;
</pre><p>An alternate syntax is provided for the above:
</p><pre>module PrioQueue : PRIOQUEUE = struct ... end;;
</pre><p>
Like for modules, it is possible to include a signature to copy
its components inside the current signature. For instance, we
can extend the PRIOQUEUE signature with the <span class="c003">extract_opt</span>
function:</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> PRIOQUEUE_WITH_OPT =
   <span class="ocamlkeyword">sig</span>
     <span class="ocamlkeyword">include</span> PRIOQUEUE
     <span class="ocamlkeyword">val</span> extract_opt : 'a queue -&gt; (int * 'a * 'a queue) option
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> PRIOQUEUE_WITH_OPT =
  <span class="ocamlkeyword">sig</span>
    <span class="ocamlkeyword">type</span> priority = int
    <span class="ocamlkeyword">type</span> 'a queue
    <span class="ocamlkeyword">val</span> empty : 'a queue
    <span class="ocamlkeyword">val</span> insert : 'a queue -&gt; int -&gt; 'a -&gt; 'a queue
    <span class="ocamlkeyword">val</span> extract : 'a queue -&gt; int * 'a * 'a queue
    <span class="ocamlkeyword">exception</span> Queue_is_empty
    <span class="ocamlkeyword">val</span> extract_opt : 'a queue -&gt; (int * 'a * 'a queue) option
  <span class="ocamlkeyword">end</span></div></div>

</div>
<!--TOC section id="s:functors" 2.3  Functors-->
<h2 class="section" id="s:functors"><a class="section-anchor" href="#s:functors" aria-hidden="true"></a>2.3  Functors</h2><!--SEC END --><p>Functors are “functions” from modules to modules. Functors let you create
parameterized modules and then provide other modules as parameter(s) to get
a specific implementation. For instance, a <span class="c003">Set</span> module implementing sets
as sorted lists could be parameterized to work with any module that provides
an element type and a comparison function <span class="c003">compare</span> (such as <span class="c003">OrderedString</span>):</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> comparison = Less | Equal | Greater;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> comparison = Less | Equal | Greater</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> ORDERED_TYPE =
   <span class="ocamlkeyword">sig</span>
     <span class="ocamlkeyword">type</span> t
     <span class="ocamlkeyword">val</span> compare: t -&gt; t -&gt; comparison
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> ORDERED_TYPE = <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> t <span class="ocamlkeyword">val</span> compare : t -&gt; t -&gt; comparison <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Set =
   <span class="ocamlkeyword">functor</span> (Elt: ORDERED_TYPE) -&gt;
     <span class="ocamlkeyword">struct</span>
       <span class="ocamlkeyword">type</span> element = Elt.t
       <span class="ocamlkeyword">type</span> set = element list
       <span class="ocamlkeyword">let</span> empty = []
       <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> add x s =
         <span class="ocamlkeyword">match</span> s <span class="ocamlkeyword">with</span>
           [] -&gt; [x]
         | hd::tl -&gt;
            <span class="ocamlkeyword">match</span> Elt.compare x hd <span class="ocamlkeyword">with</span>
              Equal   -&gt; s         <span class="ocamlcomment">(* x is already in s *)</span>
            | Less    -&gt; x :: s    <span class="ocamlcomment">(* x is smaller than all elements of s *)</span>
            | Greater -&gt; hd :: add x tl
       <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> member x s =
         <span class="ocamlkeyword">match</span> s <span class="ocamlkeyword">with</span>
           [] -&gt; <span class="ocamlkeyword">false</span>
         | hd::tl -&gt;
             <span class="ocamlkeyword">match</span> Elt.compare x hd <span class="ocamlkeyword">with</span>
               Equal   -&gt; <span class="ocamlkeyword">true</span>     <span class="ocamlcomment">(* x belongs to s *)</span>
             | Less    -&gt; <span class="ocamlkeyword">false</span>    <span class="ocamlcomment">(* x is smaller than all elements of s *)</span>
             | Greater -&gt; member x tl
     <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> Set :
  <span class="ocamlkeyword">functor</span> (Elt : ORDERED_TYPE) -&gt;
    <span class="ocamlkeyword">sig</span>
      <span class="ocamlkeyword">type</span> element = Elt.t
      <span class="ocamlkeyword">type</span> set = element list
      <span class="ocamlkeyword">val</span> empty : 'a list
      <span class="ocamlkeyword">val</span> add : Elt.t -&gt; Elt.t list -&gt; Elt.t list
      <span class="ocamlkeyword">val</span> member : Elt.t -&gt; Elt.t list -&gt; bool
    <span class="ocamlkeyword">end</span></div></div>

</div><p>


By applying the <span class="c003">Set</span> functor to a structure implementing an ordered
type, we obtain set operations for this type:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> OrderedString =
   <span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">type</span> t = string
     <span class="ocamlkeyword">let</span> compare x y = <span class="ocamlkeyword">if</span> x = y <span class="ocamlkeyword">then</span> Equal <span class="ocamlkeyword">else</span> <span class="ocamlkeyword">if</span> x &lt; y <span class="ocamlkeyword">then</span> Less <span class="ocamlkeyword">else</span> Greater
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> OrderedString :
  <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> t = string <span class="ocamlkeyword">val</span> compare : 'a -&gt; 'a -&gt; comparison <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> StringSet = Set(OrderedString);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> StringSet :
  <span class="ocamlkeyword">sig</span>
    <span class="ocamlkeyword">type</span> element = OrderedString.t
    <span class="ocamlkeyword">type</span> set = element list
    <span class="ocamlkeyword">val</span> empty : 'a list
    <span class="ocamlkeyword">val</span> add : OrderedString.t -&gt; OrderedString.t list -&gt; OrderedString.t list
    <span class="ocamlkeyword">val</span> member : OrderedString.t -&gt; OrderedString.t list -&gt; bool
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> StringSet.member <span class="ocamlstring">"bar"</span> (StringSet.add <span class="ocamlstring">"foo"</span> StringSet.empty);;</div>



<div class="pre caml-output ok">- : bool = <span class="ocamlkeyword">false</span></div></div>

</div>
<!--TOC section id="s:functors-and-abstraction" 2.4  Functors and type abstraction-->
<h2 class="section" id="s:functors-and-abstraction"><a class="section-anchor" href="#s:functors-and-abstraction" aria-hidden="true"></a>2.4  Functors and type abstraction</h2><!--SEC END --><p>As in the <span class="c003">PrioQueue</span> example, it would be good style to hide the
actual implementation of the type <span class="c003">set</span>, so that users of the
structure will not rely on sets being lists, and we can switch later
to another, more efficient representation of sets without breaking
their code. This can be achieved by restricting <span class="c003">Set</span> by a suitable
functor signature:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> SETFUNCTOR =
   <span class="ocamlkeyword">functor</span> (Elt: ORDERED_TYPE) -&gt;
     <span class="ocamlkeyword">sig</span>
       <span class="ocamlkeyword">type</span> element = Elt.t      <span class="ocamlcomment">(* concrete *)</span>
       <span class="ocamlkeyword">type</span> set                  <span class="ocamlcomment">(* abstract *)</span>
       <span class="ocamlkeyword">val</span> empty : set
       <span class="ocamlkeyword">val</span> add : element -&gt; set -&gt; set
       <span class="ocamlkeyword">val</span> member : element -&gt; set -&gt; bool
     <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> SETFUNCTOR =
  <span class="ocamlkeyword">functor</span> (Elt : ORDERED_TYPE) -&gt;
    <span class="ocamlkeyword">sig</span>
      <span class="ocamlkeyword">type</span> element = Elt.t
      <span class="ocamlkeyword">type</span> set
      <span class="ocamlkeyword">val</span> empty : set
      <span class="ocamlkeyword">val</span> add : element -&gt; set -&gt; set
      <span class="ocamlkeyword">val</span> member : element -&gt; set -&gt; bool
    <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> AbstractSet = (Set : SETFUNCTOR);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> AbstractSet : SETFUNCTOR</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> AbstractStringSet = AbstractSet(OrderedString);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> AbstractStringSet :
  <span class="ocamlkeyword">sig</span>
    <span class="ocamlkeyword">type</span> element = OrderedString.t
    <span class="ocamlkeyword">type</span> set = AbstractSet(OrderedString).set
    <span class="ocamlkeyword">val</span> empty : set
    <span class="ocamlkeyword">val</span> add : element -&gt; set -&gt; set
    <span class="ocamlkeyword">val</span> member : element -&gt; set -&gt; bool
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> AbstractStringSet.add <span class="ocamlstring">"gee"</span> AbstractStringSet.empty;;</div>



<div class="pre caml-output ok">- : AbstractStringSet.set = &lt;abstr&gt;</div></div>

</div><p>In an attempt to write the type constraint above more elegantly,
one may wish to name the signature of the structure
returned by the functor, then use that signature in the constraint:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> SET =
   <span class="ocamlkeyword">sig</span>
     <span class="ocamlkeyword">type</span> element
     <span class="ocamlkeyword">type</span> set
     <span class="ocamlkeyword">val</span> empty : set
     <span class="ocamlkeyword">val</span> add : element -&gt; set -&gt; set
     <span class="ocamlkeyword">val</span> member : element -&gt; set -&gt; bool
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> SET =
  <span class="ocamlkeyword">sig</span>
    <span class="ocamlkeyword">type</span> element
    <span class="ocamlkeyword">type</span> set
    <span class="ocamlkeyword">val</span> empty : set
    <span class="ocamlkeyword">val</span> add : element -&gt; set -&gt; set
    <span class="ocamlkeyword">val</span> member : element -&gt; set -&gt; bool
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> WrongSet = (Set : <span class="ocamlkeyword">functor</span>(Elt: ORDERED_TYPE) -&gt; SET);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> WrongSet : <span class="ocamlkeyword">functor</span> (Elt : ORDERED_TYPE) -&gt; SET</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> WrongStringSet = WrongSet(OrderedString);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> WrongStringSet :
  <span class="ocamlkeyword">sig</span>
    <span class="ocamlkeyword">type</span> element = WrongSet(OrderedString).element
    <span class="ocamlkeyword">type</span> set = WrongSet(OrderedString).set
    <span class="ocamlkeyword">val</span> empty : set
    <span class="ocamlkeyword">val</span> add : element -&gt; set -&gt; set
    <span class="ocamlkeyword">val</span> member : element -&gt; set -&gt; bool
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> WrongStringSet.add <span class="ocamlhighlight">"gee"</span> WrongStringSet.empty ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type string but an expression was expected of type
         WrongStringSet.element = WrongSet(OrderedString).element</div></div>

</div><p>


The problem here is that <span class="c003">SET</span> specifies the type <span class="c003">element</span>
abstractly, so that the type equality between <span class="c003">element</span> in the result
of the functor and <span class="c003">t</span> in its argument is forgotten. Consequently,
<span class="c003">WrongStringSet.element</span> is not the same type as <span class="c003">string</span>, and the
operations of <span class="c003">WrongStringSet</span> cannot be applied to strings.
As demonstrated above, it is important that the type <span class="c003">element</span> in the
signature <span class="c003">SET</span> be declared equal to <span class="c003">Elt.t</span>; unfortunately, this is
impossible above since <span class="c003">SET</span> is defined in a context where <span class="c003">Elt</span> does
not exist. To overcome this difficulty, OCaml provides a
<span class="c003">with type</span> construct over signatures that allows enriching a signature
with extra type equalities:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> AbstractSet2 =
   (Set : <span class="ocamlkeyword">functor</span>(Elt: ORDERED_TYPE) -&gt; (SET <span class="ocamlkeyword">with</span> <span class="ocamlkeyword">type</span> element = Elt.t));;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> AbstractSet2 :
  <span class="ocamlkeyword">functor</span> (Elt : ORDERED_TYPE) -&gt;
    <span class="ocamlkeyword">sig</span>
      <span class="ocamlkeyword">type</span> element = Elt.t
      <span class="ocamlkeyword">type</span> set
      <span class="ocamlkeyword">val</span> empty : set
      <span class="ocamlkeyword">val</span> add : element -&gt; set -&gt; set
      <span class="ocamlkeyword">val</span> member : element -&gt; set -&gt; bool
    <span class="ocamlkeyword">end</span></div></div>

</div><p>As in the case of simple structures, an alternate syntax is provided
for defining functors and restricting their result:
</p><pre>module AbstractSet2(Elt: ORDERED_TYPE) : (SET with type element = Elt.t) =
  struct ... end;;
</pre><p>
Abstracting a type component in a functor result is a powerful
technique that provides a high degree of type safety, as we now
illustrate. Consider an ordering over character strings that is
different from the standard ordering implemented in the
<span class="c003">OrderedString</span> structure. For instance, we compare strings without
distinguishing upper and lower case.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> NoCaseString =
   <span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">type</span> t = string
     <span class="ocamlkeyword">let</span> compare s1 s2 =
       OrderedString.compare (String.lowercase_ascii s1) (String.lowercase_ascii s2)
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> NoCaseString :
  <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> t = string <span class="ocamlkeyword">val</span> compare : string -&gt; string -&gt; comparison <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> NoCaseStringSet = AbstractSet(NoCaseString);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> NoCaseStringSet :
  <span class="ocamlkeyword">sig</span>
    <span class="ocamlkeyword">type</span> element = NoCaseString.t
    <span class="ocamlkeyword">type</span> set = AbstractSet(NoCaseString).set
    <span class="ocamlkeyword">val</span> empty : set
    <span class="ocamlkeyword">val</span> add : element -&gt; set -&gt; set
    <span class="ocamlkeyword">val</span> member : element -&gt; set -&gt; bool
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> NoCaseStringSet.add <span class="ocamlstring">"FOO"</span> <span class="ocamlhighlight">AbstractStringSet.empty</span> ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type
         AbstractStringSet.set = AbstractSet(OrderedString).set
       but an expression was expected of type
         NoCaseStringSet.set = AbstractSet(NoCaseString).set</div></div>

</div><p>


Note that the two types <span class="c003">AbstractStringSet.set</span> and
<span class="c003">NoCaseStringSet.set</span> are not compatible, and values of these
two types do not match. This is the correct behavior: even though both
set types contain elements of the same type (strings), they are built
upon different orderings of that type, and different invariants need
to be maintained by the operations (being strictly increasing for the
standard ordering and for the case-insensitive ordering). Applying
operations from <span class="c003">AbstractStringSet</span> to values of type
<span class="c003">NoCaseStringSet.set</span> could give incorrect results, or build
lists that violate the invariants of <span class="c003">NoCaseStringSet</span>.</p>
<!--TOC section id="s:separate-compilation" 2.5  Modules and separate compilation-->
<h2 class="section" id="s:separate-compilation"><a class="section-anchor" href="#s:separate-compilation" aria-hidden="true"></a>2.5  Modules and separate compilation</h2><!--SEC END --><p>All examples of modules so far have been given in the context of the
interactive system. However, modules are most useful for large,
batch-compiled programs. For these programs, it is a practical
necessity to split the source into several files, called compilation
units, that can be compiled separately, thus minimizing recompilation
after changes.</p><p>In OCaml, compilation units are special cases of structures
and signatures, and the relationship between the units can be
explained easily in terms of the module system. A compilation unit <span class="c009">A</span>
comprises two files:
</p><ul class="itemize"><li class="li-itemize">
the implementation file <span class="c009">A</span><span class="c003">.ml</span>, which contains a sequence
of definitions, analogous to the inside of a <span class="c003">struct</span>…<span class="c003">end</span>
construct;
</li><li class="li-itemize">the interface file <span class="c009">A</span><span class="c003">.mli</span>, which contains a sequence of
specifications, analogous to the inside of a <span class="c003">sig</span>…<span class="c003">end</span>
construct.
</li></ul><p>
These two files together define a structure named <span class="c009">A</span> as if
the following definition was entered at top-level:
</p><pre>
module <span class="c009">A</span>: sig (* contents of file <span class="c009">A</span>.mli *) end
        = struct (* contents of file <span class="c009">A</span>.ml *) end;;
</pre><p>
The files that define the compilation units can be compiled separately
using the <span class="c003">ocamlc -c</span> command (the <span class="c003">-c</span> option means “compile only, do
not try to link”); this produces compiled interface files (with
extension <span class="c003">.cmi</span>) and compiled object code files (with extension
<span class="c003">.cmo</span>). When all units have been compiled, their <span class="c003">.cmo</span> files are
linked together using the <span class="c003">ocamlc</span> command. For instance, the following
commands compile and link a program composed of two compilation units
<span class="c003">Aux</span> and <span class="c003">Main</span>:
</p><pre>$ ocamlc -c Aux.mli                     # produces aux.cmi
$ ocamlc -c Aux.ml                      # produces aux.cmo
$ ocamlc -c Main.mli                    # produces main.cmi
$ ocamlc -c Main.ml                     # produces main.cmo
$ ocamlc -o theprogram Aux.cmo Main.cmo
</pre><p>The program behaves exactly as if the following phrases were entered
at top-level:
</p><pre>
module Aux: sig (* contents of Aux.mli *) end
          = struct (* contents of Aux.ml *) end;;
module Main: sig (* contents of Main.mli *) end
           = struct (* contents of Main.ml *) end;;
</pre><p>
In particular, <span class="c003">Main</span> can refer to <span class="c003">Aux</span>: the definitions and
declarations contained in <span class="c003">Main.ml</span> and <span class="c003">Main.mli</span> can refer to
definition in <span class="c003">Aux.ml</span>, using the <span class="c003">Aux.</span><span class="c009">ident</span> notation, provided
these definitions are exported in <span class="c003">Aux.mli</span>.</p><p>The order in which the <span class="c003">.cmo</span> files are given to <span class="c003">ocamlc</span> during the
linking phase determines the order in which the module definitions
occur. Hence, in the example above, <span class="c003">Aux</span> appears first and <span class="c003">Main</span> can
refer to it, but <span class="c003">Aux</span> cannot refer to <span class="c003">Main</span>.</p><p>Note that only top-level structures can be mapped to
separately-compiled files, but neither functors nor module types.
However, all module-class objects can appear as components of a
structure, so the solution is to put the functor or module type
inside a structure, which can then be mapped to a file.

</p>
<!--TOC chapter id="sec26" Chapter 3  Objects in OCaml-->
<h1 class="chapter" id="sec26">Chapter 3  Objects in OCaml</h1><!--SEC END --><p>
<a id="c:objectexamples"></a>
</p><!--NAME objectexamples.html-->
<p>
<span class="c009">(Chapter written by Jérôme Vouillon, Didier Rémy and Jacques Garrigue)</span></p><p><br>
<br>
</p><p>This chapter gives an overview of the object-oriented features of
OCaml.</p><p>Note that the relationship between object, class and type in OCaml is
different than in mainstream object-oriented languages such as Java and
C++, so you shouldn’t assume that similar keywords mean the same thing.
Object-oriented features are used much less frequently in OCaml than
in those languages. OCaml has alternatives that are often more appropriate,
such as modules and functors. Indeed, many OCaml programs do not use objects
at all.</p>
<!--TOC section id="s:classes-and-objects" 3.1  Classes and objects-->
<h2 class="section" id="s:classes-and-objects"><a class="section-anchor" href="#s:classes-and-objects" aria-hidden="true"></a>3.1  Classes and objects</h2><!--SEC END --><p>The class <span class="c003">point</span> below defines one instance variable <span class="c003">x</span> and two methods
<span class="c003">get_x</span> and <span class="c003">move</span>. The initial value of the instance variable is <span class="c003">0</span>.
The variable <span class="c003">x</span> is declared mutable, so the method <span class="c003">move</span> can change
its value.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> point =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = 0
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> move d = x &lt;- x + d
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> point :
  <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int <span class="ocamlkeyword">method</span> get_x : int <span class="ocamlkeyword">method</span> move : int -&gt; unit <span class="ocamlkeyword">end</span></div></div>

</div><p>We now create a new point <span class="c003">p</span>, instance of the <span class="c003">point</span> class.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p = <span class="ocamlkeyword">new</span> point;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> p : point = &lt;obj&gt;</div></div>

</div><p>


Note that the type of <span class="c003">p</span> is <span class="c003">point</span>. This is an abbreviation
automatically defined by the class definition above. It stands for the
object type <span class="c003">&lt;get_x : int; move : int -&gt; unit&gt;</span>, listing the methods
of class <span class="c003">point</span> along with their types.</p><p>We now invoke some methods of <span class="c003">p</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> p#get_x;;</div>



<div class="pre caml-output ok">- : int = 0</div></div>
<div class="ocaml">



<div class="pre caml-input"> p#move 3;;</div>



<div class="pre caml-output ok">- : unit = ()</div></div>
<div class="ocaml">



<div class="pre caml-input"> p#get_x;;</div>



<div class="pre caml-output ok">- : int = 3</div></div>

</div><p>The evaluation of the body of a class only takes place at object
creation time. Therefore, in the following example, the instance
variable <span class="c003">x</span> is initialized to different values for two different
objects.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> x0 = <span class="ocamlkeyword">ref</span> 0;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> x0 : int <span class="ocamlkeyword">ref</span> = {contents = 0}</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> point =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = incr x0; !x0
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> move d = x &lt;- x + d
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> point :
  <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int <span class="ocamlkeyword">method</span> get_x : int <span class="ocamlkeyword">method</span> move : int -&gt; unit <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">new</span> point#get_x;;</div>



<div class="pre caml-output ok">- : int = 1</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">new</span> point#get_x;;</div>



<div class="pre caml-output ok">- : int = 2</div></div>

</div><p>The class <span class="c003">point</span> can also be abstracted over the initial values of
the <span class="c003">x</span> coordinate.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> point = <span class="ocamlkeyword">fun</span> x_init -&gt;
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = x_init
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> move d = x &lt;- x + d
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> point :
  int -&gt;
  <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int <span class="ocamlkeyword">method</span> get_x : int <span class="ocamlkeyword">method</span> move : int -&gt; unit <span class="ocamlkeyword">end</span></div></div>

</div><p>


Like in function definitions, the definition above can be
abbreviated as:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> point x_init =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = x_init
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> move d = x &lt;- x + d
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> point :
  int -&gt;
  <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int <span class="ocamlkeyword">method</span> get_x : int <span class="ocamlkeyword">method</span> move : int -&gt; unit <span class="ocamlkeyword">end</span></div></div>

</div><p>


An instance of the class <span class="c003">point</span> is now a function that expects an
initial parameter to create a point object:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">new</span> point;;</div>



<div class="pre caml-output ok">- : int -&gt; point = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p = <span class="ocamlkeyword">new</span> point 7;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> p : point = &lt;obj&gt;</div></div>

</div><p>


The parameter <span class="c003">x_init</span> is, of course, visible in the whole body of the
definition, including methods. For instance, the method <span class="c003">get_offset</span>
in the class below returns the position of the object relative to its
initial position.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> point x_init =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = x_init
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> get_offset = x - x_init
     <span class="ocamlkeyword">method</span> move d = x &lt;- x + d
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> point :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> get_offset : int
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


Expressions can be evaluated and bound before defining the object body
of the class. This is useful to enforce invariants. For instance,
points can be automatically adjusted to the nearest point on a grid,
as follows:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> adjusted_point x_init =
   <span class="ocamlkeyword">let</span> origin = (x_init / 10) * 10 <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = origin
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> get_offset = x - origin
     <span class="ocamlkeyword">method</span> move d = x &lt;- x + d
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> adjusted_point :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> get_offset : int
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


(One could also raise an exception if the <span class="c003">x_init</span> coordinate is not
on the grid.) In fact, the same effect could here be obtained by
calling the definition of class <span class="c003">point</span> with the value of the
<span class="c003">origin</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> adjusted_point x_init =  point ((x_init / 10) * 10);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> adjusted_point : int -&gt; point</div></div>

</div><p>


An alternate solution would have been to define the adjustment in
a special allocation function:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> new_adjusted_point x_init = <span class="ocamlkeyword">new</span> point ((x_init / 10) * 10);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> new_adjusted_point : int -&gt; point = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


However, the former pattern is generally more appropriate, since
the code for adjustment is part of the definition of the class and will be
inherited.</p><p>This ability provides class constructors as can be found in other
languages. Several constructors can be defined this way to build objects of
the same class but with different initialization patterns; an
alternative is to use initializers, as described below in
section <a href="#s%3Ainitializers">3.4</a>.</p>
<!--TOC section id="s:immediate-objects" 3.2  Immediate objects-->
<h2 class="section" id="s:immediate-objects"><a class="section-anchor" href="#s:immediate-objects" aria-hidden="true"></a>3.2  Immediate objects</h2><!--SEC END --><p>There is another, more direct way to create an object: create it
without going through a class.</p><p>The syntax is exactly the same as for class expressions, but the
result is a single object rather than a class. All the constructs
described in the rest of this section also apply to immediate objects.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = 0
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> move d = x &lt;- x + d
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> p : &lt; get_x : int; move : int -&gt; unit &gt; = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> p#get_x;;</div>



<div class="pre caml-output ok">- : int = 0</div></div>
<div class="ocaml">



<div class="pre caml-input"> p#move 3;;</div>



<div class="pre caml-output ok">- : unit = ()</div></div>
<div class="ocaml">



<div class="pre caml-input"> p#get_x;;</div>



<div class="pre caml-output ok">- : int = 3</div></div>

</div><p>Unlike classes, which cannot be defined inside an expression,
immediate objects can appear anywhere, using variables from their
environment.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> minmax x y =
   <span class="ocamlkeyword">if</span> x &lt; y <span class="ocamlkeyword">then</span> <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> min = x <span class="ocamlkeyword">method</span> max = y <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">else</span> <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> min = y <span class="ocamlkeyword">method</span> max = x <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> minmax : 'a -&gt; 'a -&gt; &lt; max : 'a; min : 'a &gt; = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>Immediate objects have two weaknesses compared to classes: their types
are not abbreviated, and you cannot inherit from them. But these two
weaknesses can be advantages in some situations, as we will see
in sections <a href="#s%3Areference-to-self">3.3</a> and <a href="#s%3Aparameterized-classes">3.10</a>.</p>
<!--TOC section id="s:reference-to-self" 3.3  Reference to self-->
<h2 class="section" id="s:reference-to-self"><a class="section-anchor" href="#s:reference-to-self" aria-hidden="true"></a>3.3  Reference to self</h2><!--SEC END --><p>A method or an initializer can invoke methods on self (that is,
the current object). For that, self must be explicitly bound, here to
the variable <span class="c003">s</span> (<span class="c003">s</span> could be any identifier, even though we will
often choose the name <span class="c003">self</span>.)


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> printable_point x_init =
   <span class="ocamlkeyword">object</span> (s)
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = x_init
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> move d = x &lt;- x + d
     <span class="ocamlkeyword">method</span> print = print_int s#get_x
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> printable_point :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
    <span class="ocamlkeyword">method</span> print : unit
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p = <span class="ocamlkeyword">new</span> printable_point 7;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> p : printable_point = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> p#print;;</div>



<div class="pre caml-output ok">7- : unit = ()</div></div>

</div><p>


Dynamically, the variable <span class="c003">s</span> is bound at the invocation of a method. In
particular, when the class <span class="c003">printable_point</span> is inherited, the variable
<span class="c003">s</span> will be correctly bound to the object of the subclass.</p><p>A common problem with self is that, as its type may be extended in
subclasses, you cannot fix it in advance. Here is a simple example.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> ints = <span class="ocamlkeyword">ref</span> [];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> ints : '_weak1 list <span class="ocamlkeyword">ref</span> = {contents = []}</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> my_int =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">method</span> n = 1
     <span class="ocamlkeyword">method</span> register = ints := <span class="ocamlhighlight">self</span> :: !ints
   <span class="ocamlkeyword">end</span> ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type &lt; n : int; register : 'a; .. &gt;
       but an expression was expected of type 'weak1
       Self type cannot escape its class</div></div>

</div><p>


You can ignore the first two lines of the error message. What matters
is the last one: putting self into an external reference would make it
impossible to extend it through inheritance.
We will see in section <a href="#s%3Ausing-coercions">3.12</a> a workaround to this
problem.
Note however that, since immediate objects are not extensible, the
problem does not occur with them.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> my_int =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">method</span> n = 1
     <span class="ocamlkeyword">method</span> register = ints := self :: !ints
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> my_int : &lt; n : int; register : unit &gt; = &lt;obj&gt;</div></div>

</div>
<!--TOC section id="s:initializers" 3.4  Initializers-->
<h2 class="section" id="s:initializers"><a class="section-anchor" href="#s:initializers" aria-hidden="true"></a>3.4  Initializers</h2><!--SEC END --><p>Let-bindings within class definitions are evaluated before the object
is constructed. It is also possible to evaluate an expression
immediately after the object has been built. Such code is written as
an anonymous hidden method called an initializer. Therefore, it can
access self and the instance variables.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> printable_point x_init =
   <span class="ocamlkeyword">let</span> origin = (x_init / 10) * 10 <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = origin
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> move d = x &lt;- x + d
     <span class="ocamlkeyword">method</span> print = print_int self#get_x
     <span class="ocamlkeyword">initializer</span> print_string <span class="ocamlstring">"new point at "</span>; self#print; print_newline ()
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> printable_point :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
    <span class="ocamlkeyword">method</span> print : unit
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p = <span class="ocamlkeyword">new</span> printable_point 17;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">new</span> point at 10
<span class="ocamlkeyword">val</span> p : printable_point = &lt;obj&gt;</div></div>

</div><p>


Initializers cannot be overridden. On the contrary, all initializers are
evaluated sequentially.
Initializers are particularly useful to enforce invariants.
Another example can be seen in section <a href="#s%3Aextended-bank-accounts">6.1</a>.</p>
<!--TOC section id="s:virtual-methods" 3.5  Virtual methods-->
<h2 class="section" id="s:virtual-methods"><a class="section-anchor" href="#s:virtual-methods" aria-hidden="true"></a>3.5  Virtual methods</h2><!--SEC END --><p>It is possible to declare a method without actually defining it, using
the keyword <span class="c003">virtual</span>. This method will be provided later in
subclasses. A class containing virtual methods must be flagged
<span class="c003">virtual</span>, and cannot be instantiated (that is, no object of this class
can be created). It still defines type abbreviations (treating virtual methods
as other methods.)


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">virtual</span> abstract_point x_init =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">virtual</span> get_x : int
     <span class="ocamlkeyword">method</span> get_offset = self#get_x - x_init
     <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">virtual</span> move : int -&gt; unit
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> <span class="ocamlkeyword">virtual</span> abstract_point :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">method</span> get_offset : int
    <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">virtual</span> get_x : int
    <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">virtual</span> move : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> point x_init =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> abstract_point x_init
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = x_init
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> move d = x &lt;- x + d
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> point :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> get_offset : int
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>Instance variables can also be declared as virtual, with the same effect
as with methods.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">virtual</span> abstract_point2 =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> <span class="ocamlkeyword">virtual</span> x : int
     <span class="ocamlkeyword">method</span> move d = x &lt;- x + d
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> <span class="ocamlkeyword">virtual</span> abstract_point2 :
  <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> <span class="ocamlkeyword">virtual</span> x : int <span class="ocamlkeyword">method</span> move : int -&gt; unit <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> point2 x_init =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> abstract_point2
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = x_init
     <span class="ocamlkeyword">method</span> get_offset = x - x_init
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> point2 :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> get_offset : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div>
<!--TOC section id="s:private-methods" 3.6  Private methods-->
<h2 class="section" id="s:private-methods"><a class="section-anchor" href="#s:private-methods" aria-hidden="true"></a>3.6  Private methods</h2><!--SEC END --><p>Private methods are methods that do not appear in object interfaces.
They can only be invoked from other methods of the same object.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> restricted_point x_init =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = x_init
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">private</span> move d = x &lt;- x + d
     <span class="ocamlkeyword">method</span> bump = self#move 1
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> restricted_point :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> bump : unit
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">private</span> move : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p = <span class="ocamlkeyword">new</span> restricted_point 0;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> p : restricted_point = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlhighlight">p</span>#move 10 ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type restricted_point
       It has no method move</div></div>
<div class="ocaml">



<div class="pre caml-input"> p#bump;;</div>



<div class="pre caml-output ok">- : unit = ()</div></div>

</div><p>


Note that this is not the same thing as private and protected methods
in Java or C++, which can be called from other objects of the same
class. This is a direct consequence of the independence between types
and classes in OCaml: two unrelated classes may produce
objects of the same type, and there is no way at the type level to
ensure that an object comes from a specific class. However a possible
encoding of friend methods is given in section <a href="#s%3Afriends">3.17</a>.</p><p>Private methods are inherited (they are by default visible in subclasses),
unless they are hidden by signature matching, as described below.</p><p>Private methods can be made public in a subclass.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> point_again x =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">inherit</span> restricted_point x
     <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">virtual</span> move : _
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> point_again :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> bump : unit
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


The annotation <span class="c003">virtual</span> here is only used to mention a method without
providing its definition. Since we didn’t add the <span class="c003">private</span>
annotation, this makes the method public, keeping the original
definition.</p><p>An alternative definition is


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> point_again x =
   <span class="ocamlkeyword">object</span> (self : &lt; move : _; ..&gt; )
     <span class="ocamlkeyword">inherit</span> restricted_point x
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> point_again :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> bump : unit
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


The constraint on self’s type is requiring a public <span class="c003">move</span> method, and
this is sufficient to override <span class="c003">private</span>.</p><p>One could think that a private method should remain private in a subclass.
However, since the method is visible in a subclass, it is always possible
to pick its code and define a method of the same name that runs that
code, so yet another (heavier) solution would be:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> point_again x =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> restricted_point x <span class="ocamlkeyword">as</span> super
     <span class="ocamlkeyword">method</span> move = super#move
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> point_again :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> bump : unit
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>Of course, private methods can also be virtual. Then, the keywords must
appear in this order <span class="c003">method private virtual</span>.</p>
<!--TOC section id="s:class-interfaces" 3.7  Class interfaces-->
<h2 class="section" id="s:class-interfaces"><a class="section-anchor" href="#s:class-interfaces" aria-hidden="true"></a>3.7  Class interfaces</h2><!--SEC END --><p>Class interfaces are inferred from class definitions. They may also
be defined directly and used to restrict the type of a class. Like class
declarations, they also define a new type abbreviation.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> restricted_point_type =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">method</span> get_x : int
     <span class="ocamlkeyword">method</span> bump : unit
 <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> restricted_point_type =
  <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> bump : unit <span class="ocamlkeyword">method</span> get_x : int <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">fun</span> (x : restricted_point_type) -&gt; x;;</div>



<div class="pre caml-output ok">- : restricted_point_type -&gt; restricted_point_type = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


In addition to program documentation, class interfaces can be used to
constrain the type of a class. Both concrete instance variables and concrete
private methods can be hidden by a class type constraint. Public
methods and virtual members, however, cannot.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> restricted_point' x = (restricted_point x : restricted_point_type);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> restricted_point' : int -&gt; restricted_point_type</div></div>

</div><p>


Or, equivalently:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> restricted_point' = (restricted_point : int -&gt; restricted_point_type);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> restricted_point' : int -&gt; restricted_point_type</div></div>

</div><p>


The interface of a class can also be specified in a module
signature, and used to restrict the inferred signature of a module.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> POINT = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">class</span> restricted_point' : int -&gt;
     <span class="ocamlkeyword">object</span>
       <span class="ocamlkeyword">method</span> get_x : int
       <span class="ocamlkeyword">method</span> bump : unit
     <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> POINT =
  <span class="ocamlkeyword">sig</span>
    <span class="ocamlkeyword">class</span> restricted_point' :
      int -&gt; <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> bump : unit <span class="ocamlkeyword">method</span> get_x : int <span class="ocamlkeyword">end</span>
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Point : POINT = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">class</span> restricted_point' = restricted_point
 <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> Point : POINT</div></div>

</div>
<!--TOC section id="s:inheritance" 3.8  Inheritance-->
<h2 class="section" id="s:inheritance"><a class="section-anchor" href="#s:inheritance" aria-hidden="true"></a>3.8  Inheritance</h2><!--SEC END --><p>We illustrate inheritance by defining a class of colored points that
inherits from the class of points. This class has all instance
variables and all methods of class <span class="c003">point</span>, plus a new instance
variable <span class="c003">c</span> and a new method <span class="c003">color</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> colored_point x (c : string) =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> point x
     <span class="ocamlkeyword">val</span> c = c
     <span class="ocamlkeyword">method</span> color = c
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> colored_point :
  int -&gt;
  string -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> c : string
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> color : string
    <span class="ocamlkeyword">method</span> get_offset : int
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p' = <span class="ocamlkeyword">new</span> colored_point 5 <span class="ocamlstring">"red"</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> p' : colored_point = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> p'#get_x, p'#color;;</div>



<div class="pre caml-output ok">- : int * string = (5, <span class="ocamlstring">"red"</span>)</div></div>

</div><p>


A point and a colored point have incompatible types, since a point has
no method <span class="c003">color</span>. However, the function <span class="c003">get_x</span> below is a generic
function applying method <span class="c003">get_x</span> to any object <span class="c003">p</span> that has this
method (and possibly some others, which are represented by an ellipsis
in the type). Thus, it applies to both points and colored points.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> get_succ_x p = p#get_x + 1;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> get_succ_x : &lt; get_x : int; .. &gt; -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> get_succ_x p + get_succ_x p';;</div>



<div class="pre caml-output ok">- : int = 8</div></div>

</div><p>


Methods need not be declared previously, as shown by the example:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> set_x p = p#set_x;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> set_x : &lt; set_x : 'a; .. &gt; -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> incr p = set_x p (get_succ_x p);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> incr : &lt; get_x : int; set_x : int -&gt; 'a; .. &gt; -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div>
<!--TOC section id="s:multiple-inheritance" 3.9  Multiple inheritance-->
<h2 class="section" id="s:multiple-inheritance"><a class="section-anchor" href="#s:multiple-inheritance" aria-hidden="true"></a>3.9  Multiple inheritance</h2><!--SEC END --><p>Multiple inheritance is allowed. Only the last definition of a method
is kept: the redefinition in a subclass of a method that was visible in
the parent class overrides the definition in the parent class.
Previous definitions of a method can be reused by binding the related
ancestor. Below, <span class="c003">super</span> is bound to the ancestor <span class="c003">printable_point</span>.
The name <span class="c003">super</span> is a pseudo value identifier that can only be used to
invoke a super-class method, as in <span class="c003">super#print</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> printable_colored_point y c =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">val</span> c = c
     <span class="ocamlkeyword">method</span> color = c
     <span class="ocamlkeyword">inherit</span> printable_point y <span class="ocamlkeyword">as</span> super
     <span class="ocamlkeyword">method</span>! print =
       print_string <span class="ocamlstring">"("</span>;
       super#print;
       print_string <span class="ocamlstring">", "</span>;
       print_string (self#color);
       print_string <span class="ocamlstring">")"</span>
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> printable_colored_point :
  int -&gt;
  string -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> c : string
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> color : string
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
    <span class="ocamlkeyword">method</span> print : unit
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p' = <span class="ocamlkeyword">new</span> printable_colored_point 17 <span class="ocamlstring">"red"</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">new</span> point at (10, red)
<span class="ocamlkeyword">val</span> p' : printable_colored_point = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> p'#print;;</div>



<div class="pre caml-output ok">(10, red)- : unit = ()</div></div>

</div><p>


A private method that has been hidden in the parent class is no longer
visible, and is thus not overridden. Since initializers are treated as
private methods, all initializers along the class hierarchy are evaluated,
in the order they are introduced.</p><p>Note that for clarity’s sake, the method <span class="c003">print</span> is explicitly marked as
overriding another definition by annotating the <span class="c003">method</span> keyword with
an exclamation mark <span class="c003">!</span>. If the method <span class="c003">print</span> were not overriding the
<span class="c003">print</span> method of <span class="c003">printable_point</span>, the compiler would raise an error:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">object</span>
     <span class="ocamlhighlight">method! m = ()</span>
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: The method `m' has no previous definition</div></div>

</div><p>This explicit overriding annotation also works
for <span class="c003">val</span> and <span class="c003">inherit</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> another_printable_colored_point y c c' =
   <span class="ocamlkeyword">object</span> (self)
   <span class="ocamlkeyword">inherit</span> printable_point y
   <span class="ocamlkeyword">inherit</span>! printable_colored_point y c
   <span class="ocamlkeyword">val</span>! c = c'
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> another_printable_colored_point :
  int -&gt;
  string -&gt;
  string -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> c : string
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> color : string
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
    <span class="ocamlkeyword">method</span> print : unit
  <span class="ocamlkeyword">end</span></div></div>

</div>
<!--TOC section id="s:parameterized-classes" 3.10  Parameterized classes-->
<h2 class="section" id="s:parameterized-classes"><a class="section-anchor" href="#s:parameterized-classes" aria-hidden="true"></a>3.10  Parameterized classes</h2><!--SEC END --><p>Reference cells can be implemented as objects.
The naive definition fails to typecheck:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlhighlight">class oref x_init =
   object
     val mutable x = x_init
     method get = x
     method set y = x &lt;- y
   end</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: Some type variables are unbound in this type:
         class oref :
           'a -&gt;
           object
             val mutable x : 'a
             method get : 'a
             method set : 'a -&gt; unit
           end
       The method get has type 'a where 'a is unbound</div></div>

</div><p>


The reason is that at least one of the methods has a polymorphic type
(here, the type of the value stored in the reference cell), thus
either the class should be parametric, or the method type should be
constrained to a monomorphic type. A monomorphic instance of the class could
be defined by:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> oref (x_init:int) =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = x_init
     <span class="ocamlkeyword">method</span> get = x
     <span class="ocamlkeyword">method</span> set y = x &lt;- y
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> oref :
  int -&gt;
  <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int <span class="ocamlkeyword">method</span> get : int <span class="ocamlkeyword">method</span> set : int -&gt; unit <span class="ocamlkeyword">end</span></div></div>

</div><p>


Note that since immediate objects do not define a class type, they have
no such restriction.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> new_oref x_init =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = x_init
     <span class="ocamlkeyword">method</span> get = x
     <span class="ocamlkeyword">method</span> set y = x &lt;- y
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> new_oref : 'a -&gt; &lt; get : 'a; set : 'a -&gt; unit &gt; = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


On the other hand, a class for polymorphic references must explicitly
list the type parameters in its declaration. Class type parameters are
listed between <span class="c003">[</span> and <span class="c003">]</span>. The type parameters must also be
bound somewhere in the class body by a type constraint.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a] oref x_init =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = (x_init : 'a)
     <span class="ocamlkeyword">method</span> get = x
     <span class="ocamlkeyword">method</span> set y = x &lt;- y
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] oref :
  'a -&gt; <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : 'a <span class="ocamlkeyword">method</span> get : 'a <span class="ocamlkeyword">method</span> set : 'a -&gt; unit <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> r = <span class="ocamlkeyword">new</span> oref 1 <span class="ocamlkeyword">in</span> r#set 2; (r#get);;</div>



<div class="pre caml-output ok">- : int = 2</div></div>

</div><p>


The type parameter in the declaration may actually be constrained in the
body of the class definition. In the class type, the actual value of
the type parameter is displayed in the <span class="c003">constraint</span> clause.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a] oref_succ (x_init:'a) =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x = x_init + 1
     <span class="ocamlkeyword">method</span> get = x
     <span class="ocamlkeyword">method</span> set y = x &lt;- y
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] oref_succ :
  'a -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">constraint</span> 'a = int
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> get : int
    <span class="ocamlkeyword">method</span> set : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


Let us consider a more complex example: define a circle, whose center
may be any kind of point. We put an additional type
constraint in method <span class="c003">move</span>, since no free variables must remain
unaccounted for by the class type parameters.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a] circle (c : 'a) =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> center = c
     <span class="ocamlkeyword">method</span> center = center
     <span class="ocamlkeyword">method</span> set_center c = center &lt;- c
     <span class="ocamlkeyword">method</span> move = (center#move : int -&gt; unit)
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] circle :
  'a -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">constraint</span> 'a = &lt; move : int -&gt; unit; .. &gt;
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> center : 'a
    <span class="ocamlkeyword">method</span> center : 'a
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
    <span class="ocamlkeyword">method</span> set_center : 'a -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


An alternate definition of <span class="c003">circle</span>, using a <span class="c003">constraint</span> clause in
the class definition, is shown below. The type <span class="c003">#point</span> used below in
the <span class="c003">constraint</span> clause is an abbreviation produced by the definition
of class <span class="c003">point</span>. This abbreviation unifies with the type of any
object belonging to a subclass of class <span class="c003">point</span>. It actually expands to
<span class="c003">&lt; get_x : int; move : int -&gt; unit; .. &gt;</span>. This leads to the following
alternate definition of <span class="c003">circle</span>, which has slightly stronger
constraints on its argument, as we now expect <span class="c003">center</span> to have a
method <span class="c003">get_x</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a] circle (c : 'a) =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">constraint</span> 'a = #point
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> center = c
     <span class="ocamlkeyword">method</span> center = center
     <span class="ocamlkeyword">method</span> set_center c = center &lt;- c
     <span class="ocamlkeyword">method</span> move = center#move
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] circle :
  'a -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">constraint</span> 'a = #point
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> center : 'a
    <span class="ocamlkeyword">method</span> center : 'a
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
    <span class="ocamlkeyword">method</span> set_center : 'a -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


The class <span class="c003">colored_circle</span> is a specialized version of class
<span class="c003">circle</span> that requires the type of the center to unify with
<span class="c003">#colored_point</span>, and adds a method <span class="c003">color</span>. Note that when specializing a
parameterized class, the instance of type parameter must always be
explicitly given. It is again written between <span class="c003">[</span> and <span class="c003">]</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a] colored_circle c =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">constraint</span> 'a = #colored_point
     <span class="ocamlkeyword">inherit</span> ['a] circle c
     <span class="ocamlkeyword">method</span> color = center#color
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] colored_circle :
  'a -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">constraint</span> 'a = #colored_point
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> center : 'a
    <span class="ocamlkeyword">method</span> center : 'a
    <span class="ocamlkeyword">method</span> color : string
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
    <span class="ocamlkeyword">method</span> set_center : 'a -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div>
<!--TOC section id="s:polymorphic-methods" 3.11  Polymorphic methods-->
<h2 class="section" id="s:polymorphic-methods"><a class="section-anchor" href="#s:polymorphic-methods" aria-hidden="true"></a>3.11  Polymorphic methods</h2><!--SEC END --><p>While parameterized classes may be polymorphic in their contents, they
are not enough to allow polymorphism of method use.</p><p>A classical example is defining an iterator.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> List.fold_left;;</div>



<div class="pre caml-output ok">- : ('a -&gt; 'b -&gt; 'a) -&gt; 'a -&gt; 'b list -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a] intlist (l : int list) =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">method</span> empty = (l = [])
     <span class="ocamlkeyword">method</span> fold f (accu : 'a) = List.fold_left f accu l
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] intlist :
  int list -&gt;
  <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> empty : bool <span class="ocamlkeyword">method</span> fold : ('a -&gt; int -&gt; 'a) -&gt; 'a -&gt; 'a <span class="ocamlkeyword">end</span></div></div>

</div><p>


At first look, we seem to have a polymorphic iterator, however this
does not work in practice.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> l = <span class="ocamlkeyword">new</span> intlist [1; 2; 3];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> l : '_weak2 intlist = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> l#fold (<span class="ocamlkeyword">fun</span> x y -&gt; x+y) 0;;</div>



<div class="pre caml-output ok">- : int = 6</div></div>
<div class="ocaml">



<div class="pre caml-input"> l;;</div>



<div class="pre caml-output ok">- : int intlist = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> l#fold (<span class="ocamlkeyword">fun</span> s x -&gt; <span class="ocamlhighlight">s</span> ^ Int.to_string x ^ <span class="ocamlstring">" "</span>) <span class="ocamlstring">""</span> ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type int but an expression was expected of type
         string</div></div>

</div><p>


Our iterator works, as shows its first use for summation. However,
since objects themselves are not polymorphic (only their constructors
are), using the <span class="c003">fold</span> method fixes its type for this individual object.
Our next attempt to use it as a string iterator fails.</p><p>The problem here is that quantification was wrongly located: it is
not the class we want to be polymorphic, but the <span class="c003">fold</span> method.
This can be achieved by giving an explicitly polymorphic type in the
method definition.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> intlist (l : int list) =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">method</span> empty = (l = [])
     <span class="ocamlkeyword">method</span> fold : 'a. ('a -&gt; int -&gt; 'a) -&gt; 'a -&gt; 'a =
       <span class="ocamlkeyword">fun</span> f accu -&gt; List.fold_left f accu l
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> intlist :
  int list -&gt;
  <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> empty : bool <span class="ocamlkeyword">method</span> fold : ('a -&gt; int -&gt; 'a) -&gt; 'a -&gt; 'a <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> l = <span class="ocamlkeyword">new</span> intlist [1; 2; 3];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> l : intlist = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> l#fold (<span class="ocamlkeyword">fun</span> x y -&gt; x+y) 0;;</div>



<div class="pre caml-output ok">- : int = 6</div></div>
<div class="ocaml">



<div class="pre caml-input"> l#fold (<span class="ocamlkeyword">fun</span> s x -&gt; s ^ Int.to_string x ^ <span class="ocamlstring">" "</span>) <span class="ocamlstring">""</span>;;</div>



<div class="pre caml-output ok">- : string = <span class="ocamlstring">"1 2 3 "</span></div></div>

</div><p>


As you can see in the class type shown by the compiler, while
polymorphic method types must be fully explicit in class definitions
(appearing immediately after the method name), quantified type
variables can be left implicit in class descriptions. Why require types
to be explicit? The problem is that <span class="c003">(int -&gt; int -&gt; int) -&gt; int -&gt; int</span> would also be a valid type for <span class="c003">fold</span>, and it happens to be
incompatible with the polymorphic type we gave (automatic
instantiation only works for toplevel types variables, not for inner
quantifiers, where it becomes an undecidable problem.) So the compiler
cannot choose between those two types, and must be helped.</p><p>However, the type can be completely omitted in the class definition if
it is already known, through inheritance or type constraints on self.
Here is an example of method overriding.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> intlist_rev l =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> intlist l
     <span class="ocamlkeyword">method</span>! fold f accu = List.fold_left f accu (List.rev l)
   <span class="ocamlkeyword">end</span>;;</div></div>

</div><p>


The following idiom separates description and definition.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> ['a] iterator =
   <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> fold : ('b -&gt; 'a -&gt; 'b) -&gt; 'b -&gt; 'b <span class="ocamlkeyword">end</span>;;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> intlist' l =
   <span class="ocamlkeyword">object</span> (self : int #iterator)
     <span class="ocamlkeyword">method</span> empty = (l = [])
     <span class="ocamlkeyword">method</span> fold f accu = List.fold_left f accu l
   <span class="ocamlkeyword">end</span>;;</div></div>

</div><p>


Note here the <span class="c003">(self : int #iterator)</span> idiom, which ensures that this
object implements the interface <span class="c003">iterator</span>.</p><p>Polymorphic methods are called in exactly the same way as normal
methods, but you should be aware of some limitations of type
inference. Namely, a polymorphic method can only be called if its
type is known at the call site. Otherwise, the method will be assumed
to be monomorphic, and given an incompatible type.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> sum lst = lst#fold (<span class="ocamlkeyword">fun</span> x y -&gt; x+y) 0;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> sum : &lt; fold : (int -&gt; int -&gt; int) -&gt; int -&gt; 'a; .. &gt; -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> sum <span class="ocamlhighlight">l</span> ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type intlist
       but an expression was expected of type
         &lt; fold : (int -&gt; int -&gt; int) -&gt; int -&gt; 'a; .. &gt;
       Types for method fold are incompatible</div></div>

</div><p>


The workaround is easy: you should put a type constraint on the
parameter.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> sum (lst : _ #iterator) = lst#fold (<span class="ocamlkeyword">fun</span> x y -&gt; x+y) 0;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> sum : int #iterator -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


Of course the constraint may also be an explicit method type.
Only occurrences of quantified variables are required.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> sum lst =
   (lst : &lt; fold : 'a. ('a -&gt; _ -&gt; 'a) -&gt; 'a -&gt; 'a; .. &gt;)#fold (+) 0;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> sum : &lt; fold : 'a. ('a -&gt; int -&gt; 'a) -&gt; 'a -&gt; 'a; .. &gt; -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>Another use of polymorphic methods is to allow some form of implicit
subtyping in method arguments. We have already seen in
section <a href="#s%3Ainheritance">3.8</a> how some functions may be polymorphic in the
class of their argument. This can be extended to methods.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> point0 = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> get_x : int <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> point0 = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> get_x : int <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> distance_point x =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> point x
     <span class="ocamlkeyword">method</span> distance : 'a. (#point0 <span class="ocamlkeyword">as</span> 'a) -&gt; int =
       <span class="ocamlkeyword">fun</span> other -&gt; abs (other#get_x - x)
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> distance_point :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
    <span class="ocamlkeyword">method</span> distance : #point0 -&gt; int
    <span class="ocamlkeyword">method</span> get_offset : int
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p = <span class="ocamlkeyword">new</span> distance_point 3 <span class="ocamlkeyword">in</span>
 (p#distance (<span class="ocamlkeyword">new</span> point 8), p#distance (<span class="ocamlkeyword">new</span> colored_point 1 <span class="ocamlstring">"blue"</span>));;</div>



<div class="pre caml-output ok">- : int * int = (5, 2)</div></div>

</div><p>


Note here the special syntax <span class="c003">(#point0 as 'a)</span> we have to use to
quantify the extensible part of <span class="c003">#point0</span>. As for the variable binder,
it can be omitted in class specifications. If you want polymorphism
inside object field it must be quantified independently.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> multi_poly =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">method</span> m1 : 'a. (&lt; n1 : 'b. 'b -&gt; 'b; .. &gt; <span class="ocamlkeyword">as</span> 'a) -&gt; _ =
       <span class="ocamlkeyword">fun</span> o -&gt; o#n1 <span class="ocamlkeyword">true</span>, o#n1 <span class="ocamlstring">"hello"</span>
     <span class="ocamlkeyword">method</span> m2 : 'a 'b. (&lt; n2 : 'b -&gt; bool; .. &gt; <span class="ocamlkeyword">as</span> 'a) -&gt; 'b -&gt; _ =
       <span class="ocamlkeyword">fun</span> o x -&gt; o#n2 x
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> multi_poly :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">method</span> m1 : &lt; n1 : 'b. 'b -&gt; 'b; .. &gt; -&gt; bool * string
    <span class="ocamlkeyword">method</span> m2 : &lt; n2 : 'b -&gt; bool; .. &gt; -&gt; 'b -&gt; bool
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


In method <span class="c003">m1</span>, <span class="c003">o</span> must be an object with at least a method <span class="c003">n1</span>,
itself polymorphic. In method <span class="c003">m2</span>, the argument of <span class="c003">n2</span> and <span class="c003">x</span> must
have the same type, which is quantified at the same level as <span class="c003">'a</span>.</p>
<!--TOC section id="s:using-coercions" 3.12  Using coercions-->
<h2 class="section" id="s:using-coercions"><a class="section-anchor" href="#s:using-coercions" aria-hidden="true"></a>3.12  Using coercions</h2><!--SEC END --><p>Subtyping is never implicit. There are, however, two ways to perform
subtyping. The most general construction is fully explicit: both the
domain and the codomain of the type coercion must be given.</p><p>We have seen that points and colored points have incompatible types.
For instance, they cannot be mixed in the same list. However, a
colored point can be coerced to a point, hiding its <span class="c003">color</span> method:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> colored_point_to_point cp = (cp : colored_point :&gt; point);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> colored_point_to_point : colored_point -&gt; point = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p = <span class="ocamlkeyword">new</span> point 3 <span class="ocamlkeyword">and</span> q = <span class="ocamlkeyword">new</span> colored_point 4 <span class="ocamlstring">"blue"</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> p : point = &lt;obj&gt;
<span class="ocamlkeyword">val</span> q : colored_point = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> l = [p; (colored_point_to_point q)];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> l : point list = [&lt;obj&gt;; &lt;obj&gt;]</div></div>

</div><p>


An object of type <span class="c003">t</span> can be seen as an object of type <span class="c003">t'</span>
only if <span class="c003">t</span> is a subtype of <span class="c003">t'</span>. For instance, a point cannot be
seen as a colored point.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlhighlight">(p : point :&gt; colored_point)</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: Type point = &lt; get_offset : int; get_x : int; move : int -&gt; unit &gt;
       is not a subtype of
         colored_point =
           &lt; color : string; get_offset : int; get_x : int;
             move : int -&gt; unit &gt;
       The first object type has no method color</div></div>

</div><p>


Indeed, narrowing coercions without runtime checks would be unsafe.
Runtime type checks might raise exceptions, and they would require
the presence of type information at runtime, which is not the case in
the OCaml system.
For these reasons, there is no such operation available in the language.</p><p>Be aware that subtyping and inheritance are not related. Inheritance is a
syntactic relation between classes while subtyping is a semantic relation
between types. For instance, the class of colored points could have been
defined directly, without inheriting from the class of points; the type of
colored points would remain unchanged and thus still be a subtype of
points.
</p><p>The domain of a coercion can often be omitted. For instance, one can
define:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> to_point cp = (cp :&gt; point);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> to_point : #point -&gt; point = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


In this case, the function <span class="c003">colored_point_to_point</span> is an instance of the
function <span class="c003">to_point</span>. This is not always true, however. The fully
explicit coercion is more precise and is sometimes unavoidable.
Consider, for example, the following class:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> c0 = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> m = {&lt; &gt;} <span class="ocamlkeyword">method</span> n = 0 <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> c0 : <span class="ocamlkeyword">object</span> ('a) <span class="ocamlkeyword">method</span> m : 'a <span class="ocamlkeyword">method</span> n : int <span class="ocamlkeyword">end</span></div></div>

</div><p>


The object type <span class="c003">c0</span> is an abbreviation for <span class="c003">&lt;m : 'a; n : int&gt; as 'a</span>.
Consider now the type declaration:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> c1 =  <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> m : c1 <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> c1 = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> m : c1 <span class="ocamlkeyword">end</span></div></div>

</div><p>


The object type <span class="c003">c1</span> is an abbreviation for the type <span class="c003">&lt;m : 'a&gt; as 'a</span>.
The coercion from an object of type <span class="c003">c0</span> to an object of type <span class="c003">c1</span> is
correct:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">fun</span> (x:c0) -&gt; (x : c0 :&gt; c1);;</div>



<div class="pre caml-output ok">- : c0 -&gt; c1 = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


However, the domain of the coercion cannot always be omitted.
In that case, the solution is to use the explicit form.
Sometimes, a change in the class-type definition can also solve the problem


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> c2 = <span class="ocamlkeyword">object</span> ('a) <span class="ocamlkeyword">method</span> m : 'a <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> c2 = <span class="ocamlkeyword">object</span> ('a) <span class="ocamlkeyword">method</span> m : 'a <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">fun</span> (x:c0) -&gt; (x :&gt; c2);;</div>



<div class="pre caml-output ok">- : c0 -&gt; c2 = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


While class types <span class="c003">c1</span> and <span class="c003">c2</span> are different, both object types
<span class="c003">c1</span> and <span class="c003">c2</span> expand to the same object type (same method names and types).
Yet, when the domain of a coercion is left implicit and its co-domain
is an abbreviation of a known class type, then the class type, rather
than the object type, is used to derive the coercion function. This
allows leaving the domain implicit in most cases when coercing form a
subclass to its superclass.
The type of a coercion can always be seen as below:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> to_c1 x = (x :&gt; c1);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> to_c1 : &lt; m : #c1; .. &gt; -&gt; c1 = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> to_c2 x = (x :&gt; c2);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> to_c2 : #c2 -&gt; c2 = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


Note the difference between these two coercions: in the case of <span class="c003">to_c2</span>,
the type
<span class="c003">#c2 = &lt; m : 'a; .. &gt; as 'a</span> is polymorphically recursive (according
to the explicit recursion in the class type of <span class="c003">c2</span>); hence the
success of applying this coercion to an object of class <span class="c003">c0</span>.
On the other hand, in the first case, <span class="c003">c1</span> was only expanded and
unrolled twice to obtain <span class="c003">&lt; m : &lt; m : c1; .. &gt;; .. &gt;</span> (remember <span class="c003">#c1 = &lt; m : c1; .. &gt;</span>), without introducing recursion.
You may also note that the type of <span class="c003">to_c2</span> is <span class="c003">#c2 -&gt; c2</span> while
the type of <span class="c003">to_c1</span> is more general than <span class="c003">#c1 -&gt; c1</span>. This is not always true,
since there are class types for which some instances of <span class="c003">#c</span> are not subtypes
of <span class="c003">c</span>, as explained in section <a href="#s%3Abinary-methods">3.16</a>. Yet, for
parameterless classes the coercion <span class="c003">(_ :&gt; c)</span> is always more general than
<span class="c003">(_ : #c :&gt; c)</span>.
</p><p>A common problem may occur when one tries to define a coercion to a
class <span class="c003">c</span> while defining class <span class="c003">c</span>. The problem is due to the type
abbreviation not being completely defined yet, and so its subtypes are not
clearly known. Then, a coercion <span class="c003">(_ :&gt; c)</span> or <span class="c003">(_ : #c :&gt; c)</span> is taken to be
the identity function, as in


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">function</span> x -&gt; (x :&gt; 'a);;</div>



<div class="pre caml-output ok">- : 'a -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


As a consequence, if the coercion is applied to <span class="c003">self</span>, as in the
following example, the type of <span class="c003">self</span> is unified with the closed type
<span class="c003">c</span> (a closed object type is an object type without ellipsis). This
would constrain the type of self be closed and is thus rejected.
Indeed, the type of self cannot be closed: this would prevent any
further extension of the class. Therefore, a type error is generated
when the unification of this type with another type would result in a
closed object type.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> c = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> m = 1 <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">and</span> d = <span class="ocamlkeyword">object</span> (self)
   <span class="ocamlkeyword">inherit</span> c
   <span class="ocamlkeyword">method</span> n = 2
   <span class="ocamlkeyword">method</span> as_c = (<span class="ocamlhighlight">self</span> :&gt; c)
 <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression cannot be coerced to type c = &lt; m : int &gt;; it has type
         &lt; as_c : c; m : int; n : int; .. &gt;
       but is here used with type c
       Self type cannot escape its class</div></div>

</div><p>


However, the most common instance of this problem, coercing self to
its current class, is detected as a special case by the type checker,
and properly typed.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> c = <span class="ocamlkeyword">object</span> (self) <span class="ocamlkeyword">method</span> m = (self :&gt; c) <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> c : <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> m : c <span class="ocamlkeyword">end</span></div></div>

</div><p>


This allows the following idiom, keeping a list of all objects
belonging to a class or its subclasses:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> all_c = <span class="ocamlkeyword">ref</span> [];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> all_c : '_weak3 list <span class="ocamlkeyword">ref</span> = {contents = []}</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> c (m : int) =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">method</span> m = m
     <span class="ocamlkeyword">initializer</span> all_c := (self :&gt; c) :: !all_c
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> c : int -&gt; <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> m : int <span class="ocamlkeyword">end</span></div></div>

</div><p>


This idiom can in turn be used to retrieve an object whose type has
been weakened:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> lookup_obj obj = <span class="ocamlkeyword">function</span> [] -&gt; raise Not_found
   | obj' :: l -&gt;
      <span class="ocamlkeyword">if</span> (obj :&gt; &lt; &gt;) = (obj' :&gt; &lt; &gt;) <span class="ocamlkeyword">then</span> obj' <span class="ocamlkeyword">else</span> lookup_obj obj l ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> lookup_obj : &lt; .. &gt; -&gt; (&lt; .. &gt; <span class="ocamlkeyword">as</span> 'a) list -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> lookup_c obj = lookup_obj obj !all_c;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> lookup_c : &lt; .. &gt; -&gt; &lt; m : int &gt; = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


The type <span class="c003">&lt; m : int &gt;</span> we see here is just the expansion of <span class="c003">c</span>, due
to the use of a reference; we have succeeded in getting back an object
of type <span class="c003">c</span>.</p><p><br>
The previous coercion problem can often be avoided by first
defining the abbreviation, using a class type:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> c' = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> m : int <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> c' = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> m : int <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> c : c' = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> m = 1 <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">and</span> d = <span class="ocamlkeyword">object</span> (self)
   <span class="ocamlkeyword">inherit</span> c
   <span class="ocamlkeyword">method</span> n = 2
   <span class="ocamlkeyword">method</span> as_c = (self :&gt; c')
 <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> c : c'
<span class="ocamlkeyword">and</span> d : <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> as_c : c' <span class="ocamlkeyword">method</span> m : int <span class="ocamlkeyword">method</span> n : int <span class="ocamlkeyword">end</span></div></div>

</div><p>


It is also possible to use a virtual class. Inheriting from this class
simultaneously forces all methods of <span class="c003">c</span> to have the same
type as the methods of <span class="c003">c'</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">virtual</span> c' = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">virtual</span> m : int <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> <span class="ocamlkeyword">virtual</span> c' : <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">virtual</span> m : int <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> c = <span class="ocamlkeyword">object</span> (self) <span class="ocamlkeyword">inherit</span> c' <span class="ocamlkeyword">method</span> m = 1 <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> c : <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> m : int <span class="ocamlkeyword">end</span></div></div>

</div><p>


One could think of defining the type abbreviation directly:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> c' = &lt;m : int&gt;;;</div></div>

</div><p>


However, the abbreviation <span class="c003">#c'</span> cannot be defined directly in a similar way.
It can only be defined by a class or a class-type definition.
This is because a <span class="c003">#</span>-abbreviation carries an implicit anonymous
variable <span class="c003">..</span> that cannot be explicitly named.
The closer you get to it is:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> 'a c'_class = 'a <span class="ocamlkeyword">constraint</span> 'a = &lt; m : int; .. &gt;;;</div></div>

</div><p>


with an extra type variable capturing the open object type.</p>
<!--TOC section id="s:functional-objects" 3.13  Functional objects-->
<h2 class="section" id="s:functional-objects"><a class="section-anchor" href="#s:functional-objects" aria-hidden="true"></a>3.13  Functional objects</h2><!--SEC END --><p>It is possible to write a version of class <span class="c003">point</span> without assignments
on the instance variables. The override construct <span class="c003">{&lt; ... &gt;}</span> returns a copy of
“self” (that is, the current object), possibly changing the value of
some instance variables.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> functional_point y =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> x = y
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> move d = {&lt; x = x + d &gt;}
     <span class="ocamlkeyword">method</span> move_to x = {&lt; x &gt;}
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> functional_point :
  int -&gt;
  <span class="ocamlkeyword">object</span> ('a)
    <span class="ocamlkeyword">val</span> x : int
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; 'a
    <span class="ocamlkeyword">method</span> move_to : int -&gt; 'a
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p = <span class="ocamlkeyword">new</span> functional_point 7;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> p : functional_point = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> p#get_x;;</div>



<div class="pre caml-output ok">- : int = 7</div></div>
<div class="ocaml">



<div class="pre caml-input"> (p#move 3)#get_x;;</div>



<div class="pre caml-output ok">- : int = 10</div></div>
<div class="ocaml">



<div class="pre caml-input"> (p#move_to 15)#get_x;;</div>



<div class="pre caml-output ok">- : int = 15</div></div>
<div class="ocaml">



<div class="pre caml-input"> p#get_x;;</div>



<div class="pre caml-output ok">- : int = 7</div></div>

</div><p>


As with records, the form <span class="c003">{&lt; x &gt;}</span> is an elided version of
<span class="c003">{&lt; x = x &gt;}</span> which avoids the repetition of the instance variable name.
Note that the type abbreviation <span class="c003">functional_point</span> is recursive, which can
be seen in the class type of <span class="c003">functional_point</span>: the type of self is <span class="c003">'a</span>
and <span class="c003">'a</span> appears inside the type of the method <span class="c003">move</span>.</p><p>The above definition of <span class="c003">functional_point</span> is not equivalent
to the following:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> bad_functional_point y =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> x = y
     <span class="ocamlkeyword">method</span> get_x = x
     <span class="ocamlkeyword">method</span> move d = <span class="ocamlkeyword">new</span> bad_functional_point (x+d)
     <span class="ocamlkeyword">method</span> move_to x = <span class="ocamlkeyword">new</span> bad_functional_point x
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> bad_functional_point :
  int -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> x : int
    <span class="ocamlkeyword">method</span> get_x : int
    <span class="ocamlkeyword">method</span> move : int -&gt; bad_functional_point
    <span class="ocamlkeyword">method</span> move_to : int -&gt; bad_functional_point
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


While objects of either class will behave the same, objects of their
subclasses will be different. In a subclass of <span class="c003">bad_functional_point</span>,
the method <span class="c003">move</span> will
keep returning an object of the parent class. On the contrary, in a
subclass of <span class="c003">functional_point</span>, the method <span class="c003">move</span> will return an
object of the subclass.</p><p>Functional update is often used in conjunction with binary methods
as illustrated in section <a href="#ss%3Astring-as-class">6.2.1</a>.</p>
<!--TOC section id="s:cloning-objects" 3.14  Cloning objects-->
<h2 class="section" id="s:cloning-objects"><a class="section-anchor" href="#s:cloning-objects" aria-hidden="true"></a>3.14  Cloning objects</h2><!--SEC END --><p>Objects can also be cloned, whether they are functional or imperative.
The library function <span class="c003">Oo.copy</span> makes a shallow copy of an object. That is,
it returns a new object that has the same methods and instance
variables as its argument. The
instance variables are copied but their contents are shared.
Assigning a new value to an instance variable of the copy (using a method
call) will not affect instance variables of the original, and conversely.
A deeper assignment (for example if the instance variable is a reference cell)
will of course affect both the original and the copy.</p><p>The type of <span class="c003">Oo.copy</span> is the following:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> Oo.copy;;</div>



<div class="pre caml-output ok">- : (&lt; .. &gt; <span class="ocamlkeyword">as</span> 'a) -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


The keyword <span class="c003">as</span> in that type binds the type variable <span class="c003">'a</span> to
the object type <span class="c003">&lt; .. &gt;</span>. Therefore, <span class="c003">Oo.copy</span> takes an object with
any methods (represented by the ellipsis), and returns an object of
the same type. The type of <span class="c003">Oo.copy</span> is different from type <span class="c003">&lt; .. &gt; -&gt; &lt; .. &gt;</span> as each ellipsis represents a different set of methods.
Ellipsis actually behaves as a type variable.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p = <span class="ocamlkeyword">new</span> point 5;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> p : point = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> q = Oo.copy p;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> q : point = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> q#move 7; (p#get_x, q#get_x);;</div>



<div class="pre caml-output ok">- : int * int = (5, 12)</div></div>

</div><p>


In fact, <span class="c003">Oo.copy p</span> will behave as <span class="c003">p#copy</span> assuming that a public
method <span class="c003">copy</span> with body <span class="c003">{&lt; &gt;}</span> has been defined in the class of <span class="c003">p</span>.</p><p>Objects can be compared using the generic comparison functions <span class="c003">=</span> and <span class="c003">&lt;&gt;</span>.
Two objects are equal if and only if they are physically equal. In
particular, an object and its copy are not equal.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> q = Oo.copy p;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> q : point = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> p = q, p = p;;</div>



<div class="pre caml-output ok">- : bool * bool = (<span class="ocamlkeyword">false</span>, <span class="ocamlkeyword">true</span>)</div></div>

</div><p>


Other generic comparisons such as (<span class="c003">&lt;</span>, <span class="c003">&lt;=</span>, ...) can also be used on
objects. The
relation <span class="c003">&lt;</span> defines an unspecified but strict ordering on objects. The
ordering relationship between two objects is fixed once for all after the
two objects have been created and it is not affected by mutation of fields.</p><p>Cloning and override have a non empty intersection.
They are interchangeable when used within an object and without
overriding any field:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> copy =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">method</span> copy = {&lt; &gt;}
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> copy : <span class="ocamlkeyword">object</span> ('a) <span class="ocamlkeyword">method</span> copy : 'a <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> copy =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">method</span> copy = Oo.copy self
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> copy : <span class="ocamlkeyword">object</span> ('a) <span class="ocamlkeyword">method</span> copy : 'a <span class="ocamlkeyword">end</span></div></div>

</div><p>


Only the override can be used to actually override fields, and
only the <span class="c003">Oo.copy</span> primitive can be used externally.</p><p>Cloning can also be used to provide facilities for saving and
restoring the state of objects.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> backup =
   <span class="ocamlkeyword">object</span> (self : 'mytype)
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> copy = None
     <span class="ocamlkeyword">method</span> save = copy &lt;- Some {&lt; copy = None &gt;}
     <span class="ocamlkeyword">method</span> restore = <span class="ocamlkeyword">match</span> copy <span class="ocamlkeyword">with</span> Some x -&gt; x | None -&gt; self
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> backup :
  <span class="ocamlkeyword">object</span> ('a)
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> copy : 'a option
    <span class="ocamlkeyword">method</span> restore : 'a
    <span class="ocamlkeyword">method</span> save : unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


The above definition will only backup one level.
The backup facility can be added to any class by using multiple inheritance.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a] backup_ref x = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">inherit</span> ['a] oref x <span class="ocamlkeyword">inherit</span> backup <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] backup_ref :
  'a -&gt;
  <span class="ocamlkeyword">object</span> ('b)
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> copy : 'b option
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : 'a
    <span class="ocamlkeyword">method</span> get : 'a
    <span class="ocamlkeyword">method</span> restore : 'b
    <span class="ocamlkeyword">method</span> save : unit
    <span class="ocamlkeyword">method</span> set : 'a -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> get p n = <span class="ocamlkeyword">if</span> n = 0 <span class="ocamlkeyword">then</span> p # get <span class="ocamlkeyword">else</span> get (p # restore) (n-1);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> get : (&lt; get : 'b; restore : 'a; .. &gt; <span class="ocamlkeyword">as</span> 'a) -&gt; int -&gt; 'b = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p = <span class="ocamlkeyword">new</span> backup_ref 0  <span class="ocamlkeyword">in</span>
 p # save; p # set 1; p # save; p # set 2;
 [get p 0; get p 1; get p 2; get p 3; get p 4];;</div>



<div class="pre caml-output ok">- : int list = [2; 1; 1; 1; 1]</div></div>

</div><p>


We can define a variant of backup that retains all copies. (We also
add a method <span class="c003">clear</span> to manually erase all copies.)


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> backup =
   <span class="ocamlkeyword">object</span> (self : 'mytype)
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> copy = None
     <span class="ocamlkeyword">method</span> save = copy &lt;- Some {&lt; &gt;}
     <span class="ocamlkeyword">method</span> restore = <span class="ocamlkeyword">match</span> copy <span class="ocamlkeyword">with</span> Some x -&gt; x | None -&gt; self
     <span class="ocamlkeyword">method</span> clear = copy &lt;- None
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> backup :
  <span class="ocamlkeyword">object</span> ('a)
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> copy : 'a option
    <span class="ocamlkeyword">method</span> clear : unit
    <span class="ocamlkeyword">method</span> restore : 'a
    <span class="ocamlkeyword">method</span> save : unit
  <span class="ocamlkeyword">end</span></div></div>

</div><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a] backup_ref x = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">inherit</span> ['a] oref x <span class="ocamlkeyword">inherit</span> backup <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] backup_ref :
  'a -&gt;
  <span class="ocamlkeyword">object</span> ('b)
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> copy : 'b option
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : 'a
    <span class="ocamlkeyword">method</span> clear : unit
    <span class="ocamlkeyword">method</span> get : 'a
    <span class="ocamlkeyword">method</span> restore : 'b
    <span class="ocamlkeyword">method</span> save : unit
    <span class="ocamlkeyword">method</span> set : 'a -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> p = <span class="ocamlkeyword">new</span> backup_ref 0  <span class="ocamlkeyword">in</span>
 p # save; p # set 1; p # save; p # set 2;
 [get p 0; get p 1; get p 2; get p 3; get p 4];;</div>



<div class="pre caml-output ok">- : int list = [2; 1; 0; 0; 0]</div></div>

</div>
<!--TOC section id="s:recursive-classes" 3.15  Recursive classes-->
<h2 class="section" id="s:recursive-classes"><a class="section-anchor" href="#s:recursive-classes" aria-hidden="true"></a>3.15  Recursive classes</h2><!--SEC END --><p>Recursive classes can be used to define objects whose types are
mutually recursive.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> window =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> top_widget = (None : widget option)
     <span class="ocamlkeyword">method</span> top_widget = top_widget
   <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">and</span> widget (w : window) =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> window = w
     <span class="ocamlkeyword">method</span> window = window
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> window :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> top_widget : widget option
    <span class="ocamlkeyword">method</span> top_widget : widget option
  <span class="ocamlkeyword">end</span>
<span class="ocamlkeyword">and</span> widget : window -&gt; <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">val</span> window : window <span class="ocamlkeyword">method</span> window : window <span class="ocamlkeyword">end</span></div></div>

</div><p>


Although their types are mutually recursive, the classes <span class="c003">widget</span> and
<span class="c003">window</span> are themselves independent.</p>
<!--TOC section id="s:binary-methods" 3.16  Binary methods-->
<h2 class="section" id="s:binary-methods"><a class="section-anchor" href="#s:binary-methods" aria-hidden="true"></a>3.16  Binary methods</h2><!--SEC END --><p>A binary method is a method which takes an argument of the same type
as self. The class <span class="c003">comparable</span> below is a template for classes with a
binary method <span class="c003">leq</span> of type <span class="c003">'a -&gt; bool</span> where the type variable <span class="c003">'a</span>
is bound to the type of self. Therefore, <span class="c003">#comparable</span> expands to <span class="c003">&lt; leq : 'a -&gt; bool; .. &gt; as 'a</span>. We see here that the binder <span class="c003">as</span> also
allows writing recursive types.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">virtual</span> comparable =
   <span class="ocamlkeyword">object</span> (_ : 'a)
     <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">virtual</span> leq : 'a -&gt; bool
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> <span class="ocamlkeyword">virtual</span> comparable : <span class="ocamlkeyword">object</span> ('a) <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">virtual</span> leq : 'a -&gt; bool <span class="ocamlkeyword">end</span></div></div>

</div><p>


We then define a subclass <span class="c003">money</span> of <span class="c003">comparable</span>. The class <span class="c003">money</span>
simply wraps floats as comparable objects. We will extend it below with
more operations. We have to use a type constraint on the class parameter <span class="c003">x</span>
because the primitive <span class="c003">&lt;=</span> is a polymorphic function in
OCaml. The <span class="c003">inherit</span> clause ensures that the type of objects
of this class is an instance of <span class="c003">#comparable</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> money (x : float) =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> comparable
     <span class="ocamlkeyword">val</span> repr = x
     <span class="ocamlkeyword">method</span> value = repr
     <span class="ocamlkeyword">method</span> leq p = repr &lt;= p#value
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> money :
  float -&gt;
  <span class="ocamlkeyword">object</span> ('a)
    <span class="ocamlkeyword">val</span> repr : float
    <span class="ocamlkeyword">method</span> leq : 'a -&gt; bool
    <span class="ocamlkeyword">method</span> value : float
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


Note that the type <span class="c003">money</span> is not a subtype of type
<span class="c003">comparable</span>, as the self type appears in contravariant position
in the type of method <span class="c003">leq</span>.
Indeed, an object <span class="c003">m</span> of class <span class="c003">money</span> has a method <span class="c003">leq</span>
that expects an argument of type <span class="c003">money</span> since it accesses
its <span class="c003">value</span> method. Considering <span class="c003">m</span> of type <span class="c003">comparable</span> would allow a
call to method <span class="c003">leq</span> on <span class="c003">m</span> with an argument that does not have a method
<span class="c003">value</span>, which would be an error.</p><p>Similarly, the type <span class="c003">money2</span> below is not a subtype of type <span class="c003">money</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> money2 x =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> money x
     <span class="ocamlkeyword">method</span> times k = {&lt; repr = k *. repr &gt;}
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> money2 :
  float -&gt;
  <span class="ocamlkeyword">object</span> ('a)
    <span class="ocamlkeyword">val</span> repr : float
    <span class="ocamlkeyword">method</span> leq : 'a -&gt; bool
    <span class="ocamlkeyword">method</span> times : float -&gt; 'a
    <span class="ocamlkeyword">method</span> value : float
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


It is however possible to define functions that manipulate objects of
type either <span class="c003">money</span> or <span class="c003">money2</span>: the function <span class="c003">min</span>
will return the minimum of any two objects whose type unifies with
<span class="c003">#comparable</span>. The type of <span class="c003">min</span> is not the same as <span class="c003">#comparable -&gt; #comparable -&gt; #comparable</span>, as the abbreviation <span class="c003">#comparable</span> hides a
type variable (an ellipsis). Each occurrence of this abbreviation
generates a new variable.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> min (x : #comparable) y =
   <span class="ocamlkeyword">if</span> x#leq y <span class="ocamlkeyword">then</span> x <span class="ocamlkeyword">else</span> y;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> min : (#comparable <span class="ocamlkeyword">as</span> 'a) -&gt; 'a -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


This function can be applied to objects of type <span class="c003">money</span>
or <span class="c003">money2</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> (min (<span class="ocamlkeyword">new</span> money  1.3) (<span class="ocamlkeyword">new</span> money 3.1))#value;;</div>



<div class="pre caml-output ok">- : float = 1.3</div></div>
<div class="ocaml">



<div class="pre caml-input"> (min (<span class="ocamlkeyword">new</span> money2 5.0) (<span class="ocamlkeyword">new</span> money2 3.14))#value;;</div>



<div class="pre caml-output ok">- : float = 3.14</div></div>

</div><p>More examples of binary methods can be found in
sections <a href="#ss%3Astring-as-class">6.2.1</a> and <a href="#ss%3Aset-as-class">6.2.3</a>.</p><p>Note the use of override for method <span class="c003">times</span>.
Writing <span class="c003">new money2 (k *. repr)</span> instead of <span class="c003">{&lt; repr = k *. repr &gt;}</span>
would not behave well with inheritance: in a subclass <span class="c003">money3</span> of <span class="c003">money2</span>
the <span class="c003">times</span> method would return an object of class <span class="c003">money2</span> but not of class
<span class="c003">money3</span> as would be expected.</p><p>The class <span class="c003">money</span> could naturally carry another binary method. Here is a
direct definition:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> money x =
   <span class="ocamlkeyword">object</span> (self : 'a)
     <span class="ocamlkeyword">val</span> repr = x
     <span class="ocamlkeyword">method</span> value = repr
     <span class="ocamlkeyword">method</span> print = print_float repr
     <span class="ocamlkeyword">method</span> times k = {&lt; repr = k *. x &gt;}
     <span class="ocamlkeyword">method</span> leq (p : 'a) = repr &lt;= p#value
     <span class="ocamlkeyword">method</span> plus (p : 'a) = {&lt; repr = x +. p#value &gt;}
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> money :
  float -&gt;
  <span class="ocamlkeyword">object</span> ('a)
    <span class="ocamlkeyword">val</span> repr : float
    <span class="ocamlkeyword">method</span> leq : 'a -&gt; bool
    <span class="ocamlkeyword">method</span> plus : 'a -&gt; 'a
    <span class="ocamlkeyword">method</span> print : unit
    <span class="ocamlkeyword">method</span> times : float -&gt; 'a
    <span class="ocamlkeyword">method</span> value : float
  <span class="ocamlkeyword">end</span></div></div>

</div>
<!--TOC section id="s:friends" 3.17  Friends-->
<h2 class="section" id="s:friends"><a class="section-anchor" href="#s:friends" aria-hidden="true"></a>3.17  Friends</h2><!--SEC END --><p>The above class <span class="c003">money</span> reveals a problem that often occurs with binary
methods. In order to interact with other objects of the same class, the
representation of <span class="c003">money</span> objects must be revealed, using a method such as
<span class="c003">value</span>. If we remove all binary methods (here <span class="c003">plus</span> and <span class="c003">leq</span>),
the representation can easily be hidden inside objects by removing the method
<span class="c003">value</span> as well. However, this is not possible as soon as some binary
method requires access to the representation of objects of the same
class (other than self).


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> safe_money x =
   <span class="ocamlkeyword">object</span> (self : 'a)
     <span class="ocamlkeyword">val</span> repr = x
     <span class="ocamlkeyword">method</span> print = print_float repr
     <span class="ocamlkeyword">method</span> times k = {&lt; repr = k *. x &gt;}
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> safe_money :
  float -&gt;
  <span class="ocamlkeyword">object</span> ('a)
    <span class="ocamlkeyword">val</span> repr : float
    <span class="ocamlkeyword">method</span> print : unit
    <span class="ocamlkeyword">method</span> times : float -&gt; 'a
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


Here, the representation of the object is known only to a particular object.
To make it available to other objects of the same class, we are forced to
make it available to the whole world. However we can easily restrict the
visibility of the representation using the module system.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> MONEY =
   <span class="ocamlkeyword">sig</span>
     <span class="ocamlkeyword">type</span> t
     <span class="ocamlkeyword">class</span> c : float -&gt;
       <span class="ocamlkeyword">object</span> ('a)
         <span class="ocamlkeyword">val</span> repr : t
         <span class="ocamlkeyword">method</span> value : t
         <span class="ocamlkeyword">method</span> print : unit
         <span class="ocamlkeyword">method</span> times : float -&gt; 'a
         <span class="ocamlkeyword">method</span> leq : 'a -&gt; bool
         <span class="ocamlkeyword">method</span> plus : 'a -&gt; 'a
       <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">end</span>;;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Euro : MONEY =
   <span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">type</span> t = float
     <span class="ocamlkeyword">class</span> c x =
       <span class="ocamlkeyword">object</span> (self : 'a)
         <span class="ocamlkeyword">val</span> repr = x
         <span class="ocamlkeyword">method</span> value = repr
         <span class="ocamlkeyword">method</span> print = print_float repr
         <span class="ocamlkeyword">method</span> times k = {&lt; repr = k *. x &gt;}
         <span class="ocamlkeyword">method</span> leq (p : 'a) = repr &lt;= p#value
         <span class="ocamlkeyword">method</span> plus (p : 'a) = {&lt; repr = x +. p#value &gt;}
       <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">end</span>;;</div></div>

</div><p>


Another example of friend functions may be found in section <a href="#ss%3Aset-as-class">6.2.3</a>.
These examples occur when a group of objects (here
objects of the same class) and functions should see each others internal
representation, while their representation should be hidden from the
outside. The solution is always to define all friends in the same module,
give access to the representation and use a signature constraint to make the
representation abstract outside the module.</p>
<!--TOC chapter id="sec44" Chapter 4  Labels and variants-->
<h1 class="chapter" id="sec44">Chapter 4  Labels and variants</h1><!--SEC END --><p> <a id="c:labl-examples"></a>
</p><!--NAME lablexamples.html-->
<p>
<span class="c009">(Chapter written by Jacques Garrigue)</span></p><p><br>
<br>
</p><p>This chapter gives an overview of the new features in
OCaml 3: labels, and polymorphic variants.</p>
<!--TOC section id="s:labels" 4.1  Labels-->
<h2 class="section" id="s:labels"><a class="section-anchor" href="#s:labels" aria-hidden="true"></a>4.1  Labels</h2><!--SEC END --><p>If you have a look at modules ending in <span class="c003">Labels</span> in the standard
library, you will see that function types have annotations you did not
have in the functions you defined yourself.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> ListLabels.map;;</div>



<div class="pre caml-output ok">- : f:('a -&gt; 'b) -&gt; 'a list -&gt; 'b list = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> StringLabels.sub;;</div>



<div class="pre caml-output ok">- : string -&gt; pos:int -&gt; len:int -&gt; string = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>Such annotations of the form <span class="c003">name:</span> are called <em>labels</em>. They are
meant to document the code, allow more checking, and give more
flexibility to function application.
You can give such names to arguments in your programs, by prefixing them
with a tilde <span class="c003">~</span>.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f ~x ~y = x - y;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f : x:int -&gt; y:int -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> x = 3 <span class="ocamlkeyword">and</span> y = 2 <span class="ocamlkeyword">in</span> f ~x ~y;;</div>



<div class="pre caml-output ok">- : int = 1</div></div>

</div><p>When you want to use distinct names for the variable and the label
appearing in the type, you can use a naming label of the form
<span class="c003">~name:</span>. This also applies when the argument is not a variable.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f ~x:x1 ~y:y1 = x1 - y1;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f : x:int -&gt; y:int -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> f ~x:3 ~y:2;;</div>



<div class="pre caml-output ok">- : int = 1</div></div>

</div><p>Labels obey the same rules as other identifiers in OCaml, that is you
cannot use a reserved keyword (like <span class="c003">in</span> or <span class="c003">to</span>) as label.</p><p>Formal parameters and arguments are matched according to their
respective labels<sup><a id="text1" href="#note1">1</a></sup>, the absence of label
being interpreted as the empty label.
This allows commuting arguments in applications. One can also
partially apply a function on any argument, creating a new function of
the remaining parameters.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f ~x ~y = x - y;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f : x:int -&gt; y:int -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> f ~y:2 ~x:3;;</div>



<div class="pre caml-output ok">- : int = 1</div></div>
<div class="ocaml">



<div class="pre caml-input"> ListLabels.fold_left;;</div>



<div class="pre caml-output ok">- : f:('a -&gt; 'b -&gt; 'a) -&gt; init:'a -&gt; 'b list -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> ListLabels.fold_left [1;2;3] ~init:0 ~f:( + );;</div>



<div class="pre caml-output ok">- : int = 6</div></div>
<div class="ocaml">



<div class="pre caml-input"> ListLabels.fold_left ~init:0;;</div>



<div class="pre caml-output ok">- : f:(int -&gt; 'a -&gt; int) -&gt; 'a list -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>If several arguments of a function bear the same label (or no label),
they will not commute among themselves, and order matters. But they
can still commute with other arguments.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> hline ~x:x1 ~x:x2 ~y = (x1, x2, y);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> hline : x:'a -&gt; x:'b -&gt; y:'c -&gt; 'a * 'b * 'c = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> hline ~x:3 ~y:2 ~x:5;;</div>



<div class="pre caml-output ok">- : int * int * int = (3, 5, 2)</div></div>

</div><p>As an exception to the above parameter matching rules, if an
application is total (omitting all optional arguments), labels may be
omitted.
In practice, many applications are total, so that labels can often be
omitted.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> f 3 2;;</div>



<div class="pre caml-output ok">- : int = 1</div></div>
<div class="ocaml">



<div class="pre caml-input"> ListLabels.map succ [1;2;3];;</div>



<div class="pre caml-output ok">- : int list = [2; 3; 4]</div></div>

</div><p>


But beware that functions like <span class="c003">ListLabels.fold_left</span> whose result
type is a type variable will never be considered as totally applied.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> ListLabels.fold_left <span class="ocamlhighlight">( + )</span> 0 [1;2;3];;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type int -&gt; int -&gt; int
       but an expression was expected of type 'a list</div></div>

</div><p>When a function is passed as an argument to a higher-order function,
labels must match in both types. Neither adding nor removing labels
are allowed.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> h g = g ~x:3 ~y:2;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> h : (x:int -&gt; y:int -&gt; 'a) -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> h f;;</div>



<div class="pre caml-output ok">- : int = 1</div></div>
<div class="ocaml">



<div class="pre caml-input"> h <span class="ocamlhighlight">( + )</span> ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type int -&gt; int -&gt; int
       but an expression was expected of type x:int -&gt; y:int -&gt; 'a</div></div>

</div><p>


Note that when you don’t need an argument, you can still use a wildcard
pattern, but you must prefix it with the label.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> h (<span class="ocamlkeyword">fun</span> ~x:_ ~y -&gt; y+1);;</div>



<div class="pre caml-output ok">- : int = 3</div></div>

</div>
<!--TOC subsection id="ss:optional-arguments" 4.1.1  Optional arguments-->
<h3 class="subsection" id="ss:optional-arguments"><a class="section-anchor" href="#ss:optional-arguments" aria-hidden="true"></a>4.1.1  Optional arguments</h3><!--SEC END --><p>An interesting feature of labeled arguments is that they can be made
optional. For optional parameters, the question mark <span class="c003">?</span> replaces the
tilde <span class="c003">~</span> of non-optional ones, and the label is also prefixed by <span class="c003">?</span>
in the function type.
Default values may be given for such optional parameters.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> bump ?(step = 1) x = x + step;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> bump : ?step:int -&gt; int -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> bump 2;;</div>



<div class="pre caml-output ok">- : int = 3</div></div>
<div class="ocaml">



<div class="pre caml-input"> bump ~step:3 2;;</div>



<div class="pre caml-output ok">- : int = 5</div></div>

</div><p>A function taking some optional arguments must also take at least one
non-optional argument. The criterion for deciding whether an optional
argument has been omitted is the non-labeled application of an
argument appearing after this optional argument in the function type.
Note that if that argument is labeled, you will only be able to
eliminate optional arguments by totally applying the function,
omitting all optional arguments and omitting all labels for all
remaining arguments.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> test ?(x = 0) ?(y = 0) () ?(z = 0) () = (x, y, z);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> test : ?x:int -&gt; ?y:int -&gt; unit -&gt; ?z:int -&gt; unit -&gt; int * int * int =
  &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> test ();;</div>



<div class="pre caml-output ok">- : ?z:int -&gt; unit -&gt; int * int * int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> test ~x:2 () ~z:3 ();;</div>



<div class="pre caml-output ok">- : int * int * int = (2, 0, 3)</div></div>

</div><p>Optional parameters may also commute with non-optional or unlabeled
ones, as long as they are applied simultaneously. By nature, optional
arguments do not commute with unlabeled arguments applied
independently.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> test ~y:2 ~x:3 () ();;</div>



<div class="pre caml-output ok">- : int * int * int = (3, 2, 0)</div></div>
<div class="ocaml">



<div class="pre caml-input"> test () () ~z:1 ~y:2 ~x:3;;</div>



<div class="pre caml-output ok">- : int * int * int = (3, 2, 1)</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlhighlight">(test () ())</span> ~z:1 ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type int * int * int
       This is not a function; it cannot be applied.</div></div>

</div><p>


Here <span class="c003">(test () ())</span> is already <span class="c003">(0,0,0)</span> and cannot be further
applied.</p><p>Optional arguments are actually implemented as option types. If
you do not give a default value, you have access to their internal
representation, <span class="c003">type 'a option = None | Some of 'a</span>. You can then
provide different behaviors when an argument is present or not.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> bump ?step x =
   <span class="ocamlkeyword">match</span> step <span class="ocamlkeyword">with</span>
   | None -&gt; x * 2
   | Some y -&gt; x + y
 ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> bump : ?step:int -&gt; int -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>It may also be useful to relay an optional argument from a function
call to another. This can be done by prefixing the applied argument
with <span class="c003">?</span>. This question mark disables the wrapping of optional
argument in an option type.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> test2 ?x ?y () = test ?x ?y () ();;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> test2 : ?x:int -&gt; ?y:int -&gt; unit -&gt; int * int * int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> test2 ?x:None;;</div>



<div class="pre caml-output ok">- : ?y:int -&gt; unit -&gt; int * int * int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div>
<!--TOC subsection id="ss:label-inference" 4.1.2  Labels and type inference-->
<h3 class="subsection" id="ss:label-inference"><a class="section-anchor" href="#ss:label-inference" aria-hidden="true"></a>4.1.2  Labels and type inference</h3><!--SEC END --><p>While they provide an increased comfort for writing function
applications, labels and optional arguments have the pitfall that they
cannot be inferred as completely as the rest of the language.</p><p>You can see it in the following two examples.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> h' g = g ~y:2 ~x:3;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> h' : (y:int -&gt; x:int -&gt; 'a) -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> h' <span class="ocamlhighlight">f</span> ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type x:int -&gt; y:int -&gt; int
       but an expression was expected of type y:int -&gt; x:int -&gt; 'a</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> bump_it bump x =
   bump ~step:2 x;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> bump_it : (step:int -&gt; 'a -&gt; 'b) -&gt; 'a -&gt; 'b = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> bump_it <span class="ocamlhighlight">bump</span> 1 ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type ?step:int -&gt; int -&gt; int
       but an expression was expected of type step:int -&gt; 'a -&gt; 'b</div></div>

</div><p>


The first case is simple: <span class="c003">g</span> is passed <span class="c003">~y</span> and then <span class="c003">~x</span>, but <span class="c003">f</span>
expects <span class="c003">~x</span> and then <span class="c003">~y</span>. This is correctly handled if we know the
type of <span class="c003">g</span> to be <span class="c003">x:int -&gt; y:int -&gt; int</span> in advance, but otherwise
this causes the above type clash. The simplest workaround is to apply
formal parameters in a standard order.</p><p>The second example is more subtle: while we intended the argument
<span class="c003">bump</span> to be of type <span class="c003">?step:int -&gt; int -&gt; int</span>, it is inferred as
<span class="c003">step:int -&gt; int -&gt; 'a</span>.
These two types being incompatible (internally normal and optional
arguments are different), a type error occurs when applying <span class="c003">bump_it</span>
to the real <span class="c003">bump</span>.</p><p>We will not try here to explain in detail how type inference works.
One must just understand that there is not enough information in the
above program to deduce the correct type of <span class="c003">g</span> or <span class="c003">bump</span>. That is,
there is no way to know whether an argument is optional or not, or
which is the correct order, by looking only at how a function is
applied. The strategy used by the compiler is to assume that there are
no optional arguments, and that applications are done in the right
order.</p><p>The right way to solve this problem for optional parameters is to add
a type annotation to the argument <span class="c003">bump</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> bump_it (bump : ?step:int -&gt; int -&gt; int) x =
   bump ~step:2 x;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> bump_it : (?step:int -&gt; int -&gt; int) -&gt; int -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> bump_it bump 1;;</div>



<div class="pre caml-output ok">- : int = 3</div></div>

</div><p>


In practice, such problems appear mostly when using objects whose
methods have optional arguments, so that writing the type of object
arguments is often a good idea.</p><p>Normally the compiler generates a type error if you attempt to pass to
a function a parameter whose type is different from the expected one.
However, in the specific case where the expected type is a non-labeled
function type, and the argument is a function expecting optional
parameters, the compiler will attempt to transform the argument to
have it match the expected type, by passing <span class="c003">None</span> for all optional
parameters.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> twice f (x : int) = f(f x);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> twice : (int -&gt; int) -&gt; int -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> twice bump 2;;</div>



<div class="pre caml-output ok">- : int = 8</div></div>

</div><p>This transformation is coherent with the intended semantics,
including side-effects. That is, if the application of optional
parameters shall produce side-effects, these are delayed until the
received function is really applied to an argument.</p>
<!--TOC subsection id="ss:label-suggestions" 4.1.3  Suggestions for labeling-->
<h3 class="subsection" id="ss:label-suggestions"><a class="section-anchor" href="#ss:label-suggestions" aria-hidden="true"></a>4.1.3  Suggestions for labeling</h3><!--SEC END --><p>Like for names, choosing labels for functions is not an easy task. A
good labeling is a labeling which</p><ul class="itemize"><li class="li-itemize">
makes programs more readable,
</li><li class="li-itemize">is easy to remember,
</li><li class="li-itemize">when possible, allows useful partial applications.
</li></ul><p>We explain here the rules we applied when labeling OCaml
libraries.</p><p>To speak in an “object-oriented” way, one can consider that each
function has a main argument, its <em>object</em>, and other arguments
related with its action, the <em>parameters</em>. To permit the
combination of functions through functionals in commuting label mode, the
object will not be labeled. Its role is clear from the function
itself. The parameters are labeled with names reminding of
their nature or their role. The best labels combine nature and
role. When this is not possible the role is to be preferred, since the
nature will
often be given by the type itself. Obscure abbreviations should be
avoided.
</p><pre>
<span class="c003">ListLabels.map : f:('a -&gt; 'b) -&gt; 'a list -&gt; 'b list</span>
UnixLabels.write : file_descr -&gt; buf:bytes -&gt; pos:int -&gt; len:int -&gt; unit
</pre><p>When there are several objects of same nature and role, they are all
left unlabeled.
</p><pre>
<span class="c003">ListLabels.iter2 : f:('a -&gt; 'b -&gt; 'c) -&gt; 'a list -&gt; 'b list -&gt; unit</span>
</pre><p>When there is no preferable object, all arguments are labeled.
</p><pre>
BytesLabels.blit :
  src:bytes -&gt; src_pos:int -&gt; dst:bytes -&gt; dst_pos:int -&gt; len:int -&gt; unit
</pre><p>However, when there is only one argument, it is often left unlabeled.
</p><pre>
BytesLabels.create : int -&gt; bytes
</pre><p>
This principle also applies to functions of several arguments whose
return type is a type variable, as long as the role of each argument
is not ambiguous. Labeling such functions may lead to awkward error
messages when one attempts to omit labels in an application, as we
have seen with <span class="c003">ListLabels.fold_left</span>.</p><p>Here are some of the label names you will find throughout the
libraries.</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Label</span></td><td class="c014"><span class="c013">Meaning</span> </td></tr>
<tr><td class="c016">
<span class="c003">f:</span></td><td class="c016">a function to be applied </td></tr>
<tr><td class="c016"><span class="c003">pos:</span></td><td class="c016">a position in a string, array or byte sequence </td></tr>
<tr><td class="c016"><span class="c003">len:</span></td><td class="c016">a length </td></tr>
<tr><td class="c016"><span class="c003">buf:</span></td><td class="c016">a byte sequence or string used as buffer </td></tr>
<tr><td class="c016"><span class="c003">src:</span></td><td class="c016">the source of an operation </td></tr>
<tr><td class="c016"><span class="c003">dst:</span></td><td class="c016">the destination of an operation </td></tr>
<tr><td class="c016"><span class="c003">init:</span></td><td class="c016">the initial value for an iterator </td></tr>
<tr><td class="c016"><span class="c003">cmp:</span></td><td class="c016">a comparison function, <span class="c009">e.g.</span> <span class="c003">Stdlib.compare</span> </td></tr>
<tr><td class="c016"><span class="c003">mode:</span></td><td class="c016">an operation mode or a flag list </td></tr>
</table></div></div><p>All these are only suggestions, but keep in mind that the
choice of labels is essential for readability. Bizarre choices will
make the program harder to maintain.</p><p>In the ideal, the right function name with right labels should be
enough to understand the function’s meaning. Since one can get this
information with OCamlBrowser or the <span class="c003">ocaml</span> toplevel, the documentation
is only used when a more detailed specification is needed.</p>
<!--TOC section id="s:polymorphic-variants" 4.2  Polymorphic variants-->
<h2 class="section" id="s:polymorphic-variants"><a class="section-anchor" href="#s:polymorphic-variants" aria-hidden="true"></a>4.2  Polymorphic variants</h2><!--SEC END --><p>Variants as presented in section <a href="#s%3Atut-recvariants">1.4</a> are a
powerful tool to build data structures and algorithms. However they
sometimes lack flexibility when used in modular programming. This is
due to the fact that every constructor is assigned to a unique type
when defined and used. Even if the same name appears in the definition
of multiple types, the constructor itself belongs to only one type.
Therefore, one cannot decide that a given constructor belongs to
multiple types, or consider a value of some type to belong to some
other type with more constructors.</p><p>With polymorphic variants, this original assumption is removed. That
is, a variant tag does not belong to any type in particular, the type
system will just check that it is an admissible value according to its
use. You need not define a type before using a variant tag. A variant
type will be inferred independently for each of its uses.</p><!--TOC subsection id="ss:polyvariant:basic-use" Basic use-->
<h3 class="subsection" id="ss:polyvariant:basic-use"><a class="section-anchor" href="#ss:polyvariant:basic-use" aria-hidden="true"></a>Basic use</h3><!--SEC END --><p>In programs, polymorphic variants work like usual ones. You just have
to prefix their names with a backquote character <span class="c003">`</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> [`On; `Off];;</div>



<div class="pre caml-output ok">- : [&gt; `Off | `On ] list = [`On; `Off]</div></div>
<div class="ocaml">



<div class="pre caml-input"> `Number 1;;</div>



<div class="pre caml-output ok">- : [&gt; `Number <span class="ocamlkeyword">of</span> int ] = `Number 1</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f = <span class="ocamlkeyword">function</span> `On -&gt; 1 | `Off -&gt; 0 | `Number n -&gt; n;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f : [&lt; `Number <span class="ocamlkeyword">of</span> int | `Off | `On ] -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> List.map f [`On; `Off];;</div>



<div class="pre caml-output ok">- : int list = [1; 0]</div></div>

</div><p>


<span class="c003">[&gt;`Off|`On] list</span> means that to match this list, you should at
least be able to match <span class="c003">`Off</span> and <span class="c003">`On</span>, without argument.
<span class="c003">[&lt;`On|`Off|`Number of int]</span> means that <span class="c003">f</span> may be applied to <span class="c003">`Off</span>,
<span class="c003">`On</span> (both without argument), or <span class="c003">`Number</span> <span class="c009">n</span> where
<span class="c009">n</span> is an integer.
The <span class="c003">&gt;</span> and <span class="c003">&lt;</span> inside the variant types show that they may still be
refined, either by defining more tags or by allowing less. As such, they
contain an implicit type variable. Because each of the variant types
appears only once in the whole type, their implicit type variables are
not shown.</p><p>The above variant types were polymorphic, allowing further refinement.
When writing type annotations, one will most often describe fixed
variant types, that is types that cannot be refined. This is
also the case for type abbreviations. Such types do not contain <span class="c003">&lt;</span> or
<span class="c003">&gt;</span>, but just an enumeration of the tags and their associated types,
just like in a normal datatype definition.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> 'a vlist = [`Nil | `Cons <span class="ocamlkeyword">of</span> 'a * 'a vlist];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> 'a vlist = [ `Cons <span class="ocamlkeyword">of</span> 'a * 'a vlist | `Nil ]</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> map f : 'a vlist -&gt; 'b vlist = <span class="ocamlkeyword">function</span>
   | `Nil -&gt; `Nil
   | `Cons(a, l) -&gt; `Cons(f a, map f l)
 ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> map : ('a -&gt; 'b) -&gt; 'a vlist -&gt; 'b vlist = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><!--TOC subsection id="ss:polyvariant-advanced" Advanced use-->
<h3 class="subsection" id="ss:polyvariant-advanced"><a class="section-anchor" href="#ss:polyvariant-advanced" aria-hidden="true"></a>Advanced use</h3><!--SEC END --><p>Type-checking polymorphic variants is a subtle thing, and some
expressions may result in more complex type information.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f = <span class="ocamlkeyword">function</span> `A -&gt; `C | `B -&gt; `D | x -&gt; x;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f : ([&gt; `A | `B | `C | `D ] <span class="ocamlkeyword">as</span> 'a) -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> f `E;;</div>



<div class="pre caml-output ok">- : [&gt; `A | `B | `C | `D | `E ] = `E</div></div>

</div><p>


Here we are seeing two phenomena. First, since this matching is open
(the last case catches any tag), we obtain the type <span class="c003">[&gt; `A | `B]</span>
rather than <span class="c003">[&lt; `A | `B]</span> in a closed matching. Then, since <span class="c003">x</span> is
returned as is, input and return types are identical. The notation <span class="c003">as 'a</span> denotes such type sharing. If we apply <span class="c003">f</span> to yet another tag
<span class="c003">`E</span>, it gets added to the list.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f1 = <span class="ocamlkeyword">function</span> `A x -&gt; x = 1 | `B -&gt; <span class="ocamlkeyword">true</span> | `C -&gt; <span class="ocamlkeyword">false</span>
 <span class="ocamlkeyword">let</span> f2 = <span class="ocamlkeyword">function</span> `A x -&gt; x = <span class="ocamlstring">"a"</span> | `B -&gt; <span class="ocamlkeyword">true</span> ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f1 : [&lt; `A <span class="ocamlkeyword">of</span> int | `B | `C ] -&gt; bool = &lt;<span class="ocamlkeyword">fun</span>&gt;
<span class="ocamlkeyword">val</span> f2 : [&lt; `A <span class="ocamlkeyword">of</span> string | `B ] -&gt; bool = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f x = f1 x &amp;&amp; f2 x;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f : [&lt; `A <span class="ocamlkeyword">of</span> string &amp; int | `B ] -&gt; bool = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


Here <span class="c003">f1</span> and <span class="c003">f2</span> both accept the variant tags <span class="c003">`A</span> and <span class="c003">`B</span>, but the
argument of <span class="c003">`A</span> is <span class="c003">int</span> for <span class="c003">f1</span> and <span class="c003">string</span> for <span class="c003">f2</span>. In <span class="c003">f</span>’s
type <span class="c003">`C</span>, only accepted by <span class="c003">f1</span>, disappears, but both argument types
appear for <span class="c003">`A</span> as <span class="c003">int &amp; string</span>. This means that if we
pass the variant tag <span class="c003">`A</span> to <span class="c003">f</span>, its argument should be <em>both</em>
<span class="c003">int</span> and <span class="c003">string</span>. Since there is no such value, <span class="c003">f</span> cannot be
applied to <span class="c003">`A</span>, and <span class="c003">`B</span> is the only accepted input.</p><p>Even if a value has a fixed variant type, one can still give it a
larger type through coercions. Coercions are normally written with
both the source type and the destination type, but in simple cases the
source type may be omitted.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> 'a wlist = [`Nil | `Cons <span class="ocamlkeyword">of</span> 'a * 'a wlist | `Snoc <span class="ocamlkeyword">of</span> 'a wlist * 'a];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> 'a wlist = [ `Cons <span class="ocamlkeyword">of</span> 'a * 'a wlist | `Nil | `Snoc <span class="ocamlkeyword">of</span> 'a wlist * 'a ]</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> wlist_of_vlist  l = (l : 'a vlist :&gt; 'a wlist);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> wlist_of_vlist : 'a vlist -&gt; 'a wlist = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> open_vlist l = (l : 'a vlist :&gt; [&gt; 'a vlist]);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> open_vlist : 'a vlist -&gt; [&gt; 'a vlist ] = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">fun</span> x -&gt; (x :&gt; [`A|`B|`C]);;</div>



<div class="pre caml-output ok">- : [&lt; `A | `B | `C ] -&gt; [ `A | `B | `C ] = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>You may also selectively coerce values through pattern matching.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> split_cases = <span class="ocamlkeyword">function</span>
   | `Nil | `Cons _ <span class="ocamlkeyword">as</span> x -&gt; `A x
   | `Snoc _ <span class="ocamlkeyword">as</span> x -&gt; `B x
 ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> split_cases :
  [&lt; `Cons <span class="ocamlkeyword">of</span> 'a | `Nil | `Snoc <span class="ocamlkeyword">of</span> 'b ] -&gt;
  [&gt; `A <span class="ocamlkeyword">of</span> [&gt; `Cons <span class="ocamlkeyword">of</span> 'a | `Nil ] | `B <span class="ocamlkeyword">of</span> [&gt; `Snoc <span class="ocamlkeyword">of</span> 'b ] ] = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


When an or-pattern composed of variant tags is wrapped inside an
alias-pattern, the alias is given a type containing only the tags
enumerated in the or-pattern. This allows for many useful idioms, like
incremental definition of functions.</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> num x = `Num x
 <span class="ocamlkeyword">let</span> eval1 eval (`Num x) = x
 <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> eval x = eval1 eval x ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> num : 'a -&gt; [&gt; `Num <span class="ocamlkeyword">of</span> 'a ] = &lt;<span class="ocamlkeyword">fun</span>&gt;
<span class="ocamlkeyword">val</span> eval1 : 'a -&gt; [&lt; `Num <span class="ocamlkeyword">of</span> 'b ] -&gt; 'b = &lt;<span class="ocamlkeyword">fun</span>&gt;
<span class="ocamlkeyword">val</span> eval : [&lt; `Num <span class="ocamlkeyword">of</span> 'a ] -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> plus x y = `Plus(x,y)
 <span class="ocamlkeyword">let</span> eval2 eval = <span class="ocamlkeyword">function</span>
   | `Plus(x,y) -&gt; eval x + eval y
   | `Num _ <span class="ocamlkeyword">as</span> x -&gt; eval1 eval x
 <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> eval x = eval2 eval x ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> plus : 'a -&gt; 'b -&gt; [&gt; `Plus <span class="ocamlkeyword">of</span> 'a * 'b ] = &lt;<span class="ocamlkeyword">fun</span>&gt;
<span class="ocamlkeyword">val</span> eval2 : ('a -&gt; int) -&gt; [&lt; `Num <span class="ocamlkeyword">of</span> int | `Plus <span class="ocamlkeyword">of</span> 'a * 'a ] -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;
<span class="ocamlkeyword">val</span> eval : ([&lt; `Num <span class="ocamlkeyword">of</span> int | `Plus <span class="ocamlkeyword">of</span> 'a * 'a ] <span class="ocamlkeyword">as</span> 'a) -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>To make this even more comfortable, you may use type definitions as
abbreviations for or-patterns. That is, if you have defined <span class="c003">type myvariant = [`Tag1 of int | `Tag2 of bool]</span>, then the pattern <span class="c003">#myvariant</span> is
equivalent to writing <span class="c003">(`Tag1(_ : int) | `Tag2(_ : bool))</span>.</p><p>Such abbreviations may be used alone,


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f = <span class="ocamlkeyword">function</span>
   | #myvariant -&gt; <span class="ocamlstring">"myvariant"</span>
   | `Tag3 -&gt; <span class="ocamlstring">"Tag3"</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f : [&lt; `Tag1 <span class="ocamlkeyword">of</span> int | `Tag2 <span class="ocamlkeyword">of</span> bool | `Tag3 ] -&gt; string = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


or combined with with aliases.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> g1 = <span class="ocamlkeyword">function</span> `Tag1 _ -&gt; <span class="ocamlstring">"Tag1"</span> | `Tag2 _ -&gt; <span class="ocamlstring">"Tag2"</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> g1 : [&lt; `Tag1 <span class="ocamlkeyword">of</span> 'a | `Tag2 <span class="ocamlkeyword">of</span> 'b ] -&gt; string = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> g = <span class="ocamlkeyword">function</span>
   | #myvariant <span class="ocamlkeyword">as</span> x -&gt; g1 x
   | `Tag3 -&gt; <span class="ocamlstring">"Tag3"</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> g : [&lt; `Tag1 <span class="ocamlkeyword">of</span> int | `Tag2 <span class="ocamlkeyword">of</span> bool | `Tag3 ] -&gt; string = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div>
<!--TOC subsection id="ss:polyvariant-weaknesses" 4.2.1  Weaknesses of polymorphic variants-->
<h3 class="subsection" id="ss:polyvariant-weaknesses"><a class="section-anchor" href="#ss:polyvariant-weaknesses" aria-hidden="true"></a>4.2.1  Weaknesses of polymorphic variants</h3><!--SEC END --><p>After seeing the power of polymorphic variants, one may wonder why
they were added to core language variants, rather than replacing them.</p><p>The answer is twofold. One first aspect is that while being pretty
efficient, the lack of static type information allows for less
optimizations, and makes polymorphic variants slightly heavier than
core language ones. However noticeable differences would only
appear on huge data structures.</p><p>More important is the fact that polymorphic variants, while being
type-safe, result in a weaker type discipline. That is, core language
variants do actually much more than ensuring type-safety, they also
check that you use only declared constructors, that all constructors
present in a data-structure are compatible, and they enforce typing
constraints to their parameters.</p><p>For this reason, you must be more careful about making types explicit
when you use polymorphic variants. When you write a library, this is
easy since you can describe exact types in interfaces, but for simple
programs you are probably better off with core language variants.</p><p>Beware also that some idioms make trivial errors very hard to find.
For instance, the following code is probably wrong but the compiler
has no way to see it.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> abc = [`A | `B | `C] ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> abc = [ `A | `B | `C ]</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f = <span class="ocamlkeyword">function</span>
   | `As -&gt; <span class="ocamlstring">"A"</span>
   | #abc -&gt; <span class="ocamlstring">"other"</span> ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f : [&lt; `A | `As | `B | `C ] -&gt; string = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f : abc -&gt; string = f ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f : abc -&gt; string = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


You can avoid such risks by annotating the definition itself.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f : abc -&gt; string = <span class="ocamlkeyword">function</span>
   | <span class="ocamlhighlight">`As</span> -&gt; <span class="ocamlstring">"A"</span>
   | #abc -&gt; <span class="ocamlstring">"other"</span> ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This pattern matches values of type [? `As ]
       but a pattern was expected which matches values of type abc
       The second variant type does not allow tag(s) `As</div></div>

</div>
<!--BEGIN NOTES chapter-->
<hr class="footnoterule"><dl class="thefootnotes"><dt class="dt-thefootnotes">
<a id="note1" href="#text1">1</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">This correspond to the commuting label mode
of Objective Caml 3.00 through 3.02, with some additional flexibility
on total applications. The so-called classic mode (<span class="c003">-nolabels</span>
options) is now deprecated for normal use.</div></dd></dl>
<!--END NOTES-->
<!--TOC chapter id="sec53" Chapter 5  Polymorphism and its limitations-->
<h1 class="chapter" id="sec53">Chapter 5  Polymorphism and its limitations</h1><!--SEC END --><p><a id="c:polymorphism"></a>
</p><!--NAME polymorphism.html-->
<p><br>
<br>
</p><p>This chapter covers more advanced questions related to the
limitations of polymorphic functions and types. There are some situations
in OCaml where the type inferred by the type checker may be less generic
than expected. Such non-genericity can stem either from interactions
between side-effect and typing or the difficulties of implicit polymorphic
recursion and higher-rank polymorphism.</p><p>This chapter details each of these situations and, if it is possible,
how to recover genericity.</p>
<!--TOC section id="s:weak-polymorphism" 5.1  Weak polymorphism and mutation-->
<h2 class="section" id="s:weak-polymorphism"><a class="section-anchor" href="#s:weak-polymorphism" aria-hidden="true"></a>5.1  Weak polymorphism and mutation</h2><!--SEC END -->
<!--TOC subsection id="ss:weak-types" 5.1.1  Weakly polymorphic types-->
<h3 class="subsection" id="ss:weak-types"><a class="section-anchor" href="#ss:weak-types" aria-hidden="true"></a>5.1.1  Weakly polymorphic types</h3><!--SEC END --><p>
Maybe the most frequent examples of non-genericity derive from the
interactions between polymorphic types and mutation. A simple example
appears when typing the following expression


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> store = <span class="ocamlkeyword">ref</span> None ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> store : '_weak1 option <span class="ocamlkeyword">ref</span> = {contents = None}</div></div>

</div><p>


Since the type of <span class="c003">None</span> is <span class="c003">'a option</span> and the function <span class="c003">ref</span> has type
<span class="c003">'b -&gt; 'b ref</span>, a natural deduction for the type of <span class="c003">store</span> would be
<span class="c003">'a option ref</span>. However, the inferred type, <span class="c003">'_weak1 option ref</span>, is
different. Type variables whose name starts with a <span class="c003">_weak</span> prefix like
<span class="c003">'_weak1</span> are weakly polymorphic type variables, sometimes shortened as
weak type variables.
A weak type variable is a placeholder for a single type that is currently
unknown. Once the specific type <span class="c003">t</span> behind the placeholder type <span class="c003">'_weak1</span>
is known, all occurrences of <span class="c003">'_weak1</span> will be replaced by <span class="c003">t</span>. For instance,
we can define another option reference and store an <span class="c003">int</span> inside:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> another_store = <span class="ocamlkeyword">ref</span> None ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> another_store : '_weak2 option <span class="ocamlkeyword">ref</span> = {contents = None}</div></div>
<div class="ocaml">



<div class="pre caml-input"> another_store := Some 0;
 another_store ;;</div>



<div class="pre caml-output ok">- : int option <span class="ocamlkeyword">ref</span> = {contents = Some 0}</div></div>

</div><p>


After storing an <span class="c003">int</span> inside <span class="c003">another_store</span>, the type of <span class="c003">another_store</span> has
been updated from <span class="c003">'_weak2 option ref</span> to <span class="c003">int option ref</span>.
This distinction between weakly and generic polymorphic type variable protects
OCaml programs from unsoundness and runtime errors. To understand from where
unsoundness might come, consider this simple function which swaps a value <span class="c003">x</span>
with the value stored inside a <span class="c003">store</span> reference, if there is such value:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> swap store x = <span class="ocamlkeyword">match</span> !store <span class="ocamlkeyword">with</span>
   | None -&gt; store := Some x; x
   | Some y -&gt; store := Some x; y;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> swap : 'a option <span class="ocamlkeyword">ref</span> -&gt; 'a -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


We can apply this function to our store


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> one = swap store 1
 <span class="ocamlkeyword">let</span> one_again = swap store 2
 <span class="ocamlkeyword">let</span> two = swap store 3;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> one : int = 1
<span class="ocamlkeyword">val</span> one_again : int = 1
<span class="ocamlkeyword">val</span> two : int = 2</div></div>

</div><p>


After these three swaps the stored value is <span class="c003">3</span>. Everything is fine up to
now. We can then try to swap <span class="c003">3</span> with a more interesting value, for
instance a function:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> error = swap store <span class="ocamlhighlight">(fun x -&gt; x)</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression should not be a function, the expected type is int</div></div>

</div><p>


At this point, the type checker rightfully complains that it is not
possible to swap an integer and a function, and that an <span class="c003">int</span> should always
be traded for another <span class="c003">int</span>. Furthermore, the type checker prevents us to
change manually the type of the value stored by <span class="c003">store</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> store := Some <span class="ocamlhighlight">(fun x -&gt; x)</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression should not be a function, the expected type is int</div></div>

</div><p>


Indeed, looking at the type of store, we see that the weak type <span class="c003">'_weak1</span> has
been replaced by the type <span class="c003">int</span>


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> store;;</div>



<div class="pre caml-output ok">- : int option <span class="ocamlkeyword">ref</span> = {contents = Some 3}</div></div>

</div><p>


Therefore, after placing an <span class="c003">int</span> in <span class="c003">store</span>, we cannot use it to store any
value other than an <span class="c003">int</span>. More generally, weak types protect the program from
undue mutation of values with a polymorphic type.</p><p>Moreover, weak types cannot appear in the signature of toplevel modules:
types must be known at compilation time. Otherwise, different compilation
units could replace the weak type with different and incompatible types.
For this reason, compiling the following small piece of code
</p><pre>let option_ref = ref None
</pre><p>yields a compilation error
</p><pre>Error: The type of this expression, '_weak1 option ref,
       contains type variables that cannot be generalized
</pre><p>To solve this error, it is enough to add an explicit type annotation to
specify the type at declaration time:
</p><pre>let option_ref: int option ref = ref None
</pre><p>This is in any case a good practice for such global mutable variables.
Otherwise, they will pick out the type of first use. If there is a mistake
at this point, this can result in confusing type errors when later, correct
uses are flagged as errors.</p>
<!--TOC subsection id="ss:valuerestriction" 5.1.2  The value restriction-->
<h3 class="subsection" id="ss:valuerestriction"><a class="section-anchor" href="#ss:valuerestriction" aria-hidden="true"></a>5.1.2  The value restriction</h3><!--SEC END --><p>Identifying the exact context in which polymorphic types should be
replaced by weak types in a modular way is a difficult question. Indeed
the type system must handle the possibility that functions may hide persistent
mutable states. For instance, the following function uses an internal reference
to implement a delayed identity function


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> make_fake_id () =
   <span class="ocamlkeyword">let</span> store = <span class="ocamlkeyword">ref</span> None <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">fun</span> x -&gt; swap store x ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> make_fake_id : unit -&gt; 'a -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> fake_id = make_fake_id();;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> fake_id : '_weak3 -&gt; '_weak3 = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


It would be unsound to apply this <span class="c003">fake_id</span> function to values with different
types. The function <span class="c003">fake_id</span> is therefore rightfully assigned the type
<span class="c003">'_weak3 -&gt; '_weak3</span> rather than <span class="c003">'a -&gt; 'a</span>. At the same time, it ought to
be possible to use a local mutable state without impacting the type of a
function.
</p><p>To circumvent these dual difficulties, the type checker considers that any value
returned by a function might rely on persistent mutable states behind the scene
and should be given a weak type. This restriction on the type of mutable
values and the results of function application is called the value restriction.
Note that this value restriction is conservative: there are situations where the
value restriction is too cautious and gives a weak type to a value that could be
safely generalized to a polymorphic type:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> not_id = (<span class="ocamlkeyword">fun</span> x -&gt; x) (<span class="ocamlkeyword">fun</span> x -&gt; x);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> not_id : '_weak4 -&gt; '_weak4 = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


Quite often, this happens when defining function using higher order function.
To avoid this problem, a solution is to add an explicit argument to the
function:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> id_again = <span class="ocamlkeyword">fun</span> x -&gt; (<span class="ocamlkeyword">fun</span> x -&gt; x) (<span class="ocamlkeyword">fun</span> x -&gt; x) x;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> id_again : 'a -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


With this argument, <span class="c003">id_again</span> is seen as a function definition by the type
checker and can therefore be generalized. This kind of manipulation is called
eta-expansion in lambda calculus and is sometimes referred under this name.</p>
<!--TOC subsection id="ss:relaxed-value-restriction" 5.1.3  The relaxed value restriction-->
<h3 class="subsection" id="ss:relaxed-value-restriction"><a class="section-anchor" href="#ss:relaxed-value-restriction" aria-hidden="true"></a>5.1.3  The relaxed value restriction</h3><!--SEC END --><p>There is another partial solution to the problem of unnecessary weak type,
which is implemented directly within the type checker. Briefly, it is possible
to prove that weak types that only appear as type parameters in covariant
positions –also called positive positions– can be safely generalized to
polymorphic types. For instance, the type <span class="c003">'a list</span> is covariant in <span class="c003">'a</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> f () = [];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f : unit -&gt; 'a list = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> empty = f ();;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> empty : 'a list = []</div></div>

</div><p>


Remark that the type inferred for <span class="c003">empty</span> is <span class="c003">'a list</span> and not <span class="c003">'_weak5 list</span>
that should have occurred with the value restriction since <span class="c003">f ()</span> is a
function application.</p><p>The value restriction combined with this generalization for covariant type
parameters is called the relaxed value restriction.</p>
<!--TOC subsection id="ss:variance-and-value-restriction" 5.1.4  Variance and value restriction-->
<h3 class="subsection" id="ss:variance-and-value-restriction"><a class="section-anchor" href="#ss:variance-and-value-restriction" aria-hidden="true"></a>5.1.4  Variance and value restriction</h3><!--SEC END --><p>
Variance describes how type constructors behave with respect to subtyping.
Consider for instance a pair of type <span class="c003">x</span> and <span class="c003">xy</span> with <span class="c003">x</span> a subtype of <span class="c003">xy</span>,
denoted <span class="c003">x :&gt; xy</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">type</span> x = [ `X ];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> x = [ `X ]</div></div>
<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">type</span> xy = [ `X | `Y ];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> xy = [ `X | `Y ]</div></div>

</div><p>


As <span class="c003">x</span> is a subtype of <span class="c003">xy</span>, we can convert a value of type <span class="c003">x</span>
to a value of type <span class="c003">xy</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> x:x = `X;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> x : x = `X</div></div>
<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> x' = ( x :&gt; xy);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> x' : xy = `X</div></div>

</div><p>


Similarly, if we have a value of type <span class="c003">x list</span>, we can convert it to a value
of type <span class="c003">xy list</span>, since we could convert each element one by one:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> l:x list = [`X; `X];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> l : x list = [`X; `X]</div></div>
<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> l' = ( l :&gt; xy list);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> l' : xy list = [`X; `X]</div></div>

</div><p>


In other words, <span class="c003">x :&gt; xy</span> implies that <span class="c003">x list :&gt; xy list</span>, therefore
the type constructor <span class="c003">'a list</span> is covariant (it preserves subtyping)
in its parameter <span class="c003">'a</span>.</p><p>Contrarily, if we have a function that can handle values of type <span class="c003">xy</span>


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> f: xy -&gt; unit = <span class="ocamlkeyword">function</span>
   | `X -&gt; ()
   | `Y -&gt; ();;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f : xy -&gt; unit = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


it can also handle values of type <span class="c003">x</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> f' = (f :&gt; x -&gt; unit);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> f' : x -&gt; unit = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


Note that we can rewrite the type of <span class="c003">f</span> and <span class="c003">f'</span> as


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">type</span> 'a proc = 'a -&gt; unit
   <span class="ocamlkeyword">let</span> f' = (f: xy proc :&gt; x proc);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> 'a proc = 'a -&gt; unit
<span class="ocamlkeyword">val</span> f' : x proc = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


In this case, we have <span class="c003">x :&gt; xy</span> implies <span class="c003">xy proc :&gt; x proc</span>. Notice
that the second subtyping relation reverse the order of <span class="c003">x</span> and <span class="c003">xy</span>:
the type constructor <span class="c003">'a proc</span> is contravariant in its parameter <span class="c003">'a</span>.
More generally, the function type constructor <span class="c003">'a -&gt; 'b</span> is covariant in
its return type <span class="c003">'b</span> and contravariant in its argument type <span class="c003">'a</span>.</p><p>A type constructor can also be invariant in some of its type parameters,
neither covariant nor contravariant. A typical example is a reference:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> x: x <span class="ocamlkeyword">ref</span> = <span class="ocamlkeyword">ref</span> `X;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> x : x <span class="ocamlkeyword">ref</span> = {contents = `X}</div></div>

</div><p>


If we were able to coerce <span class="c003">x</span> to the type <span class="c003">xy ref</span> as a variable <span class="c003">xy</span>,
we could use <span class="c003">xy</span> to store the value <span class="c003">`Y</span> inside the reference and then use
the <span class="c003">x</span> value to read this content as a value of type <span class="c003">x</span>,
which would break the type system.</p><p>More generally, as soon as a type variable appears in a position describing
mutable state it becomes invariant. As a corollary, covariant variables will
never denote mutable locations and can be safely generalized.
For a better description, interested readers can consult the original
article by Jacques Garrigue on
<a href="http://www.math.nagoya-u.ac.jp/~garrigue/papers/morepoly-long.pdf"><span class="c003">http://www.math.nagoya-u.ac.jp/~garrigue/papers/morepoly-long.pdf</span></a></p><p>Together, the relaxed value restriction and type parameter covariance
help to avoid eta-expansion in many situations.</p>
<!--TOC subsection id="ss:variance:abstract-data-types" 5.1.5  Abstract data types-->
<h3 class="subsection" id="ss:variance:abstract-data-types"><a class="section-anchor" href="#ss:variance:abstract-data-types" aria-hidden="true"></a>5.1.5  Abstract data types</h3><!--SEC END --><p>
Moreover, when the type definitions are exposed, the type checker
is able to infer variance information on its own and one can benefit from
the relaxed value restriction even unknowingly. However, this is not the case
anymore when defining new abstract types. As an illustration, we can define a
module type collection as:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> COLLECTION = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> 'a t
   <span class="ocamlkeyword">val</span> empty: unit -&gt; 'a t
 <span class="ocamlkeyword">end</span>

 <span class="ocamlkeyword">module</span> Implementation = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">type</span> 'a t = 'a list
   <span class="ocamlkeyword">let</span> empty ()= []
 <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> COLLECTION = <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> 'a t <span class="ocamlkeyword">val</span> empty : unit -&gt; 'a t <span class="ocamlkeyword">end</span>
<span class="ocamlkeyword">module</span> Implementation :
  <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> 'a t = 'a list <span class="ocamlkeyword">val</span> empty : unit -&gt; 'a list <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> List2: COLLECTION = Implementation;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> List2 : COLLECTION</div></div>

</div><p>In this situation, when coercing the module <span class="c003">List2</span> to the module type
<span class="c003">COLLECTION</span>, the type checker forgets that <span class="c003">'a List2.t</span> was covariant
in <span class="c003">'a</span>. Consequently, the relaxed value restriction does not apply anymore:</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   List2.empty ();;</div>



<div class="pre caml-output ok">- : '_weak5 List2.t = &lt;abstr&gt;</div></div>

</div><p>To keep the relaxed value restriction, we need to declare the abstract type
<span class="c003">'a COLLECTION.t</span> as covariant in <span class="c003">'a</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> COLLECTION = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> +'a t
   <span class="ocamlkeyword">val</span> empty: unit -&gt; 'a t
 <span class="ocamlkeyword">end</span>

 <span class="ocamlkeyword">module</span> List2: COLLECTION = Implementation;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> COLLECTION = <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> +'a t <span class="ocamlkeyword">val</span> empty : unit -&gt; 'a t <span class="ocamlkeyword">end</span>
<span class="ocamlkeyword">module</span> List2 : COLLECTION</div></div>

</div><p>We then recover polymorphism:</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   List2.empty ();;</div>



<div class="pre caml-output ok">- : 'a List2.t = &lt;abstr&gt;</div></div>

</div>
<!--TOC section id="s:polymorphic-recursion" 5.2  Polymorphic recursion-->
<h2 class="section" id="s:polymorphic-recursion"><a class="section-anchor" href="#s:polymorphic-recursion" aria-hidden="true"></a>5.2  Polymorphic recursion</h2><!--SEC END --><p>The second major class of non-genericity is directly related to the problem
of type inference for polymorphic functions. In some circumstances, the type
inferred by OCaml might be not general enough to allow the definition of
some recursive functions, in particular for recursive function acting on
non-regular algebraic data type.</p><p>With a regular polymorphic algebraic data type, the type parameters of
the type constructor are constant within the definition of the type. For
instance, we can look at arbitrarily nested list defined as:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">type</span> 'a regular_nested = List <span class="ocamlkeyword">of</span> 'a list | Nested <span class="ocamlkeyword">of</span> 'a regular_nested list
   <span class="ocamlkeyword">let</span> l = Nested[ List [1]; Nested [List[2;3]]; Nested[Nested[]] ];;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> 'a regular_nested = List <span class="ocamlkeyword">of</span> 'a list | Nested <span class="ocamlkeyword">of</span> 'a regular_nested list
<span class="ocamlkeyword">val</span> l : int regular_nested =
  Nested [List [1]; Nested [List [2; 3]]; Nested [Nested []]]</div></div>

</div><p>


Note that the type constructor <span class="c003">regular_nested</span> always appears as
<span class="c003">'a regular_nested</span> in the definition above, with the same parameter
<span class="c003">'a</span>. Equipped with this type, one can compute a maximal depth with
a classic recursive function


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> maximal_depth = <span class="ocamlkeyword">function</span>
   | List _ -&gt; 1
   | Nested [] -&gt; 0
   | Nested (a::q) -&gt; 1 + max (maximal_depth a) (maximal_depth (Nested q));;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> maximal_depth : 'a regular_nested -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>Non-regular recursive algebraic data types correspond to polymorphic algebraic
data types whose parameter types vary between the left and right side of
the type definition. For instance, it might be interesting to define a datatype
that ensures that all lists are nested at the same depth:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">type</span> 'a nested = List <span class="ocamlkeyword">of</span> 'a list | Nested <span class="ocamlkeyword">of</span> 'a list nested;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> 'a nested = List <span class="ocamlkeyword">of</span> 'a list | Nested <span class="ocamlkeyword">of</span> 'a list nested</div></div>

</div><p>


Intuitively, a value of type <span class="c003">'a nested</span> is a list of list …of list of
elements <span class="c003">a</span> with <span class="c003">k</span> nested list. We can then adapt the <span class="c003">maximal_depth</span>
function defined on <span class="c003">regular_depth</span> into a <span class="c003">depth</span> function that computes this
<span class="c003">k</span>. As a first try, we may define


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> depth = <span class="ocamlkeyword">function</span>
   | List _ -&gt; 1
   | Nested n -&gt; 1 + depth <span class="ocamlhighlight">n</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type 'a list nested
       but an expression was expected of type 'a nested
       The type variable 'a occurs inside 'a list</div></div>

</div><p>


The type error here comes from the fact that during the definition of <span class="c003">depth</span>,
the type checker first assigns to <span class="c003">depth</span> the type <span class="c003">'a -&gt; 'b </span>.
When typing the pattern matching, <span class="c003">'a -&gt; 'b</span> becomes <span class="c003">'a nested -&gt; 'b</span>, then
<span class="c003">'a nested -&gt; int</span> once the <span class="c003">List</span> branch is typed.
However, when typing the application <span class="c003">depth n</span> in the <span class="c003">Nested</span> branch,
the type checker encounters a problem: <span class="c003">depth n</span> is applied to
<span class="c003">'a list nested</span>, it must therefore have the type
<span class="c003">'a list nested -&gt; 'b</span>. Unifying this constraint with the previous one
leads to the impossible constraint <span class="c003">'a list nested = 'a nested</span>.
In other words, within its definition, the recursive function <span class="c003">depth</span> is
applied to values of type <span class="c003">'a t</span> with different types <span class="c003">'a</span> due to the
non-regularity of the type constructor <span class="c003">nested</span>. This creates a problem because
the type checker had introduced a new type variable <span class="c003">'a</span> only at the
<em>definition</em> of the function <span class="c003">depth</span> whereas, here, we need a
different type variable for every <em>application</em> of the function <span class="c003">depth</span>.</p>
<!--TOC subsection id="ss:explicit-polymorphism" 5.2.1  Explicitly polymorphic annotations-->
<h3 class="subsection" id="ss:explicit-polymorphism"><a class="section-anchor" href="#ss:explicit-polymorphism" aria-hidden="true"></a>5.2.1  Explicitly polymorphic annotations</h3><!--SEC END --><p>
The solution of this conundrum is to use an explicitly polymorphic type
annotation for the type <span class="c003">'a</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> depth: 'a. 'a nested -&gt; int = <span class="ocamlkeyword">function</span>
   | List _ -&gt; 1
   | Nested n -&gt; 1 + depth n;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> depth : 'a nested -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> depth ( Nested(List [ [7]; [8] ]) );;</div>



<div class="pre caml-output ok">- : int = 2</div></div>

</div><p>


In the type of <span class="c003">depth</span>, <span class="c003">'a.'a nested -&gt; int</span>, the type variable <span class="c003">'a</span>
is universally quantified. In other words, <span class="c003">'a.'a nested -&gt; int</span> reads as
“for all type <span class="c003">'a</span>, <span class="c003">depth</span> maps <span class="c003">'a nested</span> values to integers”.
Whereas the standard type <span class="c003">'a nested -&gt; int</span> can be interpreted
as “let be a type variable <span class="c003">'a</span>, then <span class="c003">depth</span> maps <span class="c003">'a nested</span> values
to integers”. There are two major differences with these two type
expressions. First, the explicit polymorphic annotation indicates to the
type checker that it needs to introduce a new type variable every times
the function <span class="c003">depth</span> is applied. This solves our problem with the definition
of the function <span class="c003">depth</span>.</p><p>Second, it also notifies the type checker that the type of the function should
be polymorphic. Indeed, without explicit polymorphic type annotation, the
following type annotation is perfectly valid


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> sum: 'a -&gt; 'b -&gt; 'c = <span class="ocamlkeyword">fun</span> x y -&gt; x + y;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> sum : int -&gt; int -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


since <span class="c003">'a</span>,<span class="c003">'b</span> and <span class="c003">'c</span> denote type variables that may or may not be
polymorphic. Whereas, it is an error to unify an explicitly polymorphic type
with a non-polymorphic type:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> sum: 'a 'b 'c. 'a -&gt; 'b -&gt; 'c = <span class="ocamlhighlight">fun x y -&gt; x + y</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This definition has type int -&gt; int -&gt; int which is less general than
         'a 'b 'c. 'a -&gt; 'b -&gt; 'c</div></div>

</div><p>An important remark here is that it is not needed to explicit fully
the type of <span class="c003">depth</span>: it is sufficient to add annotations only for the
universally quantified type variables:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> depth: 'a. 'a nested -&gt; _ = <span class="ocamlkeyword">function</span>
   | List _ -&gt; 1
   | Nested n -&gt; 1 + depth n;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> depth : 'a nested -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> depth ( Nested(List [ [7]; [8] ]) );;</div>



<div class="pre caml-output ok">- : int = 2</div></div>

</div>
<!--TOC subsection id="ss:recursive-poly-examples" 5.2.2  More examples-->
<h3 class="subsection" id="ss:recursive-poly-examples"><a class="section-anchor" href="#ss:recursive-poly-examples" aria-hidden="true"></a>5.2.2  More examples</h3><!--SEC END --><p>
With explicit polymorphic annotations, it becomes possible to implement
any recursive function that depends only on the structure of the nested
lists and not on the type of the elements. For instance, a more complex
example would be to compute the total number of elements of the nested
lists:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> len nested =
     <span class="ocamlkeyword">let</span> map_and_sum f = List.fold_left (<span class="ocamlkeyword">fun</span> acc x -&gt; acc + f x) 0 <span class="ocamlkeyword">in</span>
     <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> len: 'a. ('a list -&gt; int ) -&gt; 'a nested -&gt; int =
     <span class="ocamlkeyword">fun</span> nested_len n -&gt;
       <span class="ocamlkeyword">match</span> n <span class="ocamlkeyword">with</span>
       | List l -&gt; nested_len l
       | Nested n -&gt; len (map_and_sum nested_len) n
     <span class="ocamlkeyword">in</span>
   len List.length nested;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> len : 'a nested -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> len (Nested(Nested(List [ [ [1;2]; [3] ]; [ []; [4]; [5;6;7]]; [[]] ])));;</div>



<div class="pre caml-output ok">- : int = 7</div></div>

</div><p>Similarly, it may be necessary to use more than one explicitly
polymorphic type variables, like for computing the nested list of
list lengths of the nested list:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> shape n =
   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> shape: 'a 'b. ('a nested -&gt; int nested) -&gt;
     ('b list list -&gt; 'a list) -&gt; 'b nested -&gt; int nested
     = <span class="ocamlkeyword">fun</span> nest nested_shape -&gt;
       <span class="ocamlkeyword">function</span>
       | List l -&gt; raise
        (Invalid_argument <span class="ocamlstring">"shape requires nested_list of depth greater than 1"</span>)
       | Nested (List l) -&gt; nest @@ List (nested_shape l)
       | Nested n -&gt;
         <span class="ocamlkeyword">let</span> nested_shape = List.map nested_shape <span class="ocamlkeyword">in</span>
         <span class="ocamlkeyword">let</span> nest x = nest (Nested x) <span class="ocamlkeyword">in</span>
         shape nest nested_shape n <span class="ocamlkeyword">in</span>
   shape (<span class="ocamlkeyword">fun</span> n -&gt; n ) (<span class="ocamlkeyword">fun</span> l -&gt; List.map List.length l ) n;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> shape : 'a nested -&gt; int nested = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> shape (Nested(Nested(List [ [ [1;2]; [3] ]; [ []; [4]; [5;6;7]]; [[]] ])));;</div>



<div class="pre caml-output ok">- : int nested = Nested (List [[2; 1]; [0; 1; 3]; [0]])</div></div>

</div>
<!--TOC section id="s:higher-rank-poly" 5.3  Higher-rank polymorphic functions-->
<h2 class="section" id="s:higher-rank-poly"><a class="section-anchor" href="#s:higher-rank-poly" aria-hidden="true"></a>5.3  Higher-rank polymorphic functions</h2><!--SEC END --><p>Explicit polymorphic annotations are however not sufficient to cover all
the cases where the inferred type of a function is less general than
expected. A similar problem arises when using polymorphic functions as arguments
of higher-order functions. For instance, we may want to compute the average
depth or length of two nested lists:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> average_depth x y = (depth x + depth y) / 2;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> average_depth : 'a nested -&gt; 'b nested -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> average_len x y = (len x + len y) / 2;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> average_len : 'a nested -&gt; 'b nested -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> one = average_len (List [2]) (List [[]]);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> one : int = 1</div></div>

</div><p>


It would be natural to factorize these two definitions as:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">     <span class="ocamlkeyword">let</span> average f x y = (f x + f y) / 2;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> average : ('a -&gt; int) -&gt; 'a -&gt; 'a -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


However, the type of <span class="c003">average len</span> is less generic than the type of
<span class="c003">average_len</span>, since it requires the type of the first and second argument to
be the same:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   average_len (List [2]) (List [[]]);;</div>



<div class="pre caml-output ok">- : int = 1</div></div>
<div class="ocaml">



<div class="pre caml-input">   average len (List [2]) (List [<span class="ocamlhighlight">[]</span>]);;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type 'a list
       but an expression was expected of type int</div></div>

</div><p>As previously with polymorphic recursion, the problem stems from the fact that
type variables are introduced only at the start of the <span class="c003">let</span> definitions. When
we compute both <span class="c003">f x</span> and <span class="c003">f y</span>, the type of <span class="c003">x</span> and <span class="c003">y</span> are unified together.
To avoid this unification, we need to indicate to the type checker
that f is polymorphic in its first argument. In some sense, we would want
<span class="c003">average</span> to have type
</p><pre>val average: ('a. 'a nested -&gt; int) -&gt; 'a nested -&gt; 'b nested -&gt; int
</pre><p>Note that this syntax is not valid within OCaml: <span class="c003">average</span> has an universally
quantified type <span class="c003">'a</span> inside the type of one of its argument whereas for
polymorphic recursion the universally quantified type was introduced before
the rest of the type. This position of the universally quantified type means
that <span class="c003">average</span> is a second-rank polymorphic function. This kind of higher-rank
functions is not directly supported by OCaml: type inference for second-rank
polymorphic function and beyond is undecidable; therefore using this kind of
higher-rank functions requires to handle manually these universally quantified
types.</p><p>In OCaml, there are two ways to introduce this kind of explicit universally
quantified types: universally quantified record fields,


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">type</span> 'a nested_reduction = { f:'elt. 'elt nested -&gt; 'a };;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> 'a nested_reduction = { f : 'elt. 'elt nested -&gt; 'a; }</div></div>
<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> boxed_len = { f = len };;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> boxed_len : int nested_reduction = {f = &lt;<span class="ocamlkeyword">fun</span>&gt;}</div></div>

</div><p>


and universally quantified object methods:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> obj_len = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> f:'a. 'a nested -&gt; 'b = len <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> obj_len : &lt; f : 'a. 'a nested -&gt; int &gt; = &lt;obj&gt;</div></div>

</div><p>


To solve our problem, we can therefore use either the record solution:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> average nsm x y = (nsm.f x + nsm.f y) / 2 ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> average : int nested_reduction -&gt; 'a nested -&gt; 'b nested -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


or the object one:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> average (obj:&lt;f:'a. 'a nested -&gt; _ &gt; ) x y = (obj#f x + obj#f y) / 2 ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> average : &lt; f : 'a. 'a nested -&gt; int &gt; -&gt; 'b nested -&gt; 'c nested -&gt; int =
  &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div>
<!--TOC chapter id="sec64" Chapter 6  Advanced examples with classes and modules-->
<h1 class="chapter" id="sec64">Chapter 6  Advanced examples with classes and modules</h1><!--SEC END --><!--NAME advexamples.html-->
<p>
<a id="c:advexamples"></a></p><p><span class="c009">(Chapter written by Didier Rémy)</span></p><p><br>
<br>
</p><p>In this chapter, we show some larger examples using objects, classes
and modules. We review many of the object features simultaneously on
the example of a bank account. We show how modules taken from the
standard library can be expressed as classes. Lastly, we describe a
programming pattern known as <em>virtual types</em> through the example
of window managers.</p>
<!--TOC section id="s:extended-bank-accounts" 6.1  Extended example: bank accounts-->
<h2 class="section" id="s:extended-bank-accounts"><a class="section-anchor" href="#s:extended-bank-accounts" aria-hidden="true"></a>6.1  Extended example: bank accounts</h2><!--SEC END --><p>In this section, we illustrate most aspects of Object and inheritance
by refining, debugging, and specializing the following
initial naive definition of a simple bank account. (We reuse the
module <span class="c003">Euro</span> defined at the end of chapter <a href="#c%3Aobjectexamples">3</a>.)


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> euro = <span class="ocamlkeyword">new</span> Euro.c;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> euro : float -&gt; Euro.c = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> zero = euro 0.;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> zero : Euro.c = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> neg x = x#times (-1.);;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> neg : &lt; times : float -&gt; 'a; .. &gt; -&gt; 'a = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> account =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> balance = zero
     <span class="ocamlkeyword">method</span> balance = balance
     <span class="ocamlkeyword">method</span> deposit x = balance &lt;- balance # plus x
     <span class="ocamlkeyword">method</span> withdraw x =
       <span class="ocamlkeyword">if</span> x#leq balance <span class="ocamlkeyword">then</span> (balance &lt;- balance # plus (neg x); x) <span class="ocamlkeyword">else</span> zero
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> account :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> balance : Euro.c
    <span class="ocamlkeyword">method</span> balance : Euro.c
    <span class="ocamlkeyword">method</span> deposit : Euro.c -&gt; unit
    <span class="ocamlkeyword">method</span> withdraw : Euro.c -&gt; Euro.c
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> c = <span class="ocamlkeyword">new</span> account <span class="ocamlkeyword">in</span> c # deposit (euro 100.); c # withdraw (euro 50.);;</div>



<div class="pre caml-output ok">- : Euro.c = &lt;obj&gt;</div></div>

</div><p>


We now refine this definition with a method to compute interest.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> account_with_interests =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">inherit</span> account
     <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">private</span> interest = self # deposit (self # balance # times 0.03)
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> account_with_interests :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> balance : Euro.c
    <span class="ocamlkeyword">method</span> balance : Euro.c
    <span class="ocamlkeyword">method</span> deposit : Euro.c -&gt; unit
    <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">private</span> interest : unit
    <span class="ocamlkeyword">method</span> withdraw : Euro.c -&gt; Euro.c
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


We make the method <span class="c003">interest</span> private, since clearly it should not be
called freely from the outside. Here, it is only made accessible to subclasses
that will manage monthly or yearly updates of the account.</p><p>We should soon fix a bug in the current definition: the deposit method can
be used for withdrawing money by depositing negative amounts. We can
fix this directly:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> safe_account =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> account
     <span class="ocamlkeyword">method</span> deposit x = <span class="ocamlkeyword">if</span> zero#leq x <span class="ocamlkeyword">then</span> balance &lt;- balance#plus x
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> safe_account :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> balance : Euro.c
    <span class="ocamlkeyword">method</span> balance : Euro.c
    <span class="ocamlkeyword">method</span> deposit : Euro.c -&gt; unit
    <span class="ocamlkeyword">method</span> withdraw : Euro.c -&gt; Euro.c
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


However, the bug might be fixed more safely by the following definition:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> safe_account =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> account <span class="ocamlkeyword">as</span> unsafe
     <span class="ocamlkeyword">method</span> deposit x =
       <span class="ocamlkeyword">if</span> zero#leq x <span class="ocamlkeyword">then</span> unsafe # deposit x
       <span class="ocamlkeyword">else</span> raise (Invalid_argument <span class="ocamlstring">"deposit"</span>)
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> safe_account :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> balance : Euro.c
    <span class="ocamlkeyword">method</span> balance : Euro.c
    <span class="ocamlkeyword">method</span> deposit : Euro.c -&gt; unit
    <span class="ocamlkeyword">method</span> withdraw : Euro.c -&gt; Euro.c
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


In particular, this does not require the knowledge of the implementation of
the method <span class="c003">deposit</span>.</p><p>To keep track of operations, we extend the class with a mutable field
<span class="c003">history</span> and a private method <span class="c003">trace</span> to add an operation in the
log. Then each method to be traced is redefined.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> 'a operation = Deposit <span class="ocamlkeyword">of</span> 'a | Retrieval <span class="ocamlkeyword">of</span> 'a;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> 'a operation = Deposit <span class="ocamlkeyword">of</span> 'a | Retrieval <span class="ocamlkeyword">of</span> 'a</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> account_with_history =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">inherit</span> safe_account <span class="ocamlkeyword">as</span> super
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> history = []
     <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">private</span> trace x = history &lt;- x :: history
     <span class="ocamlkeyword">method</span> deposit x = self#trace (Deposit x);  super#deposit x
     <span class="ocamlkeyword">method</span> withdraw x = self#trace (Retrieval x); super#withdraw x
     <span class="ocamlkeyword">method</span> history = List.rev history
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> account_with_history :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> balance : Euro.c
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> history : Euro.c operation list
    <span class="ocamlkeyword">method</span> balance : Euro.c
    <span class="ocamlkeyword">method</span> deposit : Euro.c -&gt; unit
    <span class="ocamlkeyword">method</span> history : Euro.c operation list
    <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">private</span> trace : Euro.c operation -&gt; unit
    <span class="ocamlkeyword">method</span> withdraw : Euro.c -&gt; Euro.c
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


One may wish to open an account and simultaneously deposit some initial
amount. Although the initial implementation did not address this
requirement, it can be achieved by using an initializer.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> account_with_deposit x =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> account_with_history
     <span class="ocamlkeyword">initializer</span> balance &lt;- x
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> account_with_deposit :
  Euro.c -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> balance : Euro.c
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> history : Euro.c operation list
    <span class="ocamlkeyword">method</span> balance : Euro.c
    <span class="ocamlkeyword">method</span> deposit : Euro.c -&gt; unit
    <span class="ocamlkeyword">method</span> history : Euro.c operation list
    <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">private</span> trace : Euro.c operation -&gt; unit
    <span class="ocamlkeyword">method</span> withdraw : Euro.c -&gt; Euro.c
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


A better alternative is:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> account_with_deposit x =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">inherit</span> account_with_history
     <span class="ocamlkeyword">initializer</span> self#deposit x
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> account_with_deposit :
  Euro.c -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> balance : Euro.c
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> history : Euro.c operation list
    <span class="ocamlkeyword">method</span> balance : Euro.c
    <span class="ocamlkeyword">method</span> deposit : Euro.c -&gt; unit
    <span class="ocamlkeyword">method</span> history : Euro.c operation list
    <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">private</span> trace : Euro.c operation -&gt; unit
    <span class="ocamlkeyword">method</span> withdraw : Euro.c -&gt; Euro.c
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


Indeed, the latter is safer since the call to <span class="c003">deposit</span> will automatically
benefit from safety checks and from the trace.
Let’s test it:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> ccp = <span class="ocamlkeyword">new</span> account_with_deposit (euro 100.) <span class="ocamlkeyword">in</span>
 <span class="ocamlkeyword">let</span> _balance = ccp#withdraw (euro 50.) <span class="ocamlkeyword">in</span>
 ccp#history;;</div>



<div class="pre caml-output ok">- : Euro.c operation list = [Deposit &lt;obj&gt;; Retrieval &lt;obj&gt;]</div></div>

</div><p>


Closing an account can be done with the following polymorphic function:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> close c = c#withdraw c#balance;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> close : &lt; balance : 'a; withdraw : 'a -&gt; 'b; .. &gt; -&gt; 'b = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


Of course, this applies to all sorts of accounts.</p><p>Finally, we gather several versions of the account into a module <span class="c003">Account</span>
abstracted over some currency.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> today () = (01,01,2000) <span class="ocamlcomment">(* an approximation *)</span>
 <span class="ocamlkeyword">module</span> Account (M:MONEY) =
   <span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">type</span> m = M.c
     <span class="ocamlkeyword">let</span> m = <span class="ocamlkeyword">new</span> M.c
     <span class="ocamlkeyword">let</span> zero = m 0.

     <span class="ocamlkeyword">class</span> bank =
       <span class="ocamlkeyword">object</span> (self)
         <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> balance = zero
         <span class="ocamlkeyword">method</span> balance = balance
         <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> history = []
         <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">private</span> trace x = history &lt;- x::history
         <span class="ocamlkeyword">method</span> deposit x =
           self#trace (Deposit x);
           <span class="ocamlkeyword">if</span> zero#leq x <span class="ocamlkeyword">then</span> balance &lt;- balance # plus x
           <span class="ocamlkeyword">else</span> raise (Invalid_argument <span class="ocamlstring">"deposit"</span>)
         <span class="ocamlkeyword">method</span> withdraw x =
           <span class="ocamlkeyword">if</span> x#leq balance <span class="ocamlkeyword">then</span>
             (balance &lt;- balance # plus (neg x); self#trace (Retrieval x); x)
           <span class="ocamlkeyword">else</span> zero
         <span class="ocamlkeyword">method</span> history = List.rev history
       <span class="ocamlkeyword">end</span>

     <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> client_view =
       <span class="ocamlkeyword">object</span>
         <span class="ocamlkeyword">method</span> deposit : m -&gt; unit
         <span class="ocamlkeyword">method</span> history : m operation list
         <span class="ocamlkeyword">method</span> withdraw : m -&gt; m
         <span class="ocamlkeyword">method</span> balance : m
       <span class="ocamlkeyword">end</span>

     <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">virtual</span> check_client x =
       <span class="ocamlkeyword">let</span> y = <span class="ocamlkeyword">if</span> (m 100.)#leq x <span class="ocamlkeyword">then</span> x
       <span class="ocamlkeyword">else</span> raise (Failure <span class="ocamlstring">"Insufficient initial deposit"</span>) <span class="ocamlkeyword">in</span>
       <span class="ocamlkeyword">object</span> (self)
         <span class="ocamlkeyword">initializer</span> self#deposit y
         <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">virtual</span> deposit: m -&gt; unit
       <span class="ocamlkeyword">end</span>

     <span class="ocamlkeyword">module</span> Client (B : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">class</span> bank : client_view <span class="ocamlkeyword">end</span>) =
       <span class="ocamlkeyword">struct</span>
         <span class="ocamlkeyword">class</span> account x : client_view =
           <span class="ocamlkeyword">object</span>
             <span class="ocamlkeyword">inherit</span> B.bank
             <span class="ocamlkeyword">inherit</span> check_client x
           <span class="ocamlkeyword">end</span>

         <span class="ocamlkeyword">let</span> discount x =
           <span class="ocamlkeyword">let</span> c = <span class="ocamlkeyword">new</span> account x <span class="ocamlkeyword">in</span>
           <span class="ocamlkeyword">if</span> today() &lt; (1998,10,30) <span class="ocamlkeyword">then</span> c # deposit (m 100.); c
       <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">end</span>;;</div></div>

</div><p>


This shows the use of modules to group several class definitions that can in
fact be thought of as a single unit. This unit would be provided by a bank
for both internal and external uses.
This is implemented as a functor that abstracts over the currency so that
the same code can be used to provide accounts in different currencies.</p><p>The class <span class="c003">bank</span> is the <em>real</em> implementation of the bank account (it
could have been inlined). This is the one that will be used for further
extensions, refinements, etc. Conversely, the client will only be given the client view.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Euro_account = Account(Euro);;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Client = Euro_account.Client (Euro_account);;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">new</span> Client.account (<span class="ocamlkeyword">new</span> Euro.c 100.);;</div></div>

</div><p>


Hence, the clients do not have direct access to the <span class="c003">balance</span>, nor the
<span class="c003">history</span> of their own accounts. Their only way to change their balance is
to deposit or withdraw money. It is important to give the clients
a class and not just the ability to create accounts (such as the
promotional <span class="c003">discount</span> account), so that they can
personalize their account.
For instance, a client may refine the <span class="c003">deposit</span> and <span class="c003">withdraw</span> methods
so as to do his own financial bookkeeping, automatically. On the
other hand, the function <span class="c003">discount</span> is given as such, with no
possibility for further personalization.</p><p>It is important to provide the client’s view as a functor
<span class="c003">Client</span> so that client accounts can still be built after a possible
specialization of the <span class="c003">bank</span>.
The functor <span class="c003">Client</span> may remain unchanged and be passed
the new definition to initialize a client’s view of the extended account.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Investment_account (M : MONEY) =
   <span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">type</span> m = M.c
     <span class="ocamlkeyword">module</span> A = Account(M)

     <span class="ocamlkeyword">class</span> bank =
       <span class="ocamlkeyword">object</span>
         <span class="ocamlkeyword">inherit</span> A.bank <span class="ocamlkeyword">as</span> super
         <span class="ocamlkeyword">method</span> deposit x =
           <span class="ocamlkeyword">if</span> (<span class="ocamlkeyword">new</span> M.c 1000.)#leq x <span class="ocamlkeyword">then</span>
             print_string <span class="ocamlstring">"Would you like to invest?"</span>;
           super#deposit x
       <span class="ocamlkeyword">end</span>

     <span class="ocamlkeyword">module</span> Client = A.Client
   <span class="ocamlkeyword">end</span>;;</div></div>

</div><p>


The functor <span class="c003">Client</span> may also be redefined when some new features of the
account can be given to the client.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Internet_account (M : MONEY) =
   <span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">type</span> m = M.c
     <span class="ocamlkeyword">module</span> A = Account(M)

     <span class="ocamlkeyword">class</span> bank =
       <span class="ocamlkeyword">object</span>
         <span class="ocamlkeyword">inherit</span> A.bank
         <span class="ocamlkeyword">method</span> mail s = print_string s
       <span class="ocamlkeyword">end</span>

     <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> client_view =
       <span class="ocamlkeyword">object</span>
         <span class="ocamlkeyword">method</span> deposit : m -&gt; unit
         <span class="ocamlkeyword">method</span> history : m operation list
         <span class="ocamlkeyword">method</span> withdraw : m -&gt; m
         <span class="ocamlkeyword">method</span> balance : m
         <span class="ocamlkeyword">method</span> mail : string -&gt; unit
       <span class="ocamlkeyword">end</span>

     <span class="ocamlkeyword">module</span> Client (B : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">class</span> bank : client_view <span class="ocamlkeyword">end</span>) =
       <span class="ocamlkeyword">struct</span>
         <span class="ocamlkeyword">class</span> account x : client_view =
           <span class="ocamlkeyword">object</span>
             <span class="ocamlkeyword">inherit</span> B.bank
             <span class="ocamlkeyword">inherit</span> A.check_client x
           <span class="ocamlkeyword">end</span>
       <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">end</span>;;</div></div>

</div>
<!--TOC section id="s:modules-as-classes" 6.2  Simple modules as classes-->
<h2 class="section" id="s:modules-as-classes"><a class="section-anchor" href="#s:modules-as-classes" aria-hidden="true"></a>6.2  Simple modules as classes</h2><!--SEC END --><p>One may wonder whether it is possible to treat primitive types such as
integers and strings as objects. Although this is usually uninteresting
for integers or strings, there may be some situations where
this is desirable. The class <span class="c003">money</span> above is such an example.
We show here how to do it for strings.</p>
<!--TOC subsection id="ss:string-as-class" 6.2.1  Strings-->
<h3 class="subsection" id="ss:string-as-class"><a class="section-anchor" href="#ss:string-as-class" aria-hidden="true"></a>6.2.1  Strings</h3><!--SEC END --><p>A naive definition of strings as objects could be:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ostring s =
   <span class="ocamlkeyword">object</span>
      <span class="ocamlkeyword">method</span> get n = String.get s n
      <span class="ocamlkeyword">method</span> print = print_string s
      <span class="ocamlkeyword">method</span> escaped = <span class="ocamlkeyword">new</span> ostring (String.escaped s)
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ostring :
  string -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">method</span> escaped : ostring
    <span class="ocamlkeyword">method</span> get : int -&gt; char
    <span class="ocamlkeyword">method</span> print : unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


However, the method <span class="c003">escaped</span> returns an object of the class <span class="c003">ostring</span>,
and not an object of the current class. Hence, if the class is further
extended, the method <span class="c003">escaped</span> will only return an object of the parent
class.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> sub_string s =
   <span class="ocamlkeyword">object</span>
      <span class="ocamlkeyword">inherit</span> ostring s
      <span class="ocamlkeyword">method</span> sub start len = <span class="ocamlkeyword">new</span> sub_string (String.sub s  start len)
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> sub_string :
  string -&gt;
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">method</span> escaped : ostring
    <span class="ocamlkeyword">method</span> get : int -&gt; char
    <span class="ocamlkeyword">method</span> print : unit
    <span class="ocamlkeyword">method</span> sub : int -&gt; int -&gt; sub_string
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


As seen in section <a href="#s%3Abinary-methods">3.16</a>, the solution is to use
functional update instead. We need to create an instance variable
containing the representation <span class="c003">s</span> of the string.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> better_string s =
   <span class="ocamlkeyword">object</span>
      <span class="ocamlkeyword">val</span> repr = s
      <span class="ocamlkeyword">method</span> get n = String.get repr n
      <span class="ocamlkeyword">method</span> print = print_string repr
      <span class="ocamlkeyword">method</span> escaped = {&lt; repr = String.escaped repr &gt;}
      <span class="ocamlkeyword">method</span> sub start len = {&lt; repr = String.sub s start len &gt;}
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> better_string :
  string -&gt;
  <span class="ocamlkeyword">object</span> ('a)
    <span class="ocamlkeyword">val</span> repr : string
    <span class="ocamlkeyword">method</span> escaped : 'a
    <span class="ocamlkeyword">method</span> get : int -&gt; char
    <span class="ocamlkeyword">method</span> print : unit
    <span class="ocamlkeyword">method</span> sub : int -&gt; int -&gt; 'a
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


As shown in the inferred type, the methods <span class="c003">escaped</span> and <span class="c003">sub</span> now return
objects of the same type as the one of the class.</p><p>Another difficulty is the implementation of the method <span class="c003">concat</span>.
In order to concatenate a string with another string of the same class,
one must be able to access the instance variable externally. Thus, a method
<span class="c003">repr</span> returning s must be defined. Here is the correct definition of
strings:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ostring s =
   <span class="ocamlkeyword">object</span> (self : 'mytype)
      <span class="ocamlkeyword">val</span> repr = s
      <span class="ocamlkeyword">method</span> repr = repr
      <span class="ocamlkeyword">method</span> get n = String.get repr n
      <span class="ocamlkeyword">method</span> print = print_string repr
      <span class="ocamlkeyword">method</span> escaped = {&lt; repr = String.escaped repr &gt;}
      <span class="ocamlkeyword">method</span> sub start len = {&lt; repr = String.sub s start len &gt;}
      <span class="ocamlkeyword">method</span> concat (t : 'mytype) = {&lt; repr = repr ^ t#repr &gt;}
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ostring :
  string -&gt;
  <span class="ocamlkeyword">object</span> ('a)
    <span class="ocamlkeyword">val</span> repr : string
    <span class="ocamlkeyword">method</span> concat : 'a -&gt; 'a
    <span class="ocamlkeyword">method</span> escaped : 'a
    <span class="ocamlkeyword">method</span> get : int -&gt; char
    <span class="ocamlkeyword">method</span> print : unit
    <span class="ocamlkeyword">method</span> repr : string
    <span class="ocamlkeyword">method</span> sub : int -&gt; int -&gt; 'a
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


Another constructor of the class string can be defined to return a new
string of a given length:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> cstring n = ostring (String.make n ' ');;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> cstring : int -&gt; ostring</div></div>

</div><p>


Here, exposing the representation of strings is probably harmless. We do
could also hide the representation of strings as we hid the currency in the
class <span class="c003">money</span> of section <a href="#s%3Afriends">3.17</a>.</p>
<!--TOC subsubsection id="sss:stack-as-class" Stacks-->
<h4 class="subsubsection" id="sss:stack-as-class"><a class="section-anchor" href="#sss:stack-as-class" aria-hidden="true"></a>Stacks</h4><!--SEC END --><p>There is sometimes an alternative between using modules or classes for
parametric data types.
Indeed, there are situations when the two approaches are quite similar.
For instance, a stack can be straightforwardly implemented as a class:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">exception</span> Empty;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">exception</span> Empty</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a] stack =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> l = ([] : 'a list)
     <span class="ocamlkeyword">method</span> push x = l &lt;- x::l
     <span class="ocamlkeyword">method</span> pop = <span class="ocamlkeyword">match</span> l <span class="ocamlkeyword">with</span> [] -&gt; raise Empty | a::l' -&gt; l &lt;- l'; a
     <span class="ocamlkeyword">method</span> clear = l &lt;- []
     <span class="ocamlkeyword">method</span> length = List.length l
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] stack :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> l : 'a list
    <span class="ocamlkeyword">method</span> clear : unit
    <span class="ocamlkeyword">method</span> length : int
    <span class="ocamlkeyword">method</span> pop : 'a
    <span class="ocamlkeyword">method</span> push : 'a -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


However, writing a method for iterating over a stack is more
problematic. A method <span class="c003">fold</span> would have type
<span class="c003">('b -&gt; 'a -&gt; 'b) -&gt; 'b -&gt; 'b</span>. Here <span class="c003">'a</span> is the parameter of the stack.
The parameter <span class="c003">'b</span> is not related to the class <span class="c003">'a stack</span> but to the
argument that will be passed to the method <span class="c003">fold</span>.
A naive approach is to make <span class="c003">'b</span> an extra parameter of class <span class="c003">stack</span>:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a, 'b] stack2 =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> ['a] stack
     <span class="ocamlkeyword">method</span> fold f (x : 'b) = List.fold_left f x l
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a, 'b] stack2 :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> l : 'a list
    <span class="ocamlkeyword">method</span> clear : unit
    <span class="ocamlkeyword">method</span> fold : ('b -&gt; 'a -&gt; 'b) -&gt; 'b -&gt; 'b
    <span class="ocamlkeyword">method</span> length : int
    <span class="ocamlkeyword">method</span> pop : 'a
    <span class="ocamlkeyword">method</span> push : 'a -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


However, the method <span class="c003">fold</span> of a given object can only be
applied to functions that all have the same type:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> s = <span class="ocamlkeyword">new</span> stack2;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> s : ('_weak1, '_weak2) stack2 = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> s#fold ( + ) 0;;</div>



<div class="pre caml-output ok">- : int = 0</div></div>
<div class="ocaml">



<div class="pre caml-input"> s;;</div>



<div class="pre caml-output ok">- : (int, int) stack2 = &lt;obj&gt;</div></div>

</div><p>


A better solution is to use polymorphic methods, which were
introduced in OCaml version 3.05. Polymorphic methods makes
it possible to treat the type variable <span class="c003">'b</span> in the type of <span class="c003">fold</span> as
universally quantified, giving <span class="c003">fold</span> the polymorphic type
<span class="c003">Forall 'b. ('b -&gt; 'a -&gt; 'b) -&gt; 'b -&gt; 'b</span>.
An explicit type declaration on the method <span class="c003">fold</span> is required, since
the type checker cannot infer the polymorphic type by itself.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a] stack3 =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> ['a] stack
     <span class="ocamlkeyword">method</span> fold : 'b. ('b -&gt; 'a -&gt; 'b) -&gt; 'b -&gt; 'b
                 = <span class="ocamlkeyword">fun</span> f x -&gt; List.fold_left f x l
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] stack3 :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> l : 'a list
    <span class="ocamlkeyword">method</span> clear : unit
    <span class="ocamlkeyword">method</span> fold : ('b -&gt; 'a -&gt; 'b) -&gt; 'b -&gt; 'b
    <span class="ocamlkeyword">method</span> length : int
    <span class="ocamlkeyword">method</span> pop : 'a
    <span class="ocamlkeyword">method</span> push : 'a -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div>
<!--TOC subsection id="ss:hashtbl-as-class" 6.2.2  Hashtbl-->
<h3 class="subsection" id="ss:hashtbl-as-class"><a class="section-anchor" href="#ss:hashtbl-as-class" aria-hidden="true"></a>6.2.2  Hashtbl</h3><!--SEC END --><p>A simplified version of object-oriented hash tables should have the
following class type.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> ['a, 'b] hash_table =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">method</span> find : 'a -&gt; 'b
     <span class="ocamlkeyword">method</span> add : 'a -&gt; 'b -&gt; unit
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> ['a, 'b] hash_table =
  <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> add : 'a -&gt; 'b -&gt; unit <span class="ocamlkeyword">method</span> find : 'a -&gt; 'b <span class="ocamlkeyword">end</span></div></div>

</div><p>


A simple implementation, which is quite reasonable for small hash tables is
to use an association list:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a, 'b] small_hashtbl : ['a, 'b] hash_table =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> table = []
     <span class="ocamlkeyword">method</span> find key = List.assoc key table
     <span class="ocamlkeyword">method</span> add key valeur = table &lt;- (key, valeur) :: table
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a, 'b] small_hashtbl : ['a, 'b] hash_table</div></div>

</div><p>


A better implementation, and one that scales up better, is to use a
true hash table… whose elements are small hash tables!


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['a, 'b] hashtbl size : ['a, 'b] hash_table =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">val</span> table = Array.init size (<span class="ocamlkeyword">fun</span> i -&gt; <span class="ocamlkeyword">new</span> small_hashtbl)
     <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">private</span> hash key =
       (Hashtbl.hash key) <span class="ocamlkeyword">mod</span> (Array.length table)
     <span class="ocamlkeyword">method</span> find key = table.(self#hash key) # find key
     <span class="ocamlkeyword">method</span> add key = table.(self#hash key) # add key
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a, 'b] hashtbl : int -&gt; ['a, 'b] hash_table</div></div>

</div>
<!--TOC subsection id="ss:set-as-class" 6.2.3  Sets-->
<h3 class="subsection" id="ss:set-as-class"><a class="section-anchor" href="#ss:set-as-class" aria-hidden="true"></a>6.2.3  Sets</h3><!--SEC END --><p>Implementing sets leads to another difficulty. Indeed, the method
<span class="c003">union</span> needs to be able to access the internal representation of
another object of the same class.</p><p>This is another instance of friend functions as seen in
section <a href="#s%3Afriends">3.17</a>. Indeed, this is the same mechanism used in the module
<span class="c003">Set</span> in the absence of objects.</p><p>In the object-oriented version of sets, we only need to add an additional
method <span class="c003">tag</span> to return the representation of a set. Since sets are
parametric in the type of elements, the method <span class="c003">tag</span> has a parametric type
<span class="c003">'a tag</span>, concrete within
the module definition but abstract in its signature.
From outside, it will then be guaranteed that two objects with a method <span class="c003">tag</span>
of the same type will share the same representation.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> SET =
   <span class="ocamlkeyword">sig</span>
     <span class="ocamlkeyword">type</span> 'a tag
     <span class="ocamlkeyword">class</span> ['a] c :
       <span class="ocamlkeyword">object</span> ('b)
         <span class="ocamlkeyword">method</span> is_empty : bool
         <span class="ocamlkeyword">method</span> mem : 'a -&gt; bool
         <span class="ocamlkeyword">method</span> add : 'a -&gt; 'b
         <span class="ocamlkeyword">method</span> union : 'b -&gt; 'b
         <span class="ocamlkeyword">method</span> iter : ('a -&gt; unit) -&gt; unit
         <span class="ocamlkeyword">method</span> tag : 'a tag
       <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">end</span>;;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Set : SET =
   <span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> merge l1 l2 =
       <span class="ocamlkeyword">match</span> l1 <span class="ocamlkeyword">with</span>
         [] -&gt; l2
       | h1 :: t1 -&gt;
           <span class="ocamlkeyword">match</span> l2 <span class="ocamlkeyword">with</span>
             [] -&gt; l1
           | h2 :: t2 -&gt;
               <span class="ocamlkeyword">if</span> h1 &lt; h2 <span class="ocamlkeyword">then</span> h1 :: merge t1 l2
               <span class="ocamlkeyword">else</span> <span class="ocamlkeyword">if</span> h1 &gt; h2 <span class="ocamlkeyword">then</span> h2 :: merge l1 t2
               <span class="ocamlkeyword">else</span> merge t1 l2
     <span class="ocamlkeyword">type</span> 'a tag = 'a list
     <span class="ocamlkeyword">class</span> ['a] c =
       <span class="ocamlkeyword">object</span> (_ : 'b)
         <span class="ocamlkeyword">val</span> repr = ([] : 'a list)
         <span class="ocamlkeyword">method</span> is_empty = (repr = [])
         <span class="ocamlkeyword">method</span> mem x = List.exists (( = ) x) repr
         <span class="ocamlkeyword">method</span> add x = {&lt; repr = merge [x] repr &gt;}
         <span class="ocamlkeyword">method</span> union (s : 'b) = {&lt; repr = merge repr s#tag &gt;}
         <span class="ocamlkeyword">method</span> iter (f : 'a -&gt; unit) = List.iter f repr
         <span class="ocamlkeyword">method</span> tag = repr
       <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">end</span>;;</div></div>

</div>
<!--TOC section id="s:subject-observer" 6.3  The subject/observer pattern-->
<h2 class="section" id="s:subject-observer"><a class="section-anchor" href="#s:subject-observer" aria-hidden="true"></a>6.3  The subject/observer pattern</h2><!--SEC END --><p>The following example, known as the subject/observer pattern, is often
presented in the literature as a difficult inheritance problem with
inter-connected classes.
The general pattern amounts to the definition a pair of two
classes that recursively interact with one another.</p><p>The class <span class="c003">observer</span> has a distinguished method <span class="c003">notify</span> that requires
two arguments, a subject and an event to execute an action.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">virtual</span> ['subject, 'event] observer =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">virtual</span> notify : 'subject -&gt;  'event -&gt; unit
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> <span class="ocamlkeyword">virtual</span> ['subject, 'event] observer :
  <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> <span class="ocamlkeyword">virtual</span> notify : 'subject -&gt; 'event -&gt; unit <span class="ocamlkeyword">end</span></div></div>

</div><p>


The class <span class="c003">subject</span> remembers a list of observers in an instance variable,
and has a distinguished method <span class="c003">notify_observers</span> to broadcast the message
<span class="c003">notify</span> to all observers with a particular event <span class="c003">e</span>.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['observer, 'event] subject =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> observers = ([]:'observer list)
     <span class="ocamlkeyword">method</span> add_observer obs = observers &lt;- (obs :: observers)
     <span class="ocamlkeyword">method</span> notify_observers (e : 'event) =
         List.iter (<span class="ocamlkeyword">fun</span> x -&gt; x#notify self e) observers
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a, 'event] subject :
  <span class="ocamlkeyword">object</span> ('b)
    <span class="ocamlkeyword">constraint</span> 'a = &lt; notify : 'b -&gt; 'event -&gt; unit; .. &gt;
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> observers : 'a list
    <span class="ocamlkeyword">method</span> add_observer : 'a -&gt; unit
    <span class="ocamlkeyword">method</span> notify_observers : 'event -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


The difficulty usually lies in defining instances of the pattern above
by inheritance. This can be done in a natural and obvious manner in
OCaml, as shown on the following example manipulating windows.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> event = Raise | Resize | Move;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">type</span> event = Raise | Resize | Move</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> string_of_event = <span class="ocamlkeyword">function</span>
     Raise -&gt; <span class="ocamlstring">"Raise"</span> | Resize -&gt; <span class="ocamlstring">"Resize"</span> | Move -&gt; <span class="ocamlstring">"Move"</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> string_of_event : event -&gt; string = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> count = <span class="ocamlkeyword">ref</span> 0;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> count : int <span class="ocamlkeyword">ref</span> = {contents = 0}</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['observer] window_subject =
   <span class="ocamlkeyword">let</span> id = count := succ !count; !count <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">inherit</span> ['observer, event] subject
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> position = 0
     <span class="ocamlkeyword">method</span> identity = id
     <span class="ocamlkeyword">method</span> move x = position &lt;- position + x; self#notify_observers Move
     <span class="ocamlkeyword">method</span> draw = Printf.printf <span class="ocamlstring">"{Position = %d}\n"</span>  position;
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] window_subject :
  <span class="ocamlkeyword">object</span> ('b)
    <span class="ocamlkeyword">constraint</span> 'a = &lt; notify : 'b -&gt; event -&gt; unit; .. &gt;
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> observers : 'a list
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> position : int
    <span class="ocamlkeyword">method</span> add_observer : 'a -&gt; unit
    <span class="ocamlkeyword">method</span> draw : unit
    <span class="ocamlkeyword">method</span> identity : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
    <span class="ocamlkeyword">method</span> notify_observers : event -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['subject] window_observer =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> ['subject, event] observer
     <span class="ocamlkeyword">method</span> notify s e = s#draw
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] window_observer :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">constraint</span> 'a = &lt; draw : unit; .. &gt;
    <span class="ocamlkeyword">method</span> notify : 'a -&gt; event -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


As can be expected, the type of <span class="c003">window</span> is recursive.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> window = <span class="ocamlkeyword">new</span> window_subject;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> window : &lt; notify : 'a -&gt; event -&gt; unit; _.. &gt; window_subject <span class="ocamlkeyword">as</span> 'a =
  &lt;obj&gt;</div></div>

</div><p>


However, the two classes of <span class="c003">window_subject</span> and <span class="c003">window_observer</span> are not
mutually recursive.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> window_observer = <span class="ocamlkeyword">new</span> window_observer;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> window_observer : &lt; draw : unit; _.. &gt; window_observer = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> window#add_observer window_observer;;</div>



<div class="pre caml-output ok">- : unit = ()</div></div>
<div class="ocaml">



<div class="pre caml-input"> window#move 1;;</div>



<div class="pre caml-output ok">{Position = 1}
- : unit = ()</div></div>

</div><p>Classes <span class="c003">window_observer</span> and <span class="c003">window_subject</span> can still be extended by
inheritance. For instance, one may enrich the <span class="c003">subject</span> with new
behaviors and refine the behavior of the observer.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['observer] richer_window_subject =
   <span class="ocamlkeyword">object</span> (self)
     <span class="ocamlkeyword">inherit</span> ['observer] window_subject
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> size = 1
     <span class="ocamlkeyword">method</span> resize x = size &lt;- size + x; self#notify_observers Resize
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> top = <span class="ocamlkeyword">false</span>
     <span class="ocamlkeyword">method</span> raise = top &lt;- <span class="ocamlkeyword">true</span>; self#notify_observers Raise
     <span class="ocamlkeyword">method</span> draw = Printf.printf <span class="ocamlstring">"{Position = %d; Size = %d}\n"</span>  position size;
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] richer_window_subject :
  <span class="ocamlkeyword">object</span> ('b)
    <span class="ocamlkeyword">constraint</span> 'a = &lt; notify : 'b -&gt; event -&gt; unit; .. &gt;
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> observers : 'a list
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> position : int
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> size : int
    <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> top : bool
    <span class="ocamlkeyword">method</span> add_observer : 'a -&gt; unit
    <span class="ocamlkeyword">method</span> draw : unit
    <span class="ocamlkeyword">method</span> identity : int
    <span class="ocamlkeyword">method</span> move : int -&gt; unit
    <span class="ocamlkeyword">method</span> notify_observers : event -&gt; unit
    <span class="ocamlkeyword">method</span> raise : unit
    <span class="ocamlkeyword">method</span> resize : int -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['subject] richer_window_observer =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> ['subject] window_observer <span class="ocamlkeyword">as</span> super
     <span class="ocamlkeyword">method</span> notify s e = <span class="ocamlkeyword">if</span> e &lt;&gt; Raise <span class="ocamlkeyword">then</span> s#raise; super#notify s e
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] richer_window_observer :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">constraint</span> 'a = &lt; draw : unit; raise : unit; .. &gt;
    <span class="ocamlkeyword">method</span> notify : 'a -&gt; event -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


We can also create a different kind of observer:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> ['subject] trace_observer =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlkeyword">inherit</span> ['subject, event] observer
     <span class="ocamlkeyword">method</span> notify s e =
       Printf.printf
         <span class="ocamlstring">"&lt;Window %d &lt;== %s&gt;\n"</span> s#identity (string_of_event e)
   <span class="ocamlkeyword">end</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">class</span> ['a] trace_observer :
  <span class="ocamlkeyword">object</span>
    <span class="ocamlkeyword">constraint</span> 'a = &lt; identity : int; .. &gt;
    <span class="ocamlkeyword">method</span> notify : 'a -&gt; event -&gt; unit
  <span class="ocamlkeyword">end</span></div></div>

</div><p>


and attach several observers to the same object:


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> window = <span class="ocamlkeyword">new</span> richer_window_subject;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> window :
  &lt; notify : 'a -&gt; event -&gt; unit; _.. &gt; richer_window_subject <span class="ocamlkeyword">as</span> 'a = &lt;obj&gt;</div></div>
<div class="ocaml">



<div class="pre caml-input"> window#add_observer (<span class="ocamlkeyword">new</span> richer_window_observer);;</div>



<div class="pre caml-output ok">- : unit = ()</div></div>
<div class="ocaml">



<div class="pre caml-input"> window#add_observer (<span class="ocamlkeyword">new</span> trace_observer);;</div>



<div class="pre caml-output ok">- : unit = ()</div></div>
<div class="ocaml">



<div class="pre caml-input"> window#move 1; window#resize 2;;</div>



<div class="pre caml-output ok">&lt;Window 1 &lt;== Move&gt;
&lt;Window 1 &lt;== Raise&gt;
{Position = 1; Size = 1}
{Position = 1; Size = 1}
&lt;Window 1 &lt;== Resize&gt;
&lt;Window 1 &lt;== Raise&gt;
{Position = 1; Size = 3}
{Position = 1; Size = 3}
- : unit = ()</div></div>

</div>
<!--TOC part id="sec72" Part II  The OCaml language-->
<table class="center"><tr><td><h1 class="part" id="sec72">Part II<br>
The OCaml language</h1></td></tr>
</table><!--SEC END --><p>
<a id="p:refman"></a>
</p>
<!--TOC chapter id="sec73" Chapter 7  The OCaml language-->
<h1 class="chapter" id="sec73">Chapter 7  The OCaml language</h1><!--SEC END --><p> <a id="c:refman"></a>
</p><!--NAME language.html-->
<!--TOC subsection id="ss:foreword" Foreword-->
<h3 class="subsection" id="ss:foreword"><a class="section-anchor" href="#ss:foreword" aria-hidden="true"></a>Foreword</h3><!--SEC END --><p>This document is intended as a reference manual for the OCaml
language. It lists the language constructs, and gives their precise
syntax and informal semantics. It is by no means a tutorial
introduction to the language: there is not a single example. A good
working knowledge of OCaml is assumed.</p><p>No attempt has been made at mathematical rigor: words are employed
with their intuitive meaning, without further definition. As a
consequence, the typing rules have been left out, by lack of the
mathematical framework required to express them, while they are
definitely part of a full formal definition of the language.</p><!--TOC subsection id="ss:notations" Notations-->
<h3 class="subsection" id="ss:notations"><a class="section-anchor" href="#ss:notations" aria-hidden="true"></a>Notations</h3><!--SEC END --><p>The syntax of the language is given in BNF-like notation. Terminal
symbols are set in typewriter font (<span class="c002"><span class="c003">like</span> <span class="c003">this</span></span>).
Non-terminal symbols are set in italic font (<span class="c010">like</span>  <span class="c010">that</span>).
Square brackets […] denote optional components. Curly brackets
{…} denotes zero, one or several repetitions of the enclosed
components. Curly brackets with a trailing plus sign {…}<sup>+</sup>
denote one or several repetitions of the enclosed components.
Parentheses (…) denote grouping.</p><!--CUT DEF section  -->
<!--TOC section id="s:lexical-conventions" 7.1  Lexical conventions-->
<h2 class="section" id="s:lexical-conventions"><a class="section-anchor" href="#s:lexical-conventions" aria-hidden="true"></a>7.1  Lexical conventions</h2><!--SEC END --><!--NAME lex.html-->
<!--TOC subsubsection id="sss:lex:blanks" Blanks-->
<h4 class="subsubsection" id="sss:lex:blanks"><a class="section-anchor" href="#sss:lex:blanks" aria-hidden="true"></a>Blanks</h4><!--SEC END --><p>The following characters are considered as blanks: space,
horizontal tabulation, carriage return, line feed and form feed. Blanks are
ignored, but they separate adjacent identifiers, literals and
keywords that would otherwise be confused as one single identifier,
literal or keyword.</p><!--TOC subsubsection id="sss:lex:comments" Comments-->
<h4 class="subsubsection" id="sss:lex:comments"><a class="section-anchor" href="#sss:lex:comments" aria-hidden="true"></a>Comments</h4><!--SEC END --><p>Comments are introduced by the two characters <span class="c004">(*</span>, with no
intervening blanks, and terminated by the characters <span class="c004">*)</span>, with
no intervening blanks. Comments are treated as blank characters.
Comments do not occur inside string or character literals. Nested
comments are handled correctly.</p><!--TOC subsubsection id="sss:lex:identifiers" Identifiers-->
<h4 class="subsubsection" id="sss:lex:identifiers"><a class="section-anchor" href="#sss:lex:identifiers" aria-hidden="true"></a>Identifiers</h4><!--SEC END --><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="ident"><span class="c010">ident</span></a></td><td class="c015">::=</td><td class="c017"> ( <a class="syntax" href="#letter"><span class="c010">letter</span></a> ∣  <span class="c004">_</span> ) { <a class="syntax" href="#letter"><span class="c010">letter</span></a> ∣  <span class="c004">0</span> … <span class="c004">9</span> ∣  <span class="c004">_</span> ∣  <span class="c004">'</span> }  </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="capitalized-ident"><span class="c010">capitalized-ident</span></a></td><td class="c015">::=</td><td class="c017"> (<span class="c004">A</span> … <span class="c004">Z</span>) { <a class="syntax" href="#letter"><span class="c010">letter</span></a> ∣  <span class="c004">0</span> … <span class="c004">9</span> ∣  <span class="c004">_</span> ∣  <span class="c004">'</span> }  </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="lowercase-ident"><span class="c010">lowercase-ident</span></a></td><td class="c015">::=</td><td class="c017">
(<span class="c004">a</span> … <span class="c004">z</span> ∣  <span class="c004">_</span>) { <a class="syntax" href="#letter"><span class="c010">letter</span></a> ∣  <span class="c004">0</span> … <span class="c004">9</span> ∣  <span class="c004">_</span> ∣  <span class="c004">'</span> }  </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="letter"><span class="c010">letter</span></a></td><td class="c015">::=</td><td class="c017"> <span class="c004">A</span> … <span class="c004">Z</span> ∣  <span class="c004">a</span> … <span class="c004">z</span>
</td></tr>
</table></td></tr>
</table></div><p>Identifiers are sequences of letters, digits, <span class="c003">_</span> (the underscore
character), and <span class="c003">'</span> (the single quote), starting with a
letter or an underscore.
Letters contain at least the 52 lowercase and uppercase
letters from the ASCII set. The current implementation
also recognizes as letters some characters from the ISO
8859-1 set (characters 192–214 and 216–222 as uppercase letters;
characters 223–246 and 248–255 as lowercase letters). This
feature is deprecated and should be avoided for future compatibility.</p><p>All characters in an identifier are
meaningful. The current implementation accepts identifiers up to
16000000 characters in length.</p><p>In many places, OCaml makes a distinction between capitalized
identifiers and identifiers that begin with a lowercase letter. The
underscore character is considered a lowercase letter for this
purpose.</p><!--TOC subsubsection id="sss:integer-literals" Integer literals-->
<h4 class="subsubsection" id="sss:integer-literals"><a class="section-anchor" href="#sss:integer-literals" aria-hidden="true"></a>Integer literals</h4><!--SEC END --><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="integer-literal"><span class="c010">integer-literal</span></a></td><td class="c015">::=</td><td class="c017">
[<span class="c004">-</span>] (<span class="c004">0</span>…<span class="c004">9</span>) { <span class="c004">0</span>…<span class="c004">9</span> ∣  <span class="c004">_</span> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [<span class="c004">-</span>] (<span class="c004">0x</span>∣ <span class="c004">0X</span>) (<span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span>)
{ <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span>∣ <span class="c004">_</span> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [<span class="c004">-</span>] (<span class="c004">0o</span>∣ <span class="c004">0O</span>) (<span class="c004">0</span>…<span class="c004">7</span>) { <span class="c004">0</span>…<span class="c004">7</span>∣ <span class="c004">_</span> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [<span class="c004">-</span>] (<span class="c004">0b</span>∣ <span class="c004">0B</span>) (<span class="c004">0</span>…<span class="c004">1</span>) { <span class="c004">0</span>…<span class="c004">1</span>∣ <span class="c004">_</span> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="int32-literal"><span class="c010">int32-literal</span></a></td><td class="c015">::=</td><td class="c017"> <a class="syntax" href="#integer-literal"><span class="c010">integer-literal</span></a> <span class="c004">l</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="int64-literal"><span class="c010">int64-literal</span></a></td><td class="c015">::=</td><td class="c017"> <a class="syntax" href="#integer-literal"><span class="c010">integer-literal</span></a> <span class="c004">L</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="nativeint-literal"><span class="c010">nativeint-literal</span></a></td><td class="c015">::=</td><td class="c017"> <a class="syntax" href="#integer-literal"><span class="c010">integer-literal</span></a> <span class="c004">n</span>
</td></tr>
</table></td></tr>
</table></div><p>An integer literal is a sequence of one or more digits, optionally
preceded by a minus sign. By default, integer literals are in decimal
(radix 10). The following prefixes select a different radix:
</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Prefix</span></td><td class="c014"><span class="c013">Radix</span> </td></tr>
<tr><td class="c016">
<span class="c003">0x</span>, <span class="c003">0X</span></td><td class="c016">hexadecimal (radix 16) </td></tr>
<tr><td class="c016"><span class="c003">0o</span>, <span class="c003">0O</span></td><td class="c016">octal (radix 8) </td></tr>
<tr><td class="c016"><span class="c003">0b</span>, <span class="c003">0B</span></td><td class="c016">binary (radix 2) </td></tr>
</table></div></div><p>
(The initial <span class="c004">0</span> is the digit zero; the <span class="c004">O</span> for octal is the letter O.)
An integer literal can be followed by one of the letters <span class="c003">l</span>, <span class="c003">L</span> or <span class="c003">n</span>
to indicate that this integer has type <span class="c003">int32</span>, <span class="c003">int64</span> or <span class="c003">nativeint</span>
respectively, instead of the default type <span class="c003">int</span> for integer literals.
The interpretation of integer literals that fall outside the range of
representable integer values is undefined.</p><p>For convenience and readability, underscore characters (<span class="c004">_</span>) are accepted
(and ignored) within integer literals.</p><!--TOC subsubsection id="sss:floating-point-literals" Floating-point literals-->
<h4 class="subsubsection" id="sss:floating-point-literals"><a class="section-anchor" href="#sss:floating-point-literals" aria-hidden="true"></a>Floating-point literals</h4><!--SEC END --><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="float-literal"><span class="c010">float-literal</span></a></td><td class="c015">::=</td><td class="c017">
[<span class="c004">-</span>] (<span class="c004">0</span>…<span class="c004">9</span>) { <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">_</span> } [<span class="c004">.</span> { <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">_</span> }]
[(<span class="c004">e</span>∣ <span class="c004">E</span>) [<span class="c004">+</span>∣ <span class="c004">-</span>] (<span class="c004">0</span>…<span class="c004">9</span>) { <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">_</span> }]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [<span class="c004">-</span>] (<span class="c004">0x</span>∣ <span class="c004">0X</span>)
(<span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span>)
{ <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span>∣ <span class="c004">_</span> } 
[<span class="c004">.</span> { <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span>∣ <span class="c004">_</span> }]
[(<span class="c004">p</span>∣ <span class="c004">P</span>) [<span class="c004">+</span>∣ <span class="c004">-</span>] (<span class="c004">0</span>…<span class="c004">9</span>) { <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">_</span> }]
</td></tr>
</table></td></tr>
</table></div><p>Floating-point decimal literals consist in an integer part, a
fractional part and
an exponent part. The integer part is a sequence of one or more
digits, optionally preceded by a minus sign. The fractional part is a
decimal point followed by zero, one or more digits.
The exponent part is the character <span class="c004">e</span> or <span class="c004">E</span> followed by an
optional <span class="c004">+</span> or <span class="c004">-</span> sign, followed by one or more digits. It is
interpreted as a power of 10.
The fractional part or the exponent part can be omitted but not both, to
avoid ambiguity with integer literals.
The interpretation of floating-point literals that fall outside the
range of representable floating-point values is undefined.</p><p>Floating-point hexadecimal literals are denoted with the <span class="c004">0x</span> or <span class="c004">0X</span>
prefix. The syntax is similar to that of floating-point decimal
literals, with the following differences.
The integer part and the fractional part use hexadecimal
digits. The exponent part starts with the character <span class="c004">p</span> or <span class="c004">P</span>.
It is written in decimal and interpreted as a power of 2.</p><p>For convenience and readability, underscore characters (<span class="c004">_</span>) are accepted
(and ignored) within floating-point literals.</p><!--TOC subsubsection id="sss:character-literals" Character literals-->
<h4 class="subsubsection" id="sss:character-literals"><a class="section-anchor" href="#sss:character-literals" aria-hidden="true"></a>Character literals</h4><!--SEC END --><p>
<a id="s:characterliteral"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="char-literal"><span class="c010">char-literal</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">'</span> <span class="c010">regular-char</span> <span class="c004">'</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">'</span> <a class="syntax" href="#escape-sequence"><span class="c010">escape-sequence</span></a> <span class="c004">'</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="escape-sequence"><span class="c010">escape-sequence</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">\</span> ( <span class="c004">\</span> ∣  <span class="c004">"</span> ∣  <span class="c004">'</span> ∣  <span class="c004">n</span> ∣  <span class="c004">t</span> ∣  <span class="c004">b</span> ∣  <span class="c004">r</span> ∣  <span class="c010">space</span> )
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">\</span> (<span class="c004">0</span>…<span class="c004">9</span>) (<span class="c004">0</span>…<span class="c004">9</span>) (<span class="c004">0</span>…<span class="c004">9</span>)
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">\x</span> (<span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span>)
(<span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span>)
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">\o</span> (<span class="c004">0</span>…<span class="c004">3</span>) (<span class="c004">0</span>…<span class="c004">7</span>) (<span class="c004">0</span>…<span class="c004">7</span>)
</td></tr>
</table></td></tr>
</table></div><p>Character literals are delimited by <span class="c004">'</span> (single quote) characters.
The two single quotes enclose either one character different from
<span class="c004">'</span> and <span class="c004">\</span>, or one of the escape sequences below:
</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Sequence</span></td><td class="c014"><span class="c013">Character denoted</span> </td></tr>
<tr><td class="c016">
<span class="c003">\\</span></td><td class="c016">backslash (<span class="c003">\</span>) </td></tr>
<tr><td class="c016"><span class="c003">\"</span></td><td class="c016">double quote (<span class="c003">"</span>) </td></tr>
<tr><td class="c016"><span class="c003">\'</span></td><td class="c016">single quote (<span class="c003">'</span>) </td></tr>
<tr><td class="c016"><span class="c003">\n</span></td><td class="c016">linefeed (LF) </td></tr>
<tr><td class="c016"><span class="c003">\r</span></td><td class="c016">carriage return (CR) </td></tr>
<tr><td class="c016"><span class="c003">\t</span></td><td class="c016">horizontal tabulation (TAB) </td></tr>
<tr><td class="c016"><span class="c003">\b</span></td><td class="c016">backspace (BS) </td></tr>
<tr><td class="c016"><span class="c003">\</span><span class="c009">space</span></td><td class="c016">space (SPC) </td></tr>
<tr><td class="c016"><span class="c003">\</span><span class="c009">ddd</span></td><td class="c016">the character with ASCII code <span class="c009">ddd</span> in decimal </td></tr>
<tr><td class="c016"><span class="c003">\x</span><span class="c009">hh</span></td><td class="c016">the character with ASCII code <span class="c009">hh</span> in hexadecimal </td></tr>
<tr><td class="c016"><span class="c003">\o</span><span class="c009">ooo</span></td><td class="c016">the character with ASCII code <span class="c009">ooo</span> in octal </td></tr>
</table></div></div><!--TOC subsubsection id="sss:stringliterals" String literals-->
<h4 class="subsubsection" id="sss:stringliterals"><a class="section-anchor" href="#sss:stringliterals" aria-hidden="true"></a>String literals</h4><!--SEC END --><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="string-literal"><span class="c010">string-literal</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">"</span> { <a class="syntax" href="#string-character"><span class="c010">string-character</span></a> } <span class="c004">"</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">{</span> <a class="syntax" href="#quoted-string-id"><span class="c010">quoted-string-id</span></a> <span class="c004">|</span>   { <span class="c010">any-char</span> } <span class="c004">|</span>  <a class="syntax" href="#quoted-string-id"><span class="c010">quoted-string-id</span></a> <span class="c004">}</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="quoted-string-id"><span class="c010">quoted-string-id</span></a></td><td class="c015">::=</td><td class="c017">
{ <span class="c004">a</span>...<span class="c004">z</span> ∣  <span class="c004">_</span> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="string-character"><span class="c010">string-character</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c010">regular-string-char</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#escape-sequence"><span class="c010">escape-sequence</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">\u{</span> { <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span> }<sup>+</sup> <span class="c004">}</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">\</span> <span class="c010">newline</span>  { <span class="c010">space</span> ∣  <span class="c010">tab</span> }
</td></tr>
</table></td></tr>
</table></div><p>String literals are delimited by <span class="c004">"</span> (double quote) characters.
The two double quotes enclose a sequence of either characters
different from <span class="c004">"</span> and <span class="c004">\</span>, or escape sequences from the
table given above for character literals, or a Unicode character
escape sequence.</p><p>A Unicode character escape sequence is substituted by the UTF-8
encoding of the specified Unicode scalar value. The Unicode scalar
value, an integer in the ranges 0x0000...0xD7FF or 0xE000...0x10FFFF,
is defined using 1 to 6 hexadecimal digits; leading zeros are allowed.</p><p>To allow splitting long string literals across lines, the sequence
<span class="c003">\</span><span class="c009">newline</span> <span class="c009">spaces-or-tabs</span> (a backslash at the end of a line
followed by any number of spaces and horizontal tabulations at the
beginning of the next line) is ignored inside string literals.</p><p>Quoted string literals provide an alternative lexical syntax for
string literals. They are useful to represent strings of arbitrary content
without escaping. Quoted strings are delimited by a matching pair
of <span class="c004">{</span> <a class="syntax" href="#quoted-string-id"><span class="c010">quoted-string-id</span></a> <span class="c004">|</span> and <span class="c004">|</span> <a class="syntax" href="#quoted-string-id"><span class="c010">quoted-string-id</span></a> <span class="c004">}</span> with
the same <a class="syntax" href="#quoted-string-id"><span class="c010">quoted-string-id</span></a> on both sides. Quoted strings do not interpret
any character in a special way but requires that the
sequence <span class="c004">|</span> <a class="syntax" href="#quoted-string-id"><span class="c010">quoted-string-id</span></a> <span class="c004">}</span> does not occur in the string itself.
The identifier <a class="syntax" href="#quoted-string-id"><span class="c010">quoted-string-id</span></a> is a (possibly empty) sequence of
lowercase letters and underscores that can be freely chosen to avoid
such issue (e.g. <span class="c003">{|hello|}</span>, <span class="c003">{ext|hello {|world|}|ext}</span>, ...).</p><p>The current implementation places practically no restrictions on the
length of string literals.</p><!--TOC subsubsection id="sss:labelname" Naming labels-->
<h4 class="subsubsection" id="sss:labelname"><a class="section-anchor" href="#sss:labelname" aria-hidden="true"></a>Naming labels</h4><!--SEC END --><p>To avoid ambiguities, naming labels in expressions cannot just be defined
syntactically as the sequence of the three tokens <span class="c003">~</span>, <a class="syntax" href="#ident"><span class="c010">ident</span></a> and
<span class="c003">:</span>, and have to be defined at the lexical level.</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="label-name"><span class="c010">label-name</span></a></td><td class="c015">::=</td><td class="c017"> <a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="label"><span class="c010">label</span></a></td><td class="c015">::=</td><td class="c017"> <span class="c004">~</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a> <span class="c004">:</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="optlabel"><span class="c010">optlabel</span></a></td><td class="c015">::=</td><td class="c017"> <span class="c004">?</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a> <span class="c004">:</span>
</td></tr>
</table></td></tr>
</table></div><p>Naming labels come in two flavours: <a class="syntax" href="#label"><span class="c010">label</span></a> for normal arguments and
<a class="syntax" href="#optlabel"><span class="c010">optlabel</span></a> for optional ones. They are simply distinguished by their
first character, either <span class="c003">~</span> or <span class="c003">?</span>.</p><p>Despite <a class="syntax" href="#label"><span class="c010">label</span></a> and <a class="syntax" href="#optlabel"><span class="c010">optlabel</span></a> being lexical entities in expressions,
their expansions <span class="c004">~</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a> <span class="c004">:</span> and <span class="c004">?</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a> <span class="c004">:</span> will be
used in grammars, for the sake of readability. Note also that inside
type expressions, this expansion can be taken literally, <em>i.e.</em>
there are really 3 tokens, with optional blanks between them.</p><!--TOC subsubsection id="sss:lex-ops-symbols" Prefix and infix symbols-->
<h4 class="subsubsection" id="sss:lex-ops-symbols"><a class="section-anchor" href="#sss:lex-ops-symbols" aria-hidden="true"></a>Prefix and infix symbols</h4><!--SEC END --><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="infix-symbol"><span class="c010">infix-symbol</span></a></td><td class="c015">::=</td><td class="c017">
( <a class="syntax" href="#core-operator-char"><span class="c010">core-operator-char</span></a> ∣  <span class="c004">%</span> ∣  <span class="c004">&lt;</span> ) { <a class="syntax" href="#operator-char"><span class="c010">operator-char</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">#</span> { <a class="syntax" href="#operator-char"><span class="c010">operator-char</span></a> }<sup>+</sup>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="prefix-symbol"><span class="c010">prefix-symbol</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">!</span> { <a class="syntax" href="#operator-char"><span class="c010">operator-char</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> (<span class="c004">?</span> ∣  <span class="c004">~</span>) { <a class="syntax" href="#operator-char"><span class="c010">operator-char</span></a> }<sup>+</sup>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="operator-char"><span class="c010">operator-char</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">~</span> ∣  <span class="c004">!</span> ∣  <span class="c004">?</span> ∣  <a class="syntax" href="#core-operator-char"><span class="c010">core-operator-char</span></a> ∣  <span class="c004">%</span> ∣  <span class="c004">&lt;</span> ∣  <span class="c004">:</span> ∣  <span class="c004">.</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="core-operator-char"><span class="c010">core-operator-char</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">$</span> ∣  <span class="c004">&amp;</span> ∣  <span class="c004">*</span> ∣  <span class="c004">+</span> ∣  <span class="c004">-</span> ∣  <span class="c004">/</span> ∣  <span class="c004">=</span> ∣  <span class="c004">&gt;</span> ∣  <span class="c004">@</span> ∣  <span class="c004">^</span> ∣  <span class="c004">|</span>
</td></tr>
</table></td></tr>
</table></div><p>
See also the following language extensions:
<a href="#s%3Aext-ops">extension operators</a>,
<a href="#s%3Aindex-operators">extended indexing operators</a>,
and <a href="#s%3Abinding-operators">binding operators</a>.</p><p>Sequences of “operator characters”, such as <span class="c003">&lt;=&gt;</span> or <span class="c003">!!</span>,
are read as a single token from the <a class="syntax" href="#infix-symbol"><span class="c010">infix-symbol</span></a> or <a class="syntax" href="#prefix-symbol"><span class="c010">prefix-symbol</span></a>
class. These symbols are parsed as prefix and infix operators inside
expressions, but otherwise behave like normal identifiers.
</p><!--TOC subsubsection id="sss:keywords" Keywords-->
<h4 class="subsubsection" id="sss:keywords"><a class="section-anchor" href="#sss:keywords" aria-hidden="true"></a>Keywords</h4><!--SEC END --><p>The identifiers below are reserved as keywords, and cannot be employed
otherwise:
</p><pre>      and         as          assert      asr         begin       class
      constraint  do          done        downto      else        end
      exception   external    false       for         fun         function
      functor     if          in          include     inherit     initializer
      land        lazy        let         lor         lsl         lsr
      lxor        match       method      mod         module      mutable
      new         nonrec      object      of          open        or
      private     rec         sig         struct      then        to
      true        try         type        val         virtual     when
      while       with
</pre><p> <br>
The following character sequences are also keywords:
</p><pre>
<span class="c003">    !=    #     &amp;     &amp;&amp;    '     (     )     *     +     ,     -</span>
<span class="c003">    -.    -&gt;    .     ..    .~    :     ::    :=    :&gt;    ;     ;;</span>
<span class="c003">    &lt;     &lt;-    =     &gt;     &gt;]    &gt;}    ?     [     [&lt;    [&gt;    [|</span>
<span class="c003">    ]     _     `     {     {&lt;    |     |]    ||    }     ~</span>
</pre><p>
Note that the following identifiers are keywords of the Camlp4
extensions and should be avoided for compatibility reasons.
</p><pre>    parser    value    $     $$    $:    &lt;:    &lt;&lt;    &gt;&gt;    ??
</pre><!--TOC subsubsection id="sss:lex-ambiguities" Ambiguities-->
<h4 class="subsubsection" id="sss:lex-ambiguities"><a class="section-anchor" href="#sss:lex-ambiguities" aria-hidden="true"></a>Ambiguities</h4><!--SEC END --><p>Lexical ambiguities are resolved according to the “longest match”
rule: when a character sequence can be decomposed into two tokens in
several different ways, the decomposition retained is the one with the
longest first token.</p><!--TOC subsubsection id="sss:lex-linedir" Line number directives-->
<h4 class="subsubsection" id="sss:lex-linedir"><a class="section-anchor" href="#sss:lex-linedir" aria-hidden="true"></a>Line number directives</h4><!--SEC END --><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="linenum-directive"><span class="c010">linenum-directive</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">#</span> {<span class="c004">0</span> … <span class="c004">9</span>}<sup>+</sup>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">#</span> {<span class="c004">0</span> … <span class="c004">9</span>}<sup>+</sup> <span class="c004">"</span> { <a class="syntax" href="#string-character"><span class="c010">string-character</span></a> } <span class="c004">"</span>
</td></tr>
</table></td></tr>
</table></div><p>Preprocessors that generate OCaml source code can insert line number
directives in their output so that error messages produced by the
compiler contain line numbers and file names referring to the source
file before preprocessing, instead of after preprocessing.
A line number directive is composed of a <span class="c004">#</span> (sharp sign), followed by
a positive integer (the source line number), optionally followed by a
character string (the source file name).
Line number directives are treated as blanks during lexical
analysis.</p>
<!--TOC section id="s:values" 7.2  Values-->
<h2 class="section" id="s:values"><a class="section-anchor" href="#s:values" aria-hidden="true"></a>7.2  Values</h2><!--SEC END --><!--NAME values.html-->
<p>This section describes the kinds of values that are manipulated by
OCaml programs.</p>
<!--TOC subsection id="ss:values:base" 7.2.1  Base values-->
<h3 class="subsection" id="ss:values:base"><a class="section-anchor" href="#ss:values:base" aria-hidden="true"></a>7.2.1  Base values</h3><!--SEC END --><!--TOC subsubsection id="sss:values:integer" Integer numbers-->
<h4 class="subsubsection" id="sss:values:integer"><a class="section-anchor" href="#sss:values:integer" aria-hidden="true"></a>Integer numbers</h4><!--SEC END --><p>Integer values are integer numbers from −2<sup>30</sup> to 2<sup>30</sup>−1, that
is −1073741824 to 1073741823. The implementation may support a
wider range of integer values: on 64-bit platforms, the current
implementation supports integers ranging from −2<sup>62</sup> to 2<sup>62</sup>−1.</p><!--TOC subsubsection id="sss:values:float" Floating-point numbers-->
<h4 class="subsubsection" id="sss:values:float"><a class="section-anchor" href="#sss:values:float" aria-hidden="true"></a>Floating-point numbers</h4><!--SEC END --><p>Floating-point values are numbers in floating-point representation.
The current implementation uses double-precision floating-point
numbers conforming to the IEEE 754 standard, with 53 bits of mantissa
and an exponent ranging from −1022 to 1023.</p><!--TOC subsubsection id="sss:values:char" Characters-->
<h4 class="subsubsection" id="sss:values:char"><a class="section-anchor" href="#sss:values:char" aria-hidden="true"></a>Characters</h4><!--SEC END --><p>Character values are represented as 8-bit integers between 0 and 255.
Character codes between 0 and 127 are interpreted following the ASCII
standard. The current implementation interprets character codes
between 128 and 255 following the ISO 8859-1 standard.</p><!--TOC subsubsection id="sss:values:string" Character strings-->
<h4 class="subsubsection" id="sss:values:string"><a class="section-anchor" href="#sss:values:string" aria-hidden="true"></a>Character strings</h4><!--SEC END --><p>String values are finite sequences of characters. The current
implementation supports strings containing up to 2<sup>24</sup> − 5
characters (16777211 characters); on 64-bit platforms, the limit is
2<sup>57</sup> − 9.</p>
<!--TOC subsection id="ss:values:tuple" 7.2.2  Tuples-->
<h3 class="subsection" id="ss:values:tuple"><a class="section-anchor" href="#ss:values:tuple" aria-hidden="true"></a>7.2.2  Tuples</h3><!--SEC END --><p>Tuples of values are written <span class="c004">(</span><span class="c010">v</span><sub>1</sub><span class="c004">,</span> …<span class="c004">,</span> <span class="c010">v</span><sub><span class="c009">n</span></sub><span class="c004">)</span>, standing for the
<span class="c009">n</span>-tuple of values <span class="c010">v</span><sub>1</sub> to <span class="c010">v</span><sub><span class="c009">n</span></sub>. The current implementation
supports tuple of up to 2<sup>22</sup> − 1 elements (4194303 elements).</p>
<!--TOC subsection id="ss:values:records" 7.2.3  Records-->
<h3 class="subsection" id="ss:values:records"><a class="section-anchor" href="#ss:values:records" aria-hidden="true"></a>7.2.3  Records</h3><!--SEC END --><p>Record values are labeled tuples of values. The record value written
<span class="c004">{</span> <a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub> <span class="c004">=</span> <span class="c010">v</span><sub>1</sub><span class="c004">;</span> …<span class="c004">;</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">n</span></sub> <span class="c004">=</span> <span class="c010">v</span><sub><span class="c009">n</span></sub> <span class="c004">}</span> associates the value
<span class="c010">v</span><sub><span class="c009">i</span></sub> to the record field <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">i</span></sub>, for <span class="c009">i</span> = 1 … <span class="c009">n</span>. The current
implementation supports records with up to 2<sup>22</sup> − 1 fields
(4194303 fields).</p>
<!--TOC subsection id="ss:values:array" 7.2.4  Arrays-->
<h3 class="subsection" id="ss:values:array"><a class="section-anchor" href="#ss:values:array" aria-hidden="true"></a>7.2.4  Arrays</h3><!--SEC END --><p>Arrays are finite, variable-sized sequences of values of the same
type. The current implementation supports arrays containing up to
2<sup>22</sup> − 1 elements (4194303 elements) unless the elements are
floating-point numbers (2097151 elements in this case); on 64-bit
platforms, the limit is 2<sup>54</sup> − 1 for all arrays.</p>
<!--TOC subsection id="ss:values:variant" 7.2.5  Variant values-->
<h3 class="subsection" id="ss:values:variant"><a class="section-anchor" href="#ss:values:variant" aria-hidden="true"></a>7.2.5  Variant values</h3><!--SEC END --><p>Variant values are either a constant constructor, or a non-constant
constructor applied to a number of values. The former case is written
<a class="syntax" href="#constr"><span class="c010">constr</span></a>; the latter case is written <a class="syntax" href="#constr"><span class="c010">constr</span></a> <span class="c004">(</span><span class="c010">v</span><sub>1</sub><span class="c004">,</span> ... <span class="c004">,</span> <span class="c010">v</span><sub><span class="c009">n</span></sub>
<span class="c004">)</span>, where the <span class="c010">v</span><sub><span class="c009">i</span></sub> are said to be the arguments of the non-constant
constructor <a class="syntax" href="#constr"><span class="c010">constr</span></a>. The parentheses may be omitted if there is only
one argument.</p><p>The following constants are treated like built-in constant
constructors:
</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Constant</span></td><td class="c014"><span class="c013">Constructor</span> </td></tr>
<tr><td class="c016">
<span class="c003">false</span></td><td class="c016">the boolean false </td></tr>
<tr><td class="c016"><span class="c003">true</span></td><td class="c016">the boolean true </td></tr>
<tr><td class="c016"><span class="c003">()</span></td><td class="c016">the “unit” value </td></tr>
<tr><td class="c016"><span class="c003">[]</span></td><td class="c016">the empty list </td></tr>
</table></div></div><p>The current implementation limits each variant type to have at most
246 non-constant constructors and 2<sup>30</sup>−1 constant constructors.</p>
<!--TOC subsection id="ss:values:polyvars" 7.2.6  Polymorphic variants-->
<h3 class="subsection" id="ss:values:polyvars"><a class="section-anchor" href="#ss:values:polyvars" aria-hidden="true"></a>7.2.6  Polymorphic variants</h3><!--SEC END --><p>Polymorphic variants are an alternate form of variant values, not
belonging explicitly to a predefined variant type, and following
specific typing rules. They can be either constant, written
<span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>, or non-constant, written <span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a><span class="c002"><span class="c003">(</span><span class="c010">v</span><span class="c003">)</span></span>.</p>
<!--TOC subsection id="ss:values:fun" 7.2.7  Functions-->
<h3 class="subsection" id="ss:values:fun"><a class="section-anchor" href="#ss:values:fun" aria-hidden="true"></a>7.2.7  Functions</h3><!--SEC END --><p>Functional values are mappings from values to values.</p>
<!--TOC subsection id="ss:values:obj" 7.2.8  Objects-->
<h3 class="subsection" id="ss:values:obj"><a class="section-anchor" href="#ss:values:obj" aria-hidden="true"></a>7.2.8  Objects</h3><!--SEC END --><p>Objects are composed of a hidden internal state which is a
record of instance variables, and a set of methods for accessing and
modifying these variables. The structure of an object is described by
the toplevel class that created it.

</p>
<!--TOC section id="s:names" 7.3  Names-->
<h2 class="section" id="s:names"><a class="section-anchor" href="#s:names" aria-hidden="true"></a>7.3  Names</h2><!--SEC END --><!--NAME names.html-->
<p>Identifiers are used to give names to several classes of language
objects and refer to these objects by name later:
</p><ul class="itemize"><li class="li-itemize">
value names (syntactic class <a class="syntax" href="#value-name"><span class="c010">value-name</span></a>),
</li><li class="li-itemize">value constructors and exception constructors (class <a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a>),
</li><li class="li-itemize">labels (<a class="syntax" href="#label-name"><span class="c010">label-name</span></a>, defined in section <a href="#sss%3Alabelname">7.1</a>),
</li><li class="li-itemize">polymorphic variant tags (<a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>),
</li><li class="li-itemize">type constructors (<a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a>),
</li><li class="li-itemize">record fields (<a class="syntax" href="#field-name"><span class="c010">field-name</span></a>),
</li><li class="li-itemize">class names (<a class="syntax" href="#class-name"><span class="c010">class-name</span></a>),
</li><li class="li-itemize">method names (<a class="syntax" href="#method-name"><span class="c010">method-name</span></a>),
</li><li class="li-itemize">instance variable names (<a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a>),
</li><li class="li-itemize">module names (<a class="syntax" href="#module-name"><span class="c010">module-name</span></a>),
</li><li class="li-itemize">module type names (<a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a>).
</li></ul><p>
These eleven name spaces are distinguished both by the context and by the
capitalization of the identifier: whether the first letter of the
identifier is in lowercase (written <a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a> below) or in
uppercase (written <a class="syntax" href="#capitalized-ident"><span class="c010">capitalized-ident</span></a>). Underscore is considered a
lowercase letter for this purpose.</p><!--TOC subsubsection id="sss:naming-objects" Naming objects-->
<h4 class="subsubsection" id="sss:naming-objects"><a class="section-anchor" href="#sss:naming-objects" aria-hidden="true"></a>Naming objects</h4><!--SEC END --><p>
<a id="hevea_manual.kwd0"></a>
<a id="hevea_manual.kwd1"></a>
<a id="hevea_manual.kwd2"></a>
<a id="hevea_manual.kwd3"></a>
<a id="hevea_manual.kwd4"></a>
<a id="hevea_manual.kwd5"></a>
<a id="hevea_manual.kwd6"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="value-name"><span class="c010">value-name</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#operator-name"><span class="c010">operator-name</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="operator-name"><span class="c010">operator-name</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#prefix-symbol"><span class="c010">prefix-symbol</span></a> ∣  <a class="syntax" href="#infix-op"><span class="c010">infix-op</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="infix-op"><span class="c010">infix-op</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#infix-symbol"><span class="c010">infix-symbol</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">*</span> ∣  <span class="c004">+</span> ∣  <span class="c004">-</span> ∣  <span class="c004">-.</span> ∣  <span class="c004">=</span> ∣  <span class="c004">!=</span> ∣  <span class="c004">&lt;</span> ∣  <span class="c004">&gt;</span> ∣  <span class="c004">or</span> ∣  <span class="c004">||</span>
∣  <span class="c004">&amp;</span> ∣  <span class="c004">&amp;&amp;</span> ∣  <span class="c004">:=</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">mod</span> ∣  <span class="c004">land</span> ∣  <span class="c004">lor</span> ∣  <span class="c004">lxor</span> ∣  <span class="c004">lsl</span> ∣  <span class="c004">lsr</span> ∣  <span class="c004">asr</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="constr-name"><span class="c010">constr-name</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#capitalized-ident"><span class="c010">capitalized-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="tag-name"><span class="c010">tag-name</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#capitalized-ident"><span class="c010">capitalized-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="typeconstr-name"><span class="c010">typeconstr-name</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="field-name"><span class="c010">field-name</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="module-name"><span class="c010">module-name</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#capitalized-ident"><span class="c010">capitalized-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="modtype-name"><span class="c010">modtype-name</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#ident"><span class="c010">ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="class-name"><span class="c010">class-name</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="inst-var-name"><span class="c010">inst-var-name</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="method-name"><span class="c010">method-name</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>
</td></tr>
</table></td></tr>
</table></div><p>
See also the following language extension:
<a href="#s%3Aindex-operators">extended indexing operators</a>.</p><p>As shown above, prefix and infix symbols as well as some keywords can
be used as value names, provided they are written between parentheses.
The capitalization rules are summarized in the table below.</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Name space</span></td><td class="c014"><span class="c013">Case of first letter</span> </td></tr>
<tr><td class="c016">
Values</td><td class="c016">lowercase </td></tr>
<tr><td class="c016">Constructors</td><td class="c016">uppercase </td></tr>
<tr><td class="c016">Labels</td><td class="c016">lowercase </td></tr>
<tr><td class="c016">Polymorphic variant tags</td><td class="c016">uppercase </td></tr>
<tr><td class="c016">Exceptions</td><td class="c016">uppercase </td></tr>
<tr><td class="c016">Type constructors</td><td class="c016">lowercase </td></tr>
<tr><td class="c016">Record fields</td><td class="c016">lowercase </td></tr>
<tr><td class="c016">Classes</td><td class="c016">lowercase </td></tr>
<tr><td class="c016">Instance variables</td><td class="c016">lowercase </td></tr>
<tr><td class="c016">Methods</td><td class="c016">lowercase </td></tr>
<tr><td class="c016">Modules</td><td class="c016">uppercase </td></tr>
<tr><td class="c016">Module types</td><td class="c016">any </td></tr>
</table></div></div><p><span class="c009">Note on polymorphic variant tags:</span> the current implementation accepts
lowercase variant tags in addition to capitalized variant tags, but we
suggest you avoid lowercase variant tags for portability and
compatibility with future OCaml versions.</p><!--TOC subsubsection id="sss:refer-named" Referring to named objects-->
<h4 class="subsubsection" id="sss:refer-named"><a class="section-anchor" href="#sss:refer-named" aria-hidden="true"></a>Referring to named objects</h4><!--SEC END --><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="value-path"><span class="c010">value-path</span></a></td><td class="c015">::=</td><td class="c017">
[ <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span> ]  <a class="syntax" href="#value-name"><span class="c010">value-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="constr"><span class="c010">constr</span></a></td><td class="c015">::=</td><td class="c017">
[ <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span> ]  <a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="typeconstr"><span class="c010">typeconstr</span></a></td><td class="c015">::=</td><td class="c017">
[ <a class="syntax" href="#extended-module-path"><span class="c010">extended-module-path</span></a> <span class="c004">.</span> ]  <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="field"><span class="c010">field</span></a></td><td class="c015">::=</td><td class="c017">
[ <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span> ]  <a class="syntax" href="#field-name"><span class="c010">field-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="modtype-path"><span class="c010">modtype-path</span></a></td><td class="c015">::=</td><td class="c017">
[ <a class="syntax" href="#extended-module-path"><span class="c010">extended-module-path</span></a> <span class="c004">.</span> ]  <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="class-path"><span class="c010">class-path</span></a></td><td class="c015">::=</td><td class="c017">
[ <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span> ]  <a class="syntax" href="#class-name"><span class="c010">class-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="classtype-path"><span class="c010">classtype-path</span></a></td><td class="c015">::=</td><td class="c017">
[ <a class="syntax" href="#extended-module-path"><span class="c010">extended-module-path</span></a> <span class="c004">.</span> ]  <a class="syntax" href="#class-name"><span class="c010">class-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="module-path"><span class="c010">module-path</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#module-name"><span class="c010">module-name</span></a>  { <span class="c004">.</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="extended-module-path"><span class="c010">extended-module-path</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#extended-module-name"><span class="c010">extended-module-name</span></a>  { <span class="c004">.</span> <a class="syntax" href="#extended-module-name"><span class="c010">extended-module-name</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="extended-module-name"><span class="c010">extended-module-name</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#module-name"><span class="c010">module-name</span></a>  { <span class="c004">(</span> <a class="syntax" href="#extended-module-path"><span class="c010">extended-module-path</span></a> <span class="c004">)</span> }
</td></tr>
</table></td></tr>
</table></div><p>A named object can be referred to either by its name (following the
usual static scoping rules for names) or by an access path <span class="c010">prefix</span> <span class="c004">.</span>  <span class="c010">name</span>,
where <span class="c010">prefix</span> designates a module and <span class="c010">name</span> is the name of an object
defined in that module. The first component of the path, <span class="c010">prefix</span>, is
either a simple module name or an access path <span class="c010">name</span><sub>1</sub> <span class="c004">.</span>  <span class="c010">name</span><sub>2</sub> …,
in case the defining module is itself nested inside other modules.
For referring to type constructors, module types, or class types,
the <span class="c010">prefix</span> can
also contain simple functor applications (as in the syntactic class
<a class="syntax" href="#extended-module-path"><span class="c010">extended-module-path</span></a> above) in case the defining module is the
result of a functor application.</p><p>Label names, tag names, method names and instance variable names need
not be qualified: the former three are global labels, while the latter
are local to a class.

</p>
<!--TOC section id="s:typexpr" 7.4  Type expressions-->
<h2 class="section" id="s:typexpr"><a class="section-anchor" href="#s:typexpr" aria-hidden="true"></a>7.4  Type expressions</h2><!--SEC END --><!--NAME types.html-->
<p>
<a id="hevea_manual.kwd7"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="typexpr"><span class="c010">typexpr</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">'</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">_</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [[<span class="c004">?</span>]<a class="syntax" href="#label-name"><span class="c010">label-name</span></a><span class="c004">:</span>]  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">-&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  { <span class="c004">*</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> }<sup>+</sup>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  { <span class="c004">,</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> } <span class="c004">)</span>  <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">as</span> <span class="c004">'</span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#polymorphic-variant-type"><span class="c010">polymorphic-variant-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">&lt;</span> [<span class="c004">..</span>] <span class="c004">&gt;</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">&lt;</span> <a class="syntax" href="#method-type"><span class="c010">method-type</span></a>  { <span class="c004">;</span> <a class="syntax" href="#method-type"><span class="c010">method-type</span></a> }  [<span class="c004">;</span> ∣  <span class="c004">;</span> <span class="c004">..</span>] <span class="c004">&gt;</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">#</span> <a class="syntax" href="#classtype-path"><span class="c010">classtype-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">#</span>  <a class="syntax" href="#class-path"><span class="c010">class-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  { <span class="c004">,</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> } <span class="c004">)</span> <span class="c004">#</span>  <a class="syntax" href="#class-path"><span class="c010">class-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="poly-typexpr"><span class="c010">poly-typexpr</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> { <span class="c004">'</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a> }<sup>+</sup> <span class="c004">.</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="method-type"><span class="c010">method-type</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a>
</td></tr>
</table></td></tr>
</table></div><p>
See also the following language extensions:
<a href="#s%3Afirst-class-modules">first-class modules</a>,
<a href="#s%3Aattributes">attributes</a> and
<a href="#s%3Aextension-nodes">extension nodes</a>.</p><p>The table below shows the relative precedences and associativity of
operators and non-closed type constructions. The constructions with
higher precedences come first.
<a id="hevea_manual.kwd8"></a>
</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Operator</span></td><td class="c014"><span class="c013">Associativity</span> </td></tr>
<tr><td class="c016">
Type constructor application</td><td class="c016">– </td></tr>
<tr><td class="c016"><span class="c003">#</span></td><td class="c016">– </td></tr>
<tr><td class="c016"><span class="c003">*</span></td><td class="c016">– </td></tr>
<tr><td class="c016"><span class="c003">-&gt;</span></td><td class="c016">right </td></tr>
<tr><td class="c016"><span class="c003">as</span></td><td class="c016">– </td></tr>
</table></div></div><p>Type expressions denote types in definitions of data types as well as
in type constraints over patterns and expressions.</p><!--TOC subsubsection id="sss:typexpr-variables" Type variables-->
<h4 class="subsubsection" id="sss:typexpr-variables"><a class="section-anchor" href="#sss:typexpr-variables" aria-hidden="true"></a>Type variables</h4><!--SEC END --><p>The type expression <span class="c004">'</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a> stands for the type variable named
<a class="syntax" href="#ident"><span class="c010">ident</span></a>. The type expression <span class="c004">_</span> stands for either an anonymous type
variable or anonymous type parameters. In data type definitions, type
variables are names for the data type parameters. In type constraints,
they represent unspecified types that can be instantiated by any type
to satisfy the type constraint. In general the scope of a named type
variable is the whole top-level phrase where it appears, and it can
only be generalized when leaving this scope. Anonymous variables have
no such restriction. In the following cases, the scope of named type
variables is restricted to the type expression where they appear:
1) for universal (explicitly polymorphic) type variables;
2) for type variables that only appear in public method specifications
(as those variables will be made universal, as described in
section <a href="#sss%3Aclty-meth">7.9.1</a>);
3) for variables used as aliases, when the type they are aliased to
would be invalid in the scope of the enclosing definition (<span class="c009">i.e.</span>
when it contains free universal type variables, or locally
defined types.)</p><!--TOC subsubsection id="sss:typexr:parenthesized" Parenthesized types-->
<h4 class="subsubsection" id="sss:typexr:parenthesized"><a class="section-anchor" href="#sss:typexr:parenthesized" aria-hidden="true"></a>Parenthesized types</h4><!--SEC END --><p>The type expression <span class="c004">(</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">)</span> denotes the same type as
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>.</p><!--TOC subsubsection id="sss:typexr-fun" Function types-->
<h4 class="subsubsection" id="sss:typexr-fun"><a class="section-anchor" href="#sss:typexr-fun" aria-hidden="true"></a>Function types</h4><!--SEC END --><p>The type expression <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>2</sub> denotes the type of
functions mapping arguments of type <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> to results of type
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>2</sub>.</p><p><a class="syntax" href="#label-name"><span class="c010">label-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>2</sub> denotes the same function type, but
the argument is labeled <a class="syntax" href="#label"><span class="c010">label</span></a>.</p><p><span class="c004">?</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>2</sub> denotes the type of functions
mapping an optional labeled argument of type <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> to results of
type <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>2</sub>. That is, the physical type of the function will be
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c002"><span class="c003">option</span> <span class="c003">-&gt;</span></span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>2</sub>.</p><!--TOC subsubsection id="sss:typexpr-tuple" Tuple types-->
<h4 class="subsubsection" id="sss:typexpr-tuple"><a class="section-anchor" href="#sss:typexpr-tuple" aria-hidden="true"></a>Tuple types</h4><!--SEC END --><p>The type expression <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">*</span> … <span class="c004">*</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub>
denotes the type of tuples whose elements belong to types <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub>,
…  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub> respectively.</p><!--TOC subsubsection id="sss:typexpr-constructed" Constructed types-->
<h4 class="subsubsection" id="sss:typexpr-constructed"><a class="section-anchor" href="#sss:typexpr-constructed" aria-hidden="true"></a>Constructed types</h4><!--SEC END --><p>Type constructors with no parameter, as in <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>, are type
expressions.</p><p>The type expression <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>, where <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a> is a type
constructor with one parameter, denotes the application of the unary type
constructor <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a> to the type <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>.</p><p>The type expression (<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub>,…, <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub>)  <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>, where
<a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a> is a type constructor with <span class="c009">n</span> parameters, denotes the
application of the <span class="c009">n</span>-ary type constructor <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a> to the types
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> through <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub>.</p><p>In the type expression  <span class="c004">_</span> <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a> , the anonymous type expression
 <span class="c004">_</span>  stands in for anonymous type parameters and is equivalent to
 (<span class="c004">_</span>, …,<span class="c004">_</span>)  with as many repetitions of <span class="c003">_</span> as the arity of
<a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>.</p><!--TOC subsubsection id="sss:typexpr-aliased-recursive" Aliased and recursive types-->
<h4 class="subsubsection" id="sss:typexpr-aliased-recursive"><a class="section-anchor" href="#sss:typexpr-aliased-recursive" aria-hidden="true"></a>Aliased and recursive types</h4><!--SEC END --><p><a id="hevea_manual.kwd9"></a></p><p>The type expression <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c002"><span class="c003">as</span> <span class="c003">'</span></span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a> denotes the same type as
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>, and also binds the type variable <a class="syntax" href="#ident"><span class="c010">ident</span></a> to type <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> both
in <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> and in other types. In general the scope of an alias is
the same as for a named type variable, and covers the whole enclosing
definition. If the type variable
<a class="syntax" href="#ident"><span class="c010">ident</span></a> actually occurs in <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>, a recursive type is created. Recursive
types for which there exists a recursive path that does not contain
an object or polymorphic variant type constructor are rejected, except
when the <span class="c003">-rectypes</span> mode is selected.</p><p>If <span class="c004">'</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a> denotes an explicit polymorphic variable, and <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
denotes either an object or polymorphic variant type, the row variable
of <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> is captured by <span class="c004">'</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a>, and quantified upon.</p><!--TOC subsubsection id="sss:typexpr-polyvar" Polymorphic variant types-->
<h4 class="subsubsection" id="sss:typexpr-polyvar"><a class="section-anchor" href="#sss:typexpr-polyvar" aria-hidden="true"></a>Polymorphic variant types</h4><!--SEC END --><p>
<a id="hevea_manual.kwd10"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="polymorphic-variant-type"><span class="c010">polymorphic-variant-type</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">[</span> <a class="syntax" href="#tag-spec-first"><span class="c010">tag-spec-first</span></a>  { <span class="c004">|</span> <a class="syntax" href="#tag-spec"><span class="c010">tag-spec</span></a> } <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">[&gt;</span> [ <a class="syntax" href="#tag-spec"><span class="c010">tag-spec</span></a> ]  { <span class="c004">|</span> <a class="syntax" href="#tag-spec"><span class="c010">tag-spec</span></a> } <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">[&lt;</span> [<span class="c004">|</span>] <a class="syntax" href="#tag-spec-full"><span class="c010">tag-spec-full</span></a>  { <span class="c004">|</span> <a class="syntax" href="#tag-spec-full"><span class="c010">tag-spec-full</span></a> }
 [ <span class="c004">&gt;</span> { <span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a> }<sup>+</sup> ] <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="tag-spec-first"><span class="c010">tag-spec-first</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>  [ <span class="c004">of</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> ]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [ <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> ] <span class="c004">|</span>  <a class="syntax" href="#tag-spec"><span class="c010">tag-spec</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="tag-spec"><span class="c010">tag-spec</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>  [ <span class="c004">of</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> ]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="tag-spec-full"><span class="c010">tag-spec-full</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>  [ <span class="c004">of</span> [<span class="c004">&amp;</span>] <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  { <span class="c004">&amp;</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> } ]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
</td></tr>
</table></td></tr>
</table></div><p>Polymorphic variant types describe the values a polymorphic variant
may take.</p><p>The first case is an exact variant type: all possible tags are
known, with their associated types, and they can all be present.
Its structure is fully known.</p><p>The second case is an open variant type, describing a polymorphic
variant value: it gives the list of all tags the value could take,
with their associated types. This type is still compatible with a
variant type containing more tags. A special case is the unknown
type, which does not define any tag, and is compatible with any
variant type.</p><p>The third case is a closed variant type. It gives information about
all the possible tags and their associated types, and which tags are
known to potentially appear in values. The exact variant type (first
case) is
just an abbreviation for a closed variant type where all possible tags
are also potentially present.</p><p>In all three cases, tags may be either specified directly in the
<span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>  [<span class="c004">of</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>] form, or indirectly through a type
expression, which must expand to an
exact variant type, whose tag specifications are inserted in its
place.</p><p>Full specifications of variant tags are only used for non-exact closed
types. They can be understood as a conjunctive type for the argument:
it is intended to have all the types enumerated in the
specification.</p><p>Such conjunctive constraints may be unsatisfiable. In such a case the
corresponding tag may not be used in a value of this type. This
does not mean that the whole type is not valid: one can still use
other available tags.
Conjunctive constraints are mainly intended as output from the type
checker. When they are used in source programs, unsolvable constraints
may cause early failures.</p><!--TOC subsubsection id="sss:typexpr-obj" Object types-->
<h4 class="subsubsection" id="sss:typexpr-obj"><a class="section-anchor" href="#sss:typexpr-obj" aria-hidden="true"></a>Object types</h4><!--SEC END --><p>An object type
<span class="c004">&lt;</span> [<a class="syntax" href="#method-type"><span class="c010">method-type</span></a>  { <span class="c004">;</span> <a class="syntax" href="#method-type"><span class="c010">method-type</span></a> }] <span class="c004">&gt;</span>
is a record of method types.</p><p>Each method may have an explicit polymorphic type: { <span class="c004">'</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a> }<sup>+</sup>
<span class="c004">.</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>. Explicit polymorphic variables have a local scope, and
an explicit polymorphic type can only be unified to an
equivalent one, where only the order and names of polymorphic
variables may change.</p><p>The type <span class="c004">&lt;</span> {<a class="syntax" href="#method-type"><span class="c010">method-type</span></a> <span class="c004">;</span>} <span class="c002"><span class="c003">..</span> <span class="c003">&gt;</span></span> is the
type of an object whose method names and types are described by
<a class="syntax" href="#method-type"><span class="c010">method-type</span></a><sub>1</sub>, …,  <a class="syntax" href="#method-type"><span class="c010">method-type</span></a><sub><span class="c009">n</span></sub>, and possibly some other
methods represented by the ellipsis. This ellipsis actually is
a special kind of type variable (called <em>row variable</em> in the
literature) that stands for any number of extra method types.</p><!--TOC subsubsection id="sss:typexpr-sharp-types" #-types-->
<h4 class="subsubsection" id="sss:typexpr-sharp-types"><a class="section-anchor" href="#sss:typexpr-sharp-types" aria-hidden="true"></a>#-types</h4><!--SEC END --><p>The type <span class="c004">#</span> <a class="syntax" href="#classtype-path"><span class="c010">classtype-path</span></a> is a special kind of abbreviation. This
abbreviation unifies with the type of any object belonging to a subclass
of the class type <a class="syntax" href="#classtype-path"><span class="c010">classtype-path</span></a>.
It is handled in a special way as it usually hides a type variable (an
ellipsis, representing the methods that may be added in a subclass).
In particular, it vanishes when the ellipsis gets instantiated.
Each type expression <span class="c004">#</span> <a class="syntax" href="#classtype-path"><span class="c010">classtype-path</span></a> defines a new type variable, so
type <span class="c004">#</span> <a class="syntax" href="#classtype-path"><span class="c010">classtype-path</span></a> <span class="c002"><span class="c003">-&gt;</span> <span class="c003">#</span></span>  <a class="syntax" href="#classtype-path"><span class="c010">classtype-path</span></a> is usually not the same as
type (<span class="c004">#</span> <a class="syntax" href="#classtype-path"><span class="c010">classtype-path</span></a> <span class="c002"><span class="c003">as</span> <span class="c003">'</span></span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a>) <span class="c002"><span class="c003">-&gt;</span> <span class="c003">'</span></span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a>.
</p><p>Use of #-types to abbreviate polymorphic variant types is deprecated.
If <span class="c010">t</span> is an exact variant type then <span class="c004">#</span><span class="c010">t</span> translates to <span class="c002"><span class="c003">[&lt;</span> <span class="c010">t</span><span class="c003">]</span></span>,
and <span class="c002"><span class="c003">#</span><span class="c010">t</span><span class="c003">[&gt;</span> <span class="c003">`</span></span><a class="syntax" href="#tag-name"><span class="c010">tag</span></a><sub>1</sub> …<span class="c004">`</span> <a class="syntax" href="#tag-name"><span class="c010">tag</span></a><sub><span class="c009">k</span></sub><span class="c004">]</span> translates to
<span class="c002"><span class="c003">[&lt;</span> <span class="c010">t</span> <span class="c003">&gt;</span> <span class="c003">`</span></span><a class="syntax" href="#tag-name"><span class="c010">tag</span></a><sub>1</sub> …<span class="c004">`</span> <a class="syntax" href="#tag-name"><span class="c010">tag</span></a><sub><span class="c009">k</span></sub><span class="c004">]</span></p><!--TOC subsubsection id="sss:typexpr-variant-record" Variant and record types-->
<h4 class="subsubsection" id="sss:typexpr-variant-record"><a class="section-anchor" href="#sss:typexpr-variant-record" aria-hidden="true"></a>Variant and record types</h4><!--SEC END --><p>There are no type expressions describing (defined) variant types nor
record types, since those are always named, i.e. defined before use
and referred to by name. Type definitions are described in
section <a href="#ss%3Atypedefs">7.8.1</a>.

</p>
<!--TOC section id="s:const" 7.5  Constants-->
<h2 class="section" id="s:const"><a class="section-anchor" href="#s:const" aria-hidden="true"></a>7.5  Constants</h2><!--SEC END --><!--NAME const.html-->
<p><a id="hevea_manual.kwd11"></a>
<a id="hevea_manual.kwd12"></a>
<a id="hevea_manual.kwd13"></a>
<a id="hevea_manual.kwd14"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="constant"><span class="c010">constant</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#integer-literal"><span class="c010">integer-literal</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#int32-literal"><span class="c010">int32-literal</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#int64-literal"><span class="c010">int64-literal</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#nativeint-literal"><span class="c010">nativeint-literal</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#float-literal"><span class="c010">float-literal</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#char-literal"><span class="c010">char-literal</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#string-literal"><span class="c010">string-literal</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#constr"><span class="c010">constr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">false</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">true</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">()</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">begin</span> <span class="c004">end</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">[]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">[||]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>
</td></tr>
</table></td></tr>
</table></div><p>
See also the following language extension:
<a href="#ss%3Aextension-literals">extension literals</a>.</p><p>The syntactic class of constants comprises literals from the four
base types (integers, floating-point numbers, characters, character
strings), the integer variants, and constant constructors
from both normal and polymorphic variants, as well as the special
constants <span class="c004">false</span>, <span class="c004">true</span>, <span class="c004">()</span>,
<span class="c004">[]</span>, and <span class="c004">[||]</span>, which behave like constant constructors, and
<span class="c002"><span class="c003">begin</span> <span class="c003">end</span></span>, which is equivalent to <span class="c004">()</span>.

</p>
<!--TOC section id="s:patterns" 7.6  Patterns-->
<h2 class="section" id="s:patterns"><a class="section-anchor" href="#s:patterns" aria-hidden="true"></a>7.6  Patterns</h2><!--SEC END --><p>
<a id="hevea_manual.kwd15"></a>
</p><!--NAME patterns.html-->
<div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="pattern"><span class="c010">pattern</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#value-name"><span class="c010">value-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">_</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#constant"><span class="c010">constant</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">as</span>  <a class="syntax" href="#value-name"><span class="c010">value-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">|</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#constr"><span class="c010">constr</span></a>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">#</span><a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>  { <span class="c004">,</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> }<sup>+</sup>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">{</span> <a class="syntax" href="#field"><span class="c010">field</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>]  [<span class="c004">=</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>] { <span class="c004">;</span> <a class="syntax" href="#field"><span class="c010">field</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>]  [<span class="c004">=</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>] }  [<span class="c004">;</span> <span class="c004">_</span> ] [ <span class="c004">;</span> ] <span class="c004">}</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">[</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>  { <span class="c004">;</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> }  [ <span class="c004">;</span> ] <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">::</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">[|</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>  { <span class="c004">;</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> }  [ <span class="c004">;</span> ] <span class="c004">|]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#char-literal"><span class="c010">char-literal</span></a> <span class="c004">..</span>  <a class="syntax" href="#char-literal"><span class="c010">char-literal</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">lazy</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">exception</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.(</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.[</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.[|</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">|]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.{</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">}</span>
</td></tr>
</table></td></tr>
</table></div><p>
See also the following language extensions:
<a href="#s%3Afirst-class-modules">first-class modules</a>,
<a href="#s%3Aattributes">attributes</a> and
<a href="#s%3Aextension-nodes">extension nodes</a>.</p><p>The table below shows the relative precedences and associativity of
operators and non-closed pattern constructions. The constructions with
higher precedences come first.
<a id="hevea_manual.kwd16"></a>
</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Operator</span></td><td class="c014"><span class="c013">Associativity</span> </td></tr>
<tr><td class="c016">
<span class="c003">..</span></td><td class="c016">– </td></tr>
<tr><td class="c016"><span class="c003">lazy</span> (see section <a href="#sss%3Apat-lazy">7.6</a>)</td><td class="c016">– </td></tr>
<tr><td class="c016">Constructor application, Tag application</td><td class="c016">right </td></tr>
<tr><td class="c016"><span class="c003">::</span></td><td class="c016">right </td></tr>
<tr><td class="c016"><span class="c003">,</span></td><td class="c016">– </td></tr>
<tr><td class="c016"><span class="c003">|</span></td><td class="c016">left </td></tr>
<tr><td class="c016"><span class="c003">as</span></td><td class="c016">– </td></tr>
</table></div></div><p>Patterns are templates that allow selecting data structures of a
given shape, and binding identifiers to components of the data
structure. This selection operation is called pattern matching; its
outcome is either “this value does not match this pattern”, or
“this value matches this pattern, resulting in the following bindings
of names to values”.</p><!--TOC subsubsection id="sss:pat-variable" Variable patterns-->
<h4 class="subsubsection" id="sss:pat-variable"><a class="section-anchor" href="#sss:pat-variable" aria-hidden="true"></a>Variable patterns</h4><!--SEC END --><p>A pattern that consists in a value name matches any value,
binding the name to the value. The pattern <span class="c004">_</span> also matches
any value, but does not bind any name.</p><p>Patterns are <em>linear</em>: a variable cannot be bound several times by
a given pattern. In particular, there is no way to test for equality
between two parts of a data structure using only a pattern (but
<span class="c004">when</span> guards can be used for this purpose).</p><!--TOC subsubsection id="sss:pat-const" Constant patterns-->
<h4 class="subsubsection" id="sss:pat-const"><a class="section-anchor" href="#sss:pat-const" aria-hidden="true"></a>Constant patterns</h4><!--SEC END --><p>A pattern consisting in a constant matches the values that
are equal to this constant.</p><!--TOC subsubsection id="sss:pat-alias" Alias patterns-->
<h4 class="subsubsection" id="sss:pat-alias"><a class="section-anchor" href="#sss:pat-alias" aria-hidden="true"></a>Alias patterns</h4><!--SEC END --><p>
<a id="hevea_manual.kwd17"></a></p><p>The pattern <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">as</span>  <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> matches the same values as
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub>. If the matching against <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> is successful,
the name <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> is bound to the matched value, in addition to the
bindings performed by the matching against <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub>.</p><!--TOC subsubsection id="sss:pat-parenthesized" Parenthesized patterns-->
<h4 class="subsubsection" id="sss:pat-parenthesized"><a class="section-anchor" href="#sss:pat-parenthesized" aria-hidden="true"></a>Parenthesized patterns</h4><!--SEC END --><p>The pattern <span class="c004">(</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">)</span> matches the same values as
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub>. A type constraint can appear in a
parenthesized pattern, as in <span class="c004">(</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">)</span>. This
constraint forces the type of <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> to be compatible with
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>.</p><!--TOC subsubsection id="sss:pat-or" “Or” patterns-->
<h4 class="subsubsection" id="sss:pat-or"><a class="section-anchor" href="#sss:pat-or" aria-hidden="true"></a>“Or” patterns</h4><!--SEC END --><p>The pattern <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">|</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>2</sub> represents the logical “or” of
the two patterns <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> and <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>2</sub>. A value matches
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">|</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>2</sub> if it matches <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> or
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>2</sub>. The two sub-patterns <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> and <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>2</sub>
must bind exactly the same identifiers to values having the same types.
Matching is performed from left to right.
More precisely,
in case some value <span class="c009">v</span> matches <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">|</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>2</sub>, the bindings
performed are those of <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> when <span class="c009">v</span> matches <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub>.
Otherwise, value <span class="c009">v</span> matches <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>2</sub> whose bindings are performed.</p><!--TOC subsubsection id="sss:pat-variant" Variant patterns-->
<h4 class="subsubsection" id="sss:pat-variant"><a class="section-anchor" href="#sss:pat-variant" aria-hidden="true"></a>Variant patterns</h4><!--SEC END --><p>The pattern <a class="syntax" href="#constr"><span class="c010">constr</span></a> <span class="c004">(</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">,</span> … <span class="c004">,</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub> <span class="c004">)</span> matches
all variants whose
constructor is equal to <a class="syntax" href="#constr"><span class="c010">constr</span></a>, and whose arguments match
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> …  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub>. It is a type error if <span class="c009">n</span> is not the
number of arguments expected by the constructor.</p><p>The pattern <a class="syntax" href="#constr"><span class="c010">constr</span></a> <span class="c004">_</span> matches all variants whose constructor is
<a class="syntax" href="#constr"><span class="c010">constr</span></a>.</p><p>The pattern <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">::</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>2</sub> matches non-empty lists whose
heads match <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub>, and whose tails match <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>2</sub>.</p><p>The pattern <span class="c004">[</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub> <span class="c004">]</span> matches lists
of length <span class="c009">n</span> whose elements match <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> …<a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub>,
respectively. This pattern behaves like
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">::</span> … <span class="c004">::</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub> <span class="c002"><span class="c003">::</span> <span class="c003">[]</span></span>.</p><!--TOC subsubsection id="sss:pat-polyvar" Polymorphic variant patterns-->
<h4 class="subsubsection" id="sss:pat-polyvar"><a class="section-anchor" href="#sss:pat-polyvar" aria-hidden="true"></a>Polymorphic variant patterns</h4><!--SEC END --><p>The pattern <span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> matches all polymorphic variants
whose tag is equal to <a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>, and whose argument matches
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub>.</p><!--TOC subsubsection id="sss:pat-polyvar-abbrev" Polymorphic variant abbreviation patterns-->
<h4 class="subsubsection" id="sss:pat-polyvar-abbrev"><a class="section-anchor" href="#sss:pat-polyvar-abbrev" aria-hidden="true"></a>Polymorphic variant abbreviation patterns</h4><!--SEC END --><p>If the type [<span class="c004">('a,'b,</span>…<span class="c004">)</span>] <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a> = <span class="c002"><span class="c003">[</span> <span class="c003">`</span></span> <a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a><sub>1</sub>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">|</span>
… <span class="c002"><span class="c003">|</span> <span class="c003">`</span></span> <a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a><sub><span class="c009">n</span></sub>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub><span class="c004">]</span> is defined, then the pattern <span class="c004">#</span><a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>
is a shorthand for the following or-pattern:
<span class="c002"><span class="c003">(</span> <span class="c003">`</span></span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a><sub>1</sub><span class="c002"><span class="c003">(_</span> <span class="c003">:</span></span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub><span class="c002"><span class="c003">)</span> <span class="c003">|</span></span> … <span class="c002"><span class="c003">|</span> <span class="c003">`</span></span> <a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a><sub><span class="c009">n</span></sub><span class="c002"><span class="c003">(_</span>
<span class="c003">:</span></span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub><span class="c004">))</span>. It matches all values of type <span class="c004">[&lt;</span> <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a> <span class="c004">]</span>.</p><!--TOC subsubsection id="sss:pat-tuple" Tuple patterns-->
<h4 class="subsubsection" id="sss:pat-tuple"><a class="section-anchor" href="#sss:pat-tuple" aria-hidden="true"></a>Tuple patterns</h4><!--SEC END --><p>The pattern <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">,</span> … <span class="c004">,</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub> matches <span class="c009">n</span>-tuples
whose components match the patterns <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> through <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub>. That
is, the pattern matches the tuple values (<span class="c009">v</span><sub>1</sub>, …, <span class="c009">v</span><sub><span class="c009">n</span></sub>) such that
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">i</span></sub> matches <span class="c009">v</span><sub><span class="c009">i</span></sub> for <span class="c009">i</span> = 1,… , <span class="c009">n</span>.</p><!--TOC subsubsection id="sss:pat-record" Record patterns-->
<h4 class="subsubsection" id="sss:pat-record"><a class="section-anchor" href="#sss:pat-record" aria-hidden="true"></a>Record patterns</h4><!--SEC END --><p>The pattern <span class="c004">{</span> <a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub>  [<span class="c004">=</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub>] <span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">n</span></sub>  [<span class="c004">=</span>
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub>] <span class="c004">}</span> matches records that define at least the fields
<a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub> through <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">n</span></sub>, and such that the value associated to
<a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">i</span></sub> matches the pattern <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">i</span></sub>, for <span class="c009">i</span> = 1,… , <span class="c009">n</span>.
A single identifier <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> stands for <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> <span class="c004">=</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> ,
and a single qualified identifier <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> stands
for <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> <span class="c004">=</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> .
The record value can define more fields than <a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub> …<a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">n</span></sub>; the values associated to these extra fields are not taken
into account for matching. Optionally, a record pattern can be terminated
by <span class="c002"><span class="c003">;</span> <span class="c003">_</span></span> to convey the fact that not all fields of the record type are
listed in the record pattern and that it is intentional.
Optional type constraints can be added field by field with
<span class="c004">{</span> <a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">=</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">;</span>… <span class="c004">;</span> <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">n</span></sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub> <span class="c004">=</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub> <span class="c004">}</span> to force the type
of <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> to be compatible with <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">k</span></sub>.</p><!--TOC subsubsection id="sss:pat-array" Array patterns-->
<h4 class="subsubsection" id="sss:pat-array"><a class="section-anchor" href="#sss:pat-array" aria-hidden="true"></a>Array patterns</h4><!--SEC END --><p>The pattern <span class="c004">[|</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub> <span class="c004">|]</span>
matches arrays of length <span class="c009">n</span> such that the <span class="c009">i</span>-th array element
matches the pattern <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">i</span></sub>, for <span class="c009">i</span> = 1,… , <span class="c009">n</span>.</p><!--TOC subsubsection id="sss:pat-range" Range patterns-->
<h4 class="subsubsection" id="sss:pat-range"><a class="section-anchor" href="#sss:pat-range" aria-hidden="true"></a>Range patterns</h4><!--SEC END --><p>The pattern
<span class="c002"><span class="c003">'</span> <span class="c010">c</span> <span class="c003">'</span> <span class="c003">..</span> <span class="c003">'</span> <span class="c010">d</span> <span class="c003">'</span></span> is a shorthand for the pattern
</p><div class="center">
<span class="c004">'</span> <span style="color:maroon"><span class="c009">c</span> <span class="c002"><span class="c003">'</span> <span class="c003">|</span> <span class="c003">'</span></span> <span class="c009">c</span></span><sub>1</sub> <span class="c002"><span class="c003">'</span> <span class="c003">|</span> <span class="c003">'</span></span> <span class="c010">c</span><sub>2</sub> <span class="c002"><span class="c003">'</span> <span class="c003">|</span></span> …
<span class="c002"><span class="c003">|</span> <span class="c003">'</span></span> <span class="c010">c</span><sub><span class="c009">n</span></sub> <span class="c002"><span class="c003">'</span> <span class="c003">|</span> <span class="c003">'</span> <span class="c010">d</span> <span class="c003">'</span></span>
</div><p>
where <span class="c009">c</span><sub>1</sub>, <span class="c009">c</span><sub>2</sub>, …, <span class="c009">c</span><sub><span class="c009">n</span></sub> are the characters
that occur between <span class="c009">c</span> and <span class="c009">d</span> in the ASCII character set. For
instance, the pattern <span class="c003">'0'<span class="c002">..</span>'9'</span> matches all characters that are digits.</p>
<!--TOC subsubsection id="sss:pat-lazy" Lazy patterns-->
<h4 class="subsubsection" id="sss:pat-lazy"><a class="section-anchor" href="#sss:pat-lazy" aria-hidden="true"></a>Lazy patterns</h4><!--SEC END --><p><a id="hevea_manual.kwd18"></a></p><p>(Introduced in Objective Caml 3.11)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a></td><td class="c015">::=</td><td class="c017"> ...
</td></tr>
</table></td></tr>
</table></div><p>The pattern <span class="c004">lazy</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> matches a value <span class="c009">v</span> of type <span class="c003">Lazy.t</span>,
provided <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> matches the result of forcing <span class="c009">v</span> with
<span class="c003">Lazy.force</span>. A successful match of a pattern containing <span class="c004">lazy</span>
sub-patterns forces the corresponding parts of the value being matched, even
those that imply no test such as <span class="c004">lazy</span> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> or <span class="c002"><span class="c003">lazy</span> <span class="c003">_</span></span>.
Matching a value with a <a class="syntax" href="#pattern-matching"><span class="c010">pattern-matching</span></a> where some patterns
contain <span class="c004">lazy</span> sub-patterns may imply forcing parts of the value,
even when the pattern selected in the end has no <span class="c004">lazy</span> sub-pattern.</p><p>For more information, see the description of module <span class="c003">Lazy</span> in the
standard library (module <a href="libref/Lazy.html"><span class="c003">Lazy</span></a>).
<a id="hevea_manual0"></a><a id="hevea_manual1"></a></p><!--TOC subsubsection id="sss:exception-match" Exception patterns-->
<h4 class="subsubsection" id="sss:exception-match"><a class="section-anchor" href="#sss:exception-match" aria-hidden="true"></a>Exception patterns</h4><!--SEC END --><p>
(Introduced in OCaml 4.02)</p><p>A new form of exception pattern,  <span class="c004">exception</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> , is allowed
only as a toplevel pattern or inside a toplevel or-pattern under
a <span class="c003">match</span>...<span class="c003">with</span> pattern-matching
(other occurrences are rejected by the type-checker).</p><p>Cases with such a toplevel pattern are called “exception cases”,
as opposed to regular “value cases”. Exception cases are applied
when the evaluation of the matched expression raises an exception.
The exception value is then matched against all the exception cases
and re-raised if none of them accept the exception (as with a
<span class="c003">try</span>...<span class="c003">with</span> block). Since the bodies of all exception and value
cases are outside the scope of the exception handler, they are all
considered to be in tail-position: if the <span class="c003">match</span>...<span class="c003">with</span> block
itself is in tail position in the current function, any function call
in tail position in one of the case bodies results in an actual tail
call.</p><p>A pattern match must contain at least one value case. It is an error if
all cases are exceptions, because there would be no code to handle
the return of a value.</p><!--TOC subsubsection id="sss:pat-open" Local opens for patterns-->
<h4 class="subsubsection" id="sss:pat-open"><a class="section-anchor" href="#sss:pat-open" aria-hidden="true"></a>Local opens for patterns</h4><!--SEC END --><p>
<a id="hevea_manual.kwd19"></a>
(Introduced in OCaml 4.04)</p><p>For patterns, local opens are limited to the
<a class="syntax" href="#module-path"><span class="c010">module-path</span></a><span class="c004">.(</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><span class="c004">)</span> construction. This
construction locally opens the module referred to by the module path
<a class="syntax" href="#module-path"><span class="c010">module-path</span></a> in the scope of the pattern <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>.</p><p>When the body of a local open pattern is delimited by
<span class="c002"><span class="c003">[</span> <span class="c003">]</span></span>, <span class="c002"><span class="c003">[|</span> <span class="c003">|]</span></span>, or <span class="c002"><span class="c003">{</span> <span class="c003">}</span></span>, the parentheses can be omitted.
For example, <a class="syntax" href="#module-path"><span class="c010">module-path</span></a><span class="c004">.[</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><span class="c004">]</span> is equivalent to
<a class="syntax" href="#module-path"><span class="c010">module-path</span></a><span class="c004">.([</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><span class="c004">])</span>, and <a class="syntax" href="#module-path"><span class="c010">module-path</span></a><span class="c004">.[|</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">|]</span> is
equivalent to <a class="syntax" href="#module-path"><span class="c010">module-path</span></a><span class="c004">.([|</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">|])</span>.

</p>
<!--TOC section id="s:value-expr" 7.7  Expressions-->
<h2 class="section" id="s:value-expr"><a class="section-anchor" href="#s:value-expr" aria-hidden="true"></a>7.7  Expressions</h2><!--SEC END --><!--NAME expr.html-->
<p>
<a id="hevea_manual.kwd20"></a>
<a id="hevea_manual.kwd21"></a>
<a id="hevea_manual.kwd22"></a>
<a id="hevea_manual.kwd23"></a>
<a id="hevea_manual.kwd24"></a>
<a id="hevea_manual.kwd25"></a>
<a id="hevea_manual.kwd26"></a>
<a id="hevea_manual.kwd27"></a>
<a id="hevea_manual.kwd28"></a>
<a id="hevea_manual.kwd29"></a>
<a id="hevea_manual.kwd30"></a>
<a id="hevea_manual.kwd31"></a>
<a id="hevea_manual.kwd32"></a>
<a id="hevea_manual.kwd33"></a>
<a id="hevea_manual.kwd34"></a>
<a id="hevea_manual.kwd35"></a>
<a id="hevea_manual.kwd36"></a>
<a id="hevea_manual.kwd37"></a>
<a id="hevea_manual.kwd38"></a>
<a id="hevea_manual.kwd39"></a>
<a id="hevea_manual.kwd40"></a>
<a id="hevea_manual.kwd41"></a>
<a id="hevea_manual.kwd42"></a>
<a id="hevea_manual.kwd43"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="expr"><span class="c010">expr</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#value-path"><span class="c010">value-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#constant"><span class="c010">constant</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">begin</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">end</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a>  {<span class="c004">,</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>}<sup>+</sup>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#constr"><span class="c010">constr</span></a>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">::</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">[</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>  { <span class="c004">;</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> }  [<span class="c004">;</span>] <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">[|</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>  { <span class="c004">;</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> }  [<span class="c004">;</span>] <span class="c004">|]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">{</span> <a class="syntax" href="#field"><span class="c010">field</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>]  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>] { <span class="c004">;</span> <a class="syntax" href="#field"><span class="c010">field</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>]  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>] }  [<span class="c004">;</span>] <span class="c004">}</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">with</span>  <a class="syntax" href="#field"><span class="c010">field</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>]  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>] { <span class="c004">;</span> <a class="syntax" href="#field"><span class="c010">field</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>]  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>] }  [<span class="c004">;</span>] <span class="c004">}</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a>  { <a class="syntax" href="#argument"><span class="c010">argument</span></a> }<sup>+</sup>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#prefix-symbol"><span class="c010">prefix-symbol</span></a>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">-</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">-.</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a>  <a class="syntax" href="#infix-op"><span class="c010">infix-op</span></a>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.</span>  <a class="syntax" href="#field"><span class="c010">field</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.</span>  <a class="syntax" href="#field"><span class="c010">field</span></a> <span class="c004">&lt;-</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.(</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.(</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">)</span> <span class="c004">&lt;-</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.[</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.[</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">]</span> <span class="c004">&lt;-</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">if</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">then</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>  [ <span class="c004">else</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> ]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">while</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">do</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">done</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">for</span> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>  ( <span class="c004">to</span> ∣  <span class="c004">downto</span> ) <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">do</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">done</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">match</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">with</span>  <a class="syntax" href="#pattern-matching"><span class="c010">pattern-matching</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">function</span> <a class="syntax" href="#pattern-matching"><span class="c010">pattern-matching</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">fun</span> { <a class="syntax" href="#parameter"><span class="c010">parameter</span></a> }<sup>+</sup>  [ <span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> ] <span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">try</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">with</span>  <a class="syntax" href="#pattern-matching"><span class="c010">pattern-matching</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">let</span> [<span class="c004">rec</span>] <a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a>  { <span class="c004">and</span> <a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a> } <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">let</span> <span class="c004">exception</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">let</span> <span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a>  { <span class="c004">(</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span> }
 [ <span class="c004">:</span> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> ]  <span class="c004">=</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">:&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">:&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">assert</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">lazy</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#local-open"><span class="c010">local-open</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#object-expr"><span class="c010">object-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="argument"><span class="c010">argument</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">~</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">~</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">?</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">?</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="pattern-matching"><span class="c010">pattern-matching</span></a></td><td class="c015">::=</td><td class="c017">
[ <span class="c004">|</span> ] <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>  [<span class="c004">when</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>] <span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 { <span class="c004">|</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>  [<span class="c004">when</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>] <span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="let-binding"><span class="c010">let-binding</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a>  { <a class="syntax" href="#parameter"><span class="c010">parameter</span></a> }  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>]  [<span class="c004">:&gt;</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>] <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>  </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="parameter"><span class="c010">parameter</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">~</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">~</span> <span class="c004">(</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>] <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">~</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">?</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">?</span> <span class="c004">(</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>]  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>] <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">?</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">?</span> <a class="syntax" href="#label-name"><span class="c010">label-name</span></a> <span class="c004">:</span> <span class="c004">(</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>]  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>] <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="local-open"><span class="c010">local-open</span></a></td><td class="c015">::=</td><td class="c017">
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">let</span> <span class="c004">open</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.(</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.[</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.[|</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">|]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.{</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">}</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.{&lt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">&gt;}</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="object-expr"><span class="c010">object-expr</span></a></td><td class="c015">::=</td><td class="c017">
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">new</span> <a class="syntax" href="#class-path"><span class="c010">class-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">object</span> <a class="syntax" href="#class-body"><span class="c010">class-body</span></a> <span class="c004">end</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">#</span>  <a class="syntax" href="#method-name"><span class="c010">method-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">&lt;-</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">{&lt;</span> [ <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a>  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>]  { <span class="c004">;</span> <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a>  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>] }  [<span class="c004">;</span>] ] <span class="c004">&gt;}</span>
</td></tr>
</table></td></tr>
</table></div><p>
See also the following language extensions:
<a href="#s%3Afirst-class-modules">first-class modules</a>,
<a href="#s%3Aexplicit-overriding-open">overriding in open statements</a>,
<a href="#s%3Abigarray-access">syntax for Bigarray access</a>,
<a href="#s%3Aattributes">attributes</a>,
<a href="#s%3Aextension-nodes">extension nodes</a> and
<a href="#s%3Aindex-operators">extended indexing operators</a>.</p>
<!--TOC subsection id="ss:precedence-and-associativity" 7.7.1  Precedence and associativity-->
<h3 class="subsection" id="ss:precedence-and-associativity"><a class="section-anchor" href="#ss:precedence-and-associativity" aria-hidden="true"></a>7.7.1  Precedence and associativity</h3><!--SEC END --><p>
The table below shows the relative precedences and associativity of
operators and non-closed constructions. The constructions with higher
precedence come first. For infix and prefix symbols, we write
“<span class="c003">*</span>…” to mean “any symbol starting with <span class="c003">*</span>”.
<a id="hevea_manual.kwd44"></a><a id="hevea_manual.kwd45"></a><a id="hevea_manual.kwd46"></a><a id="hevea_manual.kwd47"></a><a id="hevea_manual.kwd48"></a><a id="hevea_manual.kwd49"></a><a id="hevea_manual.kwd50"></a><a id="hevea_manual.kwd51"></a>
<a id="hevea_manual.kwd52"></a>
<a id="hevea_manual.kwd53"></a>
<a id="hevea_manual.kwd54"></a>
<a id="hevea_manual.kwd55"></a>
<a id="hevea_manual.kwd56"></a>
<a id="hevea_manual.kwd57"></a>
</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Construction or operator</span></td><td class="c014"><span class="c013">Associativity</span> </td></tr>
<tr><td class="c016">
prefix-symbol</td><td class="c016">– </td></tr>
<tr><td class="c016"><span class="c003">.   .(   .[   .{</span> (see section <a href="#s%3Abigarray-access">8.11</a>)</td><td class="c016">– </td></tr>
<tr><td class="c016"><span class="c003">#</span>…</td><td class="c016">left </td></tr>
<tr><td class="c016">function application, constructor application, tag
application, <span class="c003">assert</span>,
<span class="c003">lazy</span></td><td class="c016">left </td></tr>
<tr><td class="c016"><span class="c003">-   -.</span> (prefix)</td><td class="c016">– </td></tr>
<tr><td class="c016"><span class="c003">**</span>…<span class="c003">   lsl   lsr   asr</span></td><td class="c016">right </td></tr>
<tr><td class="c016"><span class="c003">*</span>…<span class="c003">   /</span>…<span class="c003">   %</span>…<span class="c003">   mod   land   lor   lxor</span></td><td class="c016">left </td></tr>
<tr><td class="c016"> <span class="c003">+</span>…<span class="c003">   -</span>…</td><td class="c016">left </td></tr>
<tr><td class="c016"><span class="c003">::</span></td><td class="c016">right </td></tr>
<tr><td class="c016"><span class="c003">@</span>…<span class="c003">   ^</span>…</td><td class="c016">right </td></tr>
<tr><td class="c016"><span class="c003">=</span>…<span class="c003">   &lt;</span>…<span class="c003">   &gt;</span>…<span class="c003">   |</span>…<span class="c003">   &amp;</span>…<span class="c003">   $</span>…<span class="c003">   !=</span></td><td class="c016">left </td></tr>
<tr><td class="c016"><span class="c003">&amp;   &amp;&amp;</span></td><td class="c016">right </td></tr>
<tr><td class="c016"><span class="c003">or  ||</span></td><td class="c016">right </td></tr>
<tr><td class="c016"><span class="c003">,</span></td><td class="c016">– </td></tr>
<tr><td class="c016"><span class="c003">&lt;-   :=</span></td><td class="c016">right </td></tr>
<tr><td class="c016"><span class="c003">if</span></td><td class="c016">– </td></tr>
<tr><td class="c016"><span class="c003">;</span></td><td class="c016">right </td></tr>
<tr><td class="c016"><span class="c003">let  match  fun  function  try</span></td><td class="c016">– </td></tr>
</table></div></div>
<!--TOC subsection id="ss:expr-basic" 7.7.2  Basic expressions-->
<h3 class="subsection" id="ss:expr-basic"><a class="section-anchor" href="#ss:expr-basic" aria-hidden="true"></a>7.7.2  Basic expressions</h3><!--SEC END --><!--TOC subsubsection id="sss:expr-constants" Constants-->
<h4 class="subsubsection" id="sss:expr-constants"><a class="section-anchor" href="#sss:expr-constants" aria-hidden="true"></a>Constants</h4><!--SEC END --><p>An expression consisting in a constant evaluates to this constant.</p><!--TOC subsubsection id="sss:expr-var" Value paths-->
<h4 class="subsubsection" id="sss:expr-var"><a class="section-anchor" href="#sss:expr-var" aria-hidden="true"></a>Value paths</h4><!--SEC END --><p>An expression consisting in an access path evaluates to the value bound to
this path in the current evaluation environment. The path can
be either a value name or an access path to a value component of a module.</p><!--TOC subsubsection id="sss:expr-parenthesized" Parenthesized expressions-->
<h4 class="subsubsection" id="sss:expr-parenthesized"><a class="section-anchor" href="#sss:expr-parenthesized" aria-hidden="true"></a>Parenthesized expressions</h4><!--SEC END --><p>
<a id="hevea_manual.kwd58"></a>
<a id="hevea_manual.kwd59"></a></p><p>The expressions <span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">)</span> and <span class="c004">begin</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">end</span> have the same
value as <a class="syntax" href="#expr"><span class="c010">expr</span></a>. The two constructs are semantically equivalent, but it
is good style to use <span class="c004">begin</span> … <span class="c004">end</span> inside control structures:
</p><pre>
        if … then begin … ; … end else begin … ; … end
</pre><p>
and <span class="c004">(</span> … <span class="c004">)</span> for the other grouping situations.</p><p>Parenthesized expressions can contain a type constraint, as in <span class="c004">(</span>
<a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">)</span>. This constraint forces the type of <a class="syntax" href="#expr"><span class="c010">expr</span></a> to be
compatible with <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>.</p><p>Parenthesized expressions can also contain coercions
<span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>] <span class="c004">:&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><span class="c004">)</span> (see
subsection <a href="#ss%3Aexpr-coercions">7.7.7</a> below).</p><!--TOC subsubsection id="sss:expr-functions-application" Function application-->
<h4 class="subsubsection" id="sss:expr-functions-application"><a class="section-anchor" href="#sss:expr-functions-application" aria-hidden="true"></a>Function application</h4><!--SEC END --><p>Function application is denoted by juxtaposition of (possibly labeled)
expressions. The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a>  <a class="syntax" href="#argument"><span class="c010">argument</span></a><sub>1</sub> …  <a class="syntax" href="#argument"><span class="c010">argument</span></a><sub><span class="c009">n</span></sub>
evaluates the expression <a class="syntax" href="#expr"><span class="c010">expr</span></a> and those appearing in <a class="syntax" href="#argument"><span class="c010">argument</span></a><sub>1</sub>
to <a class="syntax" href="#argument"><span class="c010">argument</span></a><sub><span class="c009">n</span></sub>. The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a> must evaluate to a
functional value <span class="c009">f</span>, which is then applied to the values of
<a class="syntax" href="#argument"><span class="c010">argument</span></a><sub>1</sub>, …,  <a class="syntax" href="#argument"><span class="c010">argument</span></a><sub><span class="c009">n</span></sub>.</p><p>The order in which the expressions <a class="syntax" href="#expr"><span class="c010">expr</span></a>,  <a class="syntax" href="#argument"><span class="c010">argument</span></a><sub>1</sub>, …,
 <a class="syntax" href="#argument"><span class="c010">argument</span></a><sub><span class="c009">n</span></sub> are evaluated is not specified.</p><p>Arguments and parameters are matched according to their respective
labels. Argument order is irrelevant, except among arguments with the
same label, or no label.</p><p>If a parameter is specified as optional (label prefixed by <span class="c004">?</span>) in the
type of <a class="syntax" href="#expr"><span class="c010">expr</span></a>, the corresponding argument will be automatically
wrapped with the constructor <span class="c003">Some</span>, except if the argument itself is
also prefixed by <span class="c004">?</span>, in which case it is passed as is.
If a non-labeled argument is passed, and its corresponding parameter
is preceded by one or several optional parameters, then these
parameters are <em>defaulted</em>, <em>i.e.</em> the value <span class="c003">None</span> will be
passed for them.
All other missing parameters (without corresponding argument), both
optional and non-optional, will be kept, and the result of the
function will still be a function of these missing parameters to the
body of <span class="c009">f</span>.</p><p>As a special case, if the function has a known arity, all the
arguments are unlabeled, and their number matches the number of
non-optional parameters, then labels are ignored and non-optional
parameters are matched in their definition order. Optional arguments
are defaulted.</p><p>In all cases but exact match of order and labels, without optional
parameters, the function type should be known at the application
point. This can be ensured by adding a type constraint. Principality
of the derivation can be checked in the <span class="c003">-principal</span> mode.</p><!--TOC subsubsection id="sss:expr-function-definition" Function definition-->
<h4 class="subsubsection" id="sss:expr-function-definition"><a class="section-anchor" href="#sss:expr-function-definition" aria-hidden="true"></a>Function definition</h4><!--SEC END --><p>Two syntactic forms are provided to define functions. The first form
is introduced by the keyword <span class="c003">function</span>:
<a id="hevea_manual.kwd60"></a></p><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018"><span class="c004">function</span></td><td class="c017"><span class="c012">pattern</span><sub>1</sub></td><td class="c017"><span class="c004">-&gt;</span></td><td class="c017"><span class="c012">expr</span><sub>1</sub> </td></tr>
<tr><td class="c018"><span class="c004">|</span></td><td class="c017">… </td></tr>
<tr><td class="c018"><span class="c004">|</span></td><td class="c017"><span class="c012">pattern</span><sub><span class="c009">n</span></sub></td><td class="c017"><span class="c004">-&gt;</span></td><td class="c017"><span class="c012">expr</span><sub><span class="c009">n</span></sub>
</td></tr>
</table></td></tr>
</table><p>
This expression evaluates to a functional value with one argument.
When this function is applied to a value <span class="c009">v</span>, this value is
matched against each pattern <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> to <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub>.
If one of these matchings succeeds, that is, if the value <span class="c009">v</span>
matches the pattern <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">i</span></sub> for some <span class="c009">i</span>,
then the expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">i</span></sub> associated to the selected pattern
is evaluated, and its value becomes the value of the function
application. The evaluation of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">i</span></sub> takes place in an
environment enriched by the bindings performed during the matching.</p><p>If several patterns match the argument <span class="c009">v</span>, the one that occurs
first in the function definition is selected. If none of the patterns
matches the argument, the exception <span class="c003">Match_failure</span> is raised.
<a id="hevea_manual2"></a></p><p><br>
</p><p>The other form of function definition is introduced by the keyword <span class="c003">fun</span>:
<a id="hevea_manual.kwd61"></a>
</p><div class="center">
<span class="c004">fun</span> <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub>1</sub> …  <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub><span class="c009">n</span></sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p>
This expression is equivalent to:
</p><div class="center">
<span class="c004">fun</span> <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub>1</sub> <span class="c004">-&gt;</span> … <span class="c004">fun</span>  <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub><span class="c009">n</span></sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p>An optional type constraint <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> can be added before <span class="c003">-&gt;</span> to enforce
the type of the result to be compatible with the constraint <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>:
</p><div class="center">
<span class="c004">fun</span> <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub>1</sub> …  <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub><span class="c009">n</span></sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p>
is equivalent to
</p><div class="center">
<span class="c004">fun</span> <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub>1</sub> <span class="c004">-&gt;</span> … <span class="c004">fun</span>  <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub><span class="c009">n</span></sub> <span class="c004">-&gt;</span>  (<a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> )
</div><p>
Beware of the small syntactic difference between a type constraint on
the last parameter
</p><div class="center">
<span class="c004">fun</span> <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub>1</sub> …  (<a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub><span class="c009">n</span></sub><span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>)<span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> 
</div><p>
and one on the result
</p><div class="center">
<span class="c004">fun</span> <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub>1</sub> …  <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub><span class="c009">n</span></sub><span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> 
</div><p>The parameter patterns <span class="c004">~</span><a class="syntax" href="#label-name"><span class="c010">lab</span></a> and <span class="c004">~(</span><a class="syntax" href="#label-name"><span class="c010">lab</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>]<span class="c004">)</span>
are shorthands for respectively <span class="c004">~</span><a class="syntax" href="#label-name"><span class="c010">lab</span></a><span class="c004">:</span> <a class="syntax" href="#label-name"><span class="c010">lab</span></a> and
<span class="c004">~</span><a class="syntax" href="#label-name"><span class="c010">lab</span></a><span class="c004">:(</span> <a class="syntax" href="#label-name"><span class="c010">lab</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>]<span class="c004">)</span>, and similarly for their optional
counterparts.</p><p>A function of the form <span class="c002"><span class="c003">fun</span> <span class="c003">?</span></span> <a class="syntax" href="#label-name"><span class="c010">lab</span></a> <span class="c004">:(</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub> <span class="c002"><span class="c003">)</span> <span class="c003">-&gt;</span></span>
 <a class="syntax" href="#expr"><span class="c010">expr</span></a> is equivalent to
</p><div class="center">
<span class="c002"><span class="c003">fun</span> <span class="c003">?</span></span> <a class="syntax" href="#label-name"><span class="c010">lab</span></a> <span class="c004">:</span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a> <span class="c002"><span class="c003">-&gt;</span>
<span class="c003">let</span></span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c002"><span class="c003">=</span>
<span class="c003">match</span></span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a> <span class="c002"><span class="c003">with</span> <span class="c003">Some</span></span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a> <span class="c004">-&gt;</span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a> <span class="c002"><span class="c003">|</span> <span class="c003">None</span> <span class="c003">-&gt;</span></span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub>
<span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p>
where <a class="syntax" href="#ident"><span class="c010">ident</span></a>
is a fresh variable, except that it is unspecified when <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub> is evaluated.</p><p>After these two transformations, expressions are of the form
</p><div class="center">
<span class="c004">fun</span> [<a class="syntax" href="#label"><span class="c010">label</span></a><sub>1</sub>]  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">-&gt;</span> … <span class="c004">fun</span>  [<a class="syntax" href="#label"><span class="c010">label</span></a><sub><span class="c009">n</span></sub>]  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p>
If we ignore labels, which will only be meaningful at function
application, this is equivalent to
</p><div class="center">
<span class="c004">function</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">-&gt;</span> … <span class="c004">function</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p>
That is, the <span class="c004">fun</span> expression above evaluates to a curried function
with <span class="c009">n</span> arguments: after applying this function <span class="c009">n</span> times to the
values <span class="c010">v</span><sub>1</sub> … <span class="c010">v</span><sub><span class="c009">n</span></sub>, the values will be matched
in parallel against the patterns <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> …  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub>.
If the matching succeeds, the function returns the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a> in
an environment enriched by the bindings performed during the matchings.
If the matching fails, the exception <span class="c003">Match_failure</span> is raised.</p><!--TOC subsubsection id="sss:guards-in-pattern-matchings" Guards in pattern-matchings-->
<h4 class="subsubsection" id="sss:guards-in-pattern-matchings"><a class="section-anchor" href="#sss:guards-in-pattern-matchings" aria-hidden="true"></a>Guards in pattern-matchings</h4><!--SEC END --><p><a id="hevea_manual.kwd62"></a>
The cases of a pattern matching (in the <span class="c004">function</span>, <span class="c004">match</span> and
<span class="c004">try</span> constructs) can include guard expressions, which are
arbitrary boolean expressions that must evaluate to <span class="c003">true</span> for the
match case to be selected. Guards occur just before the <span class="c004">-&gt;</span> token and
are introduced by the <span class="c004">when</span> keyword:</p><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018"><span class="c004">function</span></td><td class="c017"><span class="c010">pattern</span><sub>1</sub>   [<span class="c004">when</span>   <span class="c010">cond</span><sub>1</sub>]</td><td class="c017"><span class="c004">-&gt;</span></td><td class="c017"><span class="c010">expr</span><sub>1</sub> </td></tr>
<tr><td class="c018"><span class="c004">|</span></td><td class="c017">… </td></tr>
<tr><td class="c018"><span class="c004">|</span></td><td class="c017"><span class="c010">pattern</span><sub><span class="c009">n</span></sub>    [<span class="c004">when</span>   <span class="c010">cond</span><sub><span class="c009">n</span></sub>]</td><td class="c017"><span class="c004">-&gt;</span></td><td class="c017"><span class="c010">expr</span><sub><span class="c009">n</span></sub>
</td></tr>
</table></td></tr>
</table><p>Matching proceeds as described before, except that if the value
matches some pattern <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">i</span></sub> which has a guard <span class="c010">cond</span><sub><span class="c009">i</span></sub>, then the
expression <span class="c010">cond</span><sub><span class="c009">i</span></sub> is evaluated (in an environment enriched by the
bindings performed during matching). If <span class="c010">cond</span><sub><span class="c009">i</span></sub> evaluates to <span class="c003">true</span>,
then <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">i</span></sub> is evaluated and its value returned as the result of the
matching, as usual. But if <span class="c010">cond</span><sub><span class="c009">i</span></sub> evaluates to <span class="c003">false</span>, the matching
is resumed against the patterns following <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">i</span></sub>.</p><!--TOC subsubsection id="sss:expr-localdef" Local definitions-->
<h4 class="subsubsection" id="sss:expr-localdef"><a class="section-anchor" href="#sss:expr-localdef" aria-hidden="true"></a>Local definitions</h4><!--SEC END --><p><a id="hevea_manual.kwd63"></a></p><p>The <span class="c004">let</span> and <span class="c002"><span class="c003">let</span> <span class="c003">rec</span></span> constructs bind value names locally.
The construct
</p><div class="center">
<span class="c004">let</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">and</span> … <span class="c004">and</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p>
evaluates <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> …  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> in some unspecified order and matches
their values against the patterns <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> …  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub>. If the
matchings succeed, <a class="syntax" href="#expr"><span class="c010">expr</span></a> is evaluated in the environment enriched by
the bindings performed during matching, and the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a> is
returned as the value of the whole <span class="c004">let</span> expression. If one of the
matchings fails, the exception <span class="c003">Match_failure</span> is raised.
<a id="hevea_manual3"></a></p><p>An alternate syntax is provided to bind variables to functional
values: instead of writing
</p><div class="center">
<span class="c004">let</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a> <span class="c002"><span class="c003">=</span> <span class="c003">fun</span></span>  <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub>1</sub> …  <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub><span class="c009">m</span></sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p>
in a <span class="c004">let</span> expression, one may instead write
</p><div class="center">
<span class="c004">let</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a>  <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub>1</sub> …  <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub><span class="c009">m</span></sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p><br>
Recursive definitions of names are introduced by <span class="c002"><span class="c003">let</span> <span class="c003">rec</span></span>:
</p><div class="center">
<span class="c002"><span class="c003">let</span> <span class="c003">rec</span></span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">and</span> … <span class="c004">and</span>  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub>
<span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p>
The only difference with the <span class="c004">let</span> construct described above is
that the bindings of names to values performed by the
pattern-matching are considered already performed when the expressions
<a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> to <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> are evaluated. That is, the expressions <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>
to <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> can reference identifiers that are bound by one of the
patterns <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub>, …,  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub>, and expect them to have the
same value as in <a class="syntax" href="#expr"><span class="c010">expr</span></a>, the body of the <span class="c002"><span class="c003">let</span> <span class="c003">rec</span></span> construct.</p><p>The recursive definition is guaranteed to behave as described above if
the expressions <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> to <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> are function definitions
(<span class="c004">fun</span> … or <span class="c004">function</span> …), and the patterns <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub>
…  <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub> are just value names, as in:
</p><div class="center">
<span class="c002"><span class="c003">let</span> <span class="c003">rec</span></span> <span class="c010">name</span><sub>1</sub> <span class="c002"><span class="c003">=</span> <span class="c003">fun</span></span> …
<span class="c004">and</span> …
<span class="c004">and</span>  <span class="c010">name</span><sub><span class="c009">n</span></sub> <span class="c002"><span class="c003">=</span> <span class="c003">fun</span></span> …
<span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p>
This defines <span class="c010">name</span><sub>1</sub> …  <span class="c010">name</span><sub><span class="c009">n</span></sub> as mutually recursive functions
local to <a class="syntax" href="#expr"><span class="c010">expr</span></a>.</p><p>The behavior of other forms of <span class="c002"><span class="c003">let</span> <span class="c003">rec</span></span> definitions is
implementation-dependent. The current implementation also supports
a certain class of recursive definitions of non-functional values,
as explained in section <a href="#s%3Aletrecvalues">8.1</a>.
</p>
<!--TOC subsubsection id="sss:expr-explicit-polytype" Explicit polymorphic type annotations-->
<h4 class="subsubsection" id="sss:expr-explicit-polytype"><a class="section-anchor" href="#sss:expr-explicit-polytype" aria-hidden="true"></a>Explicit polymorphic type annotations</h4><!--SEC END --><p>
(Introduced in OCaml 3.12)</p><p>Polymorphic type annotations in <span class="c004">let</span>-definitions behave in a way
similar to polymorphic methods:</p><div class="center">
<span class="c004">let</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> …  <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub><span class="c009">n</span></sub> <span class="c004">.</span>  <span class="c010">typeexpr</span> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> 
</div><p>These annotations explicitly require the defined value to be polymorphic,
and allow one to use this polymorphism in recursive occurrences
(when using <span class="c002"><span class="c003">let</span> <span class="c003">rec</span></span>). Note however that this is a normal polymorphic
type, unifiable with any instance of itself.</p><p>It is possible to define local exceptions in expressions:
 <span class="c004">let</span> <span class="c010">exception</span>  <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>  .
The syntactic scope of the exception constructor is the inner
expression, but nothing prevents exception values created with this
constructor from escaping this scope. Two executions of the definition
above result in two incompatible exception constructors (as for any
exception definition). For instance, the following assertion is
true:
</p><pre>  let gen () = let exception A in A
  let () = assert(gen () &lt;&gt; gen ())
</pre>
<!--TOC subsection id="ss:expr-control" 7.7.3  Control structures-->
<h3 class="subsection" id="ss:expr-control"><a class="section-anchor" href="#ss:expr-control" aria-hidden="true"></a>7.7.3  Control structures</h3><!--SEC END --><!--TOC subsubsection id="sss:expr-sequence" Sequence-->
<h4 class="subsubsection" id="sss:expr-sequence"><a class="section-anchor" href="#sss:expr-sequence" aria-hidden="true"></a>Sequence</h4><!--SEC END --><p>The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> evaluates <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> first, then
<a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub>, and returns the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub>.</p><!--TOC subsubsection id="sss:expr-conditional" Conditional-->
<h4 class="subsubsection" id="sss:expr-conditional"><a class="section-anchor" href="#sss:expr-conditional" aria-hidden="true"></a>Conditional</h4><!--SEC END --><p>
<a id="hevea_manual.kwd64"></a></p><p>The expression <span class="c004">if</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">then</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> <span class="c004">else</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub> evaluates to
the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> if <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> evaluates to the boolean <span class="c004">true</span>,
and to the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub> if <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> evaluates to the boolean
<span class="c004">false</span>.</p><p>The <span class="c004">else</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub> part can be omitted, in which case it defaults to
<span class="c002"><span class="c003">else</span> <span class="c003">()</span></span>.</p><!--TOC subsubsection id="sss:expr-case" Case expression-->
<h4 class="subsubsection" id="sss:expr-case"><a class="section-anchor" href="#sss:expr-case" aria-hidden="true"></a>Case expression</h4><!--SEC END --><p><a id="hevea_manual.kwd65"></a></p><p>The expression
</p><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018"><span class="c004">match</span></td><td class="c017"><span class="c012">expr</span> </td></tr>
<tr><td class="c018"><span class="c004">with</span></td><td class="c017"><span class="c012">pattern</span><sub>1</sub></td><td class="c017"><span class="c004">-&gt;</span></td><td class="c017"><span class="c012">expr</span><sub>1</sub> </td></tr>
<tr><td class="c018"><span class="c004">|</span></td><td class="c017">… </td></tr>
<tr><td class="c018"><span class="c004">|</span></td><td class="c017"><span class="c012">pattern</span><sub><span class="c009">n</span></sub></td><td class="c017"><span class="c004">-&gt;</span></td><td class="c017"><span class="c012">expr</span><sub><span class="c009">n</span></sub>
</td></tr>
</table></td></tr>
</table><p>
matches the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a> against the patterns <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> to
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub>. If the matching against <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">i</span></sub> succeeds, the
associated expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">i</span></sub> is evaluated, and its value becomes the
value of the whole <span class="c004">match</span> expression. The evaluation of
<a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">i</span></sub> takes place in an environment enriched by the bindings
performed during matching. If several patterns match the value of
<a class="syntax" href="#expr"><span class="c010">expr</span></a>, the one that occurs first in the <span class="c004">match</span> expression is
selected. If none of the patterns match the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a>, the
exception <span class="c003">Match_failure</span> is raised.
<a id="hevea_manual4"></a></p><!--TOC subsubsection id="sss:expr-boolean-operators" Boolean operators-->
<h4 class="subsubsection" id="sss:expr-boolean-operators"><a class="section-anchor" href="#sss:expr-boolean-operators" aria-hidden="true"></a>Boolean operators</h4><!--SEC END --><p>The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">&amp;&amp;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> evaluates to <span class="c004">true</span> if both
<a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> and <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> evaluate to <span class="c004">true</span>; otherwise, it evaluates to
<span class="c004">false</span>. The first component, <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>, is evaluated first. The
second component, <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub>, is not evaluated if the first component
evaluates to <span class="c004">false</span>. Hence, the expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">&amp;&amp;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> behaves
exactly as
</p><div class="center">
<span class="c004">if</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">then</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> <span class="c002"><span class="c003">else</span> <span class="c003">false</span></span>.
</div><p>The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">||</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> evaluates to <span class="c004">true</span> if one of
the expressions
<a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> and <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> evaluates to <span class="c004">true</span>; otherwise, it evaluates to
<span class="c004">false</span>. The first component, <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>, is evaluated first. The
second component, <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub>, is not evaluated if the first component
evaluates to <span class="c004">true</span>. Hence, the expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">||</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> behaves
exactly as
</p><div class="center">
<span class="c004">if</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c002"><span class="c003">then</span> <span class="c003">true</span> <span class="c003">else</span></span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub>.
</div><p><a id="hevea_manual.kwd66"></a>
The boolean operators <span class="c004">&amp;</span> and <span class="c004">or</span> are deprecated synonyms for
(respectively) <span class="c004">&amp;&amp;</span> and <span class="c004">||</span>.</p><!--TOC subsubsection id="sss:expr-loops" Loops-->
<h4 class="subsubsection" id="sss:expr-loops"><a class="section-anchor" href="#sss:expr-loops" aria-hidden="true"></a>Loops</h4><!--SEC END --><p><a id="hevea_manual.kwd67"></a>
The expression <span class="c004">while</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">do</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> <span class="c004">done</span> repeatedly
evaluates <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> while <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> evaluates to <span class="c004">true</span>. The loop
condition <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> is evaluated and tested at the beginning of each
iteration. The whole <span class="c004">while</span> … <span class="c004">done</span> expression evaluates to
the unit value <span class="c004">()</span>.</p><p><a id="hevea_manual.kwd68"></a>
The expression <span class="c002"><span class="c003">for</span> <span class="c010">name</span> <span class="c003">=</span></span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">to</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> <span class="c004">do</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub> <span class="c004">done</span>
first evaluates the expressions <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> and <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> (the boundaries)
into integer values <span class="c009">n</span> and <span class="c009">p</span>. Then, the loop body <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub> is
repeatedly evaluated in an environment where <span class="c010">name</span> is successively
bound to the values
<span class="c009">n</span>, <span class="c009">n</span>+1, …, <span class="c009">p</span>−1, <span class="c009">p</span>.
The loop body is never evaluated if <span class="c009">n</span> &gt; <span class="c009">p</span>.</p><p>The expression <span class="c002"><span class="c003">for</span> <span class="c010">name</span> <span class="c003">=</span></span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">downto</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> <span class="c004">do</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub> <span class="c004">done</span>
evaluates similarly, except that <span class="c010">name</span> is successively bound to the values
<span class="c009">n</span>, <span class="c009">n</span>−1, …, <span class="c009">p</span>+1, <span class="c009">p</span>.
The loop body is never evaluated if <span class="c009">n</span> &lt; <span class="c009">p</span>.</p><p>In both cases, the whole <span class="c004">for</span> expression evaluates to the unit
value <span class="c004">()</span>.</p><!--TOC subsubsection id="sss:expr-exception-handling" Exception handling-->
<h4 class="subsubsection" id="sss:expr-exception-handling"><a class="section-anchor" href="#sss:expr-exception-handling" aria-hidden="true"></a>Exception handling</h4><!--SEC END --><p>
<a id="hevea_manual.kwd69"></a></p><p>The expression
</p><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018"><span class="c004">try </span></td><td class="c017"><span class="c012">expr</span> </td></tr>
<tr><td class="c018"><span class="c004">with</span></td><td class="c017"><span class="c012">pattern</span><sub>1</sub></td><td class="c017"><span class="c004">-&gt;</span></td><td class="c017"><span class="c012">expr</span><sub>1</sub> </td></tr>
<tr><td class="c018"><span class="c004">|</span></td><td class="c017">… </td></tr>
<tr><td class="c018"><span class="c004">|</span></td><td class="c017"><span class="c012">pattern</span><sub><span class="c009">n</span></sub></td><td class="c017"><span class="c004">-&gt;</span></td><td class="c017"><span class="c012">expr</span><sub><span class="c009">n</span></sub>
</td></tr>
</table></td></tr>
</table><p>
evaluates the expression <a class="syntax" href="#expr"><span class="c010">expr</span></a> and returns its value if the
evaluation of <a class="syntax" href="#expr"><span class="c010">expr</span></a> does not raise any exception. If the evaluation
of <a class="syntax" href="#expr"><span class="c010">expr</span></a> raises an exception, the exception value is matched against
the patterns <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub>1</sub> to <a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">n</span></sub>. If the matching against
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a><sub><span class="c009">i</span></sub> succeeds, the associated expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">i</span></sub> is evaluated,
and its value becomes the value of the whole <span class="c004">try</span> expression. The
evaluation of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">i</span></sub> takes place in an environment enriched by the
bindings performed during matching. If several patterns match the value of
<a class="syntax" href="#expr"><span class="c010">expr</span></a>, the one that occurs first in the <span class="c004">try</span> expression is
selected. If none of the patterns matches the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a>, the
exception value is raised again, thereby transparently “passing
through” the <span class="c004">try</span> construct.</p>
<!--TOC subsection id="ss:expr-ops-on-data" 7.7.4  Operations on data structures-->
<h3 class="subsection" id="ss:expr-ops-on-data"><a class="section-anchor" href="#ss:expr-ops-on-data" aria-hidden="true"></a>7.7.4  Operations on data structures</h3><!--SEC END --><!--TOC subsubsection id="sss:expr-products" Products-->
<h4 class="subsubsection" id="sss:expr-products"><a class="section-anchor" href="#sss:expr-products" aria-hidden="true"></a>Products</h4><!--SEC END --><p>The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">,</span> … <span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> evaluates to the
<span class="c009">n</span>-tuple of the values of expressions <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> to <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub>. The
evaluation order of the subexpressions is not specified.</p><!--TOC subsubsection id="sss:expr-variants" Variants-->
<h4 class="subsubsection" id="sss:expr-variants"><a class="section-anchor" href="#sss:expr-variants" aria-hidden="true"></a>Variants</h4><!--SEC END --><p>The expression <a class="syntax" href="#constr"><span class="c010">constr</span></a>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> evaluates to the unary variant value
whose constructor is <a class="syntax" href="#constr"><span class="c010">constr</span></a>, and whose argument is the value of
<a class="syntax" href="#expr"><span class="c010">expr</span></a>. Similarly, the expression <a class="syntax" href="#constr"><span class="c010">constr</span></a> <span class="c004">(</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">,</span> … <span class="c004">,</span>
 <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> <span class="c004">)</span> evaluates to the n-ary variant value whose constructor is
<a class="syntax" href="#constr"><span class="c010">constr</span></a> and whose arguments are the values of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>, …,
 <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub>.</p><p>The expression <a class="syntax" href="#constr"><span class="c010">constr</span></a> <span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>, …,  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub><span class="c004">)</span> evaluates to the
variant value whose constructor is <a class="syntax" href="#constr"><span class="c010">constr</span></a>, and whose arguments are
the values of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> …  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub>.</p><p>For lists, some syntactic sugar is provided. The expression
<a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">::</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> stands for the constructor <span class="c002"><span class="c003">(</span> <span class="c003">::</span> <span class="c003">)</span></span> 
applied to the arguments <span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> <span class="c004">)</span>, and therefore
evaluates to the list whose head is the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> and whose tail
is the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub>. The expression <span class="c004">[</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">;</span> … <span class="c004">;</span>
 <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> <span class="c004">]</span> is equivalent to <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">::</span> … <span class="c004">::</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> <span class="c002"><span class="c003">::</span>
<span class="c003">[]</span></span>, and therefore evaluates to the list whose elements are the
values of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> to <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub>.</p><!--TOC subsubsection id="sss:expr-polyvars" Polymorphic variants-->
<h4 class="subsubsection" id="sss:expr-polyvars"><a class="section-anchor" href="#sss:expr-polyvars" aria-hidden="true"></a>Polymorphic variants</h4><!--SEC END --><p>The expression <span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> evaluates to the polymorphic variant
value whose tag is <a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>, and whose argument is the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a>.</p><!--TOC subsubsection id="sss:expr-records" Records-->
<h4 class="subsubsection" id="sss:expr-records"><a class="section-anchor" href="#sss:expr-records" aria-hidden="true"></a>Records</h4><!--SEC END --><p>The expression <span class="c004">{</span> <a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub>  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>] <span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">n</span></sub>  [<span class="c004">=</span>
<a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> <span class="c004">]}</span> evaluates to the record value
{ <span class="c009">field</span><sub>1</sub> = <span class="c009">v</span><sub>1</sub>; …; <span class="c009">field</span><sub><span class="c009">n</span></sub> = <span class="c009">v</span><sub><span class="c009">n</span></sub> }
where <span class="c009">v</span><sub><span class="c009">i</span></sub> is the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">i</span></sub> for <span class="c009">i</span> = 1,… , <span class="c009">n</span>.
A single identifier <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> stands for <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> <span class="c004">=</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub>,
and a qualified identifier <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> stands for
<a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> <span class="c004">=</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub>.
The fields <a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub> to <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">n</span></sub> must all belong to the same record
type; each field of this record type must appear exactly
once in the record expression, though they can appear in any
order. The order in which <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> to <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> are evaluated is not
specified. Optional type constraints can be added after each field
<span class="c004">{</span> <a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">;</span>… <span class="c004">;</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">n</span></sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> <span class="c004">}</span>
to force the type of <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> to be compatible with <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">k</span></sub>.</p><p>The expression
<span class="c004">{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">with</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub>  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>] <span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">n</span></sub>  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub>] <span class="c004">}</span>
builds a fresh record with fields <a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub> …  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">n</span></sub> equal to
<a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> …  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub>, and all other fields having the same value as
in the record <a class="syntax" href="#expr"><span class="c010">expr</span></a>. In other terms, it returns a shallow copy of
the record <a class="syntax" href="#expr"><span class="c010">expr</span></a>, except for the fields <a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub> …  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">n</span></sub>,
which are initialized to <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> …  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub>. As previously,
single identifier <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> stands for <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> <span class="c004">=</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub>,
a qualified identifier <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> stands for
<a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> <span class="c004">=</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">k</span></sub> and it is
possible to add an optional type constraint on each field being updated
with
<span class="c004">{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">with</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">n</span></sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> <span class="c004">}</span>.</p><p>The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">.</span>  <a class="syntax" href="#field"><span class="c010">field</span></a> evaluates <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> to a record
value, and returns the value associated to <a class="syntax" href="#field"><span class="c010">field</span></a> in this record
value.</p><p>The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">.</span>  <a class="syntax" href="#field"><span class="c010">field</span></a> <span class="c004">&lt;-</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> evaluates <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> to a record
value, which is then modified in-place by replacing the value
associated to <a class="syntax" href="#field"><span class="c010">field</span></a> in this record by the value of
<a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub>. This operation is permitted only if <a class="syntax" href="#field"><span class="c010">field</span></a> has been
declared <span class="c004">mutable</span> in the definition of the record type. The whole
expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">.</span>  <a class="syntax" href="#field"><span class="c010">field</span></a> <span class="c004">&lt;-</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> evaluates to the unit value
<span class="c004">()</span>.</p><!--TOC subsubsection id="sss:expr-arrays" Arrays-->
<h4 class="subsubsection" id="sss:expr-arrays"><a class="section-anchor" href="#sss:expr-arrays" aria-hidden="true"></a>Arrays</h4><!--SEC END --><p>The expression <span class="c004">[|</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> <span class="c004">|]</span> evaluates to
a <span class="c009">n</span>-element array, whose elements are initialized with the values of
<a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> to <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> respectively. The order in which these
expressions are evaluated is unspecified.</p><p>The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">.(</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> <span class="c004">)</span> returns the value of element
number <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> in the array denoted by <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>. The first element
has number 0; the last element has number <span class="c009">n</span>−1, where <span class="c009">n</span> is the
size of the array. The exception <span class="c003">Invalid_argument</span> is raised if the
access is out of bounds.</p><p>The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">.(</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> <span class="c002"><span class="c003">)</span> <span class="c003">&lt;-</span></span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub> modifies in-place
the array denoted by <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>, replacing element number <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> by
the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub>. The exception <span class="c003">Invalid_argument</span> is raised if
the access is out of bounds. The value of the whole expression is <span class="c004">()</span>.</p><!--TOC subsubsection id="sss:expr-strings" Strings-->
<h4 class="subsubsection" id="sss:expr-strings"><a class="section-anchor" href="#sss:expr-strings" aria-hidden="true"></a>Strings</h4><!--SEC END --><p>The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">.[</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> <span class="c004">]</span> returns the value of character
number <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> in the string denoted by <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>. The first character
has number 0; the last character has number <span class="c009">n</span>−1, where <span class="c009">n</span> is the
length of the string. The exception <span class="c003">Invalid_argument</span> is raised if the
access is out of bounds.</p><p>The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">.[</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> <span class="c002"><span class="c003">]</span> <span class="c003">&lt;-</span></span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub> modifies in-place
the string denoted by <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>, replacing character number <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> by
the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub>. The exception <span class="c003">Invalid_argument</span> is raised if
the access is out of bounds. The value of the whole expression is <span class="c004">()</span>.</p><p><span class="c013">Note:</span> this possibility is offered only for backward
compatibility with older versions of OCaml and will be removed in a
future version. New code should use byte sequences and the <span class="c003">Bytes.set</span>
function.</p>
<!--TOC subsection id="ss:expr-operators" 7.7.5  Operators-->
<h3 class="subsection" id="ss:expr-operators"><a class="section-anchor" href="#ss:expr-operators" aria-hidden="true"></a>7.7.5  Operators</h3><!--SEC END --><p>
<a id="hevea_manual.kwd70"></a>
<a id="hevea_manual.kwd71"></a>
<a id="hevea_manual.kwd72"></a>
<a id="hevea_manual.kwd73"></a>
<a id="hevea_manual.kwd74"></a>
<a id="hevea_manual.kwd75"></a>
<a id="hevea_manual.kwd76"></a></p><p>Symbols from the class <a class="syntax" href="#infix-symbol"><span class="c010">infix-symbol</span></a>, as well as the keywords
<span class="c004">*</span>, <span class="c004">+</span>, <span class="c004">-</span>, <span class="c004">-.</span>, <span class="c004">=</span>, <span class="c004">!=</span>, <span class="c004">&lt;</span>, <span class="c004">&gt;</span>, <span class="c004">or</span>, <span class="c004">||</span>,
<span class="c004">&amp;</span>, <span class="c004">&amp;&amp;</span>, <span class="c004">:=</span>, <span class="c004">mod</span>, <span class="c004">land</span>, <span class="c004">lor</span>, <span class="c004">lxor</span>, <span class="c004">lsl</span>, <span class="c004">lsr</span>,
and <span class="c004">asr</span> can appear in infix position (between two
expressions). Symbols from the class <a class="syntax" href="#prefix-symbol"><span class="c010">prefix-symbol</span></a>, as well as
the keywords <span class="c004">-</span> and <span class="c004">-.</span>
can appear in prefix position (in front of an expression).</p><p>Infix and prefix symbols do not have a fixed meaning: they are simply
interpreted as applications of functions bound to the names
corresponding to the symbols. The expression <a class="syntax" href="#prefix-symbol"><span class="c010">prefix-symbol</span></a>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> is
interpreted as the application <span class="c004">(</span> <a class="syntax" href="#prefix-symbol"><span class="c010">prefix-symbol</span></a> <span class="c004">)</span>
 <a class="syntax" href="#expr"><span class="c010">expr</span></a>. Similarly, the expression <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>  <a class="syntax" href="#infix-symbol"><span class="c010">infix-symbol</span></a>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> is
interpreted as the application <span class="c004">(</span> <a class="syntax" href="#infix-symbol"><span class="c010">infix-symbol</span></a> <span class="c004">)</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub>.</p><p>The table below lists the symbols defined in the initial environment
and their initial meaning. (See the description of the core
library module <span class="c003">Stdlib</span> in chapter <a href="#c%3Acorelib">25</a> for more
details). Their meaning may be changed at any time using
<span class="c002"><span class="c003">let</span> <span class="c003">(</span></span> <a class="syntax" href="#infix-op"><span class="c010">infix-op</span></a> <span class="c004">)</span>  <span class="c010">name</span><sub>1</sub>  <span class="c010">name</span><sub>2</sub> <span class="c004">=</span> …</p><p>Note: the operators <span class="c004">&amp;&amp;</span>, <span class="c004">||</span>, and <span class="c004">~-</span> are handled specially
and it is not advisable to change their meaning.</p><p>The keywords <span class="c004">-</span> and <span class="c004">-.</span> can appear both as infix and
prefix operators. When they appear as prefix operators, they are
interpreted respectively as the functions <span class="c004">(~-)</span> and <span class="c004">(~-.)</span>.</p><p><a id="hevea_manual.kwd77"></a><a id="hevea_manual.kwd78"></a><a id="hevea_manual.kwd79"></a><a id="hevea_manual.kwd80"></a><a id="hevea_manual.kwd81"></a><a id="hevea_manual.kwd82"></a><a id="hevea_manual.kwd83"></a></p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Operator</span></td><td class="c014"><span class="c013">Initial meaning</span> </td></tr>
<tr><td class="c022">
<span class="c003">+</span></td><td class="c021">Integer addition. </td></tr>
<tr><td class="c022"><span class="c003">-</span> (infix)</td><td class="c021">Integer subtraction. </td></tr>
<tr><td class="c022"><span class="c003">~-   -</span> (prefix)</td><td class="c021">Integer negation. </td></tr>
<tr><td class="c022"><span class="c003">*</span></td><td class="c021">Integer multiplication. </td></tr>
<tr><td class="c022"><span class="c003">/</span></td><td class="c021">Integer division.
Raise <span class="c003">Division_by_zero</span> if second argument is zero. </td></tr>
<tr><td class="c022"><span class="c003">mod</span></td><td class="c021">Integer modulus. Raise
<span class="c003">Division_by_zero</span> if second argument is zero. </td></tr>
<tr><td class="c022"><span class="c003">land</span></td><td class="c021">Bitwise logical “and” on integers. </td></tr>
<tr><td class="c022"><span class="c003">lor</span></td><td class="c021">Bitwise logical “or” on integers. </td></tr>
<tr><td class="c022"><span class="c003">lxor</span></td><td class="c021">Bitwise logical “exclusive or” on integers. </td></tr>
<tr><td class="c022"><span class="c003">lsl</span></td><td class="c021">Bitwise logical shift left on integers. </td></tr>
<tr><td class="c022"><span class="c003">lsr</span></td><td class="c021">Bitwise logical shift right on integers. </td></tr>
<tr><td class="c022"><span class="c003">asr</span></td><td class="c021">Bitwise arithmetic shift right on integers. </td></tr>
<tr><td class="c022"><span class="c003">+.</span></td><td class="c021">Floating-point addition. </td></tr>
<tr><td class="c022"><span class="c003">-.</span> (infix)</td><td class="c021">Floating-point subtraction. </td></tr>
<tr><td class="c022"><span class="c003">~-.   -.</span> (prefix)</td><td class="c021">Floating-point negation. </td></tr>
<tr><td class="c022"><span class="c003">*.</span></td><td class="c021">Floating-point multiplication. </td></tr>
<tr><td class="c022"><span class="c003">/.</span></td><td class="c021">Floating-point division. </td></tr>
<tr><td class="c022"><span class="c003">**</span></td><td class="c021">Floating-point exponentiation. </td></tr>
<tr><td class="c022"><span class="c003">@</span> </td><td class="c021">List concatenation. </td></tr>
<tr><td class="c022"><span class="c003">^</span> </td><td class="c021">String concatenation. </td></tr>
<tr><td class="c022"><span class="c003">!</span> </td><td class="c021">Dereferencing (return the current
contents of a reference). </td></tr>
<tr><td class="c022"><span class="c003">:=</span></td><td class="c021">Reference assignment (update the
reference given as first argument with the value of the second
argument). </td></tr>
<tr><td class="c022"><span class="c003">=</span> </td><td class="c021">Structural equality test. </td></tr>
<tr><td class="c022"><span class="c003">&lt;&gt;</span> </td><td class="c021">Structural inequality test. </td></tr>
<tr><td class="c022"><span class="c003">==</span> </td><td class="c021">Physical equality test. </td></tr>
<tr><td class="c022"><span class="c003">!=</span> </td><td class="c021">Physical inequality test. </td></tr>
<tr><td class="c022"><span class="c003">&lt;</span> </td><td class="c021">Test “less than”. </td></tr>
<tr><td class="c022"><span class="c003">&lt;=</span> </td><td class="c021">Test “less than or equal”. </td></tr>
<tr><td class="c022"><span class="c003">&gt;</span> </td><td class="c021">Test “greater than”. </td></tr>
<tr><td class="c022"><span class="c003">&gt;=</span> </td><td class="c021">Test “greater than or equal”. </td></tr>
<tr><td class="c022"><span class="c003">&amp;&amp;   &amp;</span></td><td class="c021">Boolean conjunction. </td></tr>
<tr><td class="c022"><span class="c003">||   or</span></td><td class="c021">Boolean disjunction. </td></tr>
</table></div></div>
<!--TOC subsection id="ss:expr-obj" 7.7.6  Objects-->
<h3 class="subsection" id="ss:expr-obj"><a class="section-anchor" href="#ss:expr-obj" aria-hidden="true"></a>7.7.6  Objects</h3><!--SEC END --><p> <a id="s:objects"></a></p><!--TOC subsubsection id="sss:expr-obj-creation" Object creation-->
<h4 class="subsubsection" id="sss:expr-obj-creation"><a class="section-anchor" href="#sss:expr-obj-creation" aria-hidden="true"></a>Object creation</h4><!--SEC END --><p><a id="hevea_manual.kwd84"></a></p><p>When <a class="syntax" href="#class-path"><span class="c010">class-path</span></a> evaluates to a class body, <span class="c004">new</span> <a class="syntax" href="#class-path"><span class="c010">class-path</span></a>
evaluates to a new object containing the instance variables and
methods of this class.</p><p>When <a class="syntax" href="#class-path"><span class="c010">class-path</span></a> evaluates to a class function, <span class="c004">new</span> <a class="syntax" href="#class-path"><span class="c010">class-path</span></a>
evaluates to a function expecting the same number of arguments and
returning a new object of this class.</p><!--TOC subsubsection id="sss:expr-obj-immediate" Immediate object creation-->
<h4 class="subsubsection" id="sss:expr-obj-immediate"><a class="section-anchor" href="#sss:expr-obj-immediate" aria-hidden="true"></a>Immediate object creation</h4><!--SEC END --><p><a id="hevea_manual.kwd85"></a></p><p>Creating directly an object through the <span class="c004">object</span> <a class="syntax" href="#class-body"><span class="c010">class-body</span></a> <span class="c004">end</span>
construct is operationally equivalent to defining locally a <span class="c004">class</span>
<a class="syntax" href="#class-name"><span class="c010">class-name</span></a> <span class="c002"><span class="c003">=</span> <span class="c003">object</span></span>  <a class="syntax" href="#class-body"><span class="c010">class-body</span></a> <span class="c004">end</span> —see sections
<a href="#sss%3Aclass-body">7.9.2</a> and following for the syntax of <a class="syntax" href="#class-body"><span class="c010">class-body</span></a>—
and immediately creating a single object from it by <span class="c004">new</span> <a class="syntax" href="#class-name"><span class="c010">class-name</span></a>.</p><p>The typing of immediate objects is slightly different from explicitly
defining a class in two respects. First, the inferred object type may
contain free type variables. Second, since the class body of an
immediate object will never be extended, its self type can be unified
with a closed object type.</p><!--TOC subsubsection id="sss:expr-method" Method invocation-->
<h4 class="subsubsection" id="sss:expr-method"><a class="section-anchor" href="#sss:expr-method" aria-hidden="true"></a>Method invocation</h4><!--SEC END --><p>The expression <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">#</span>  <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> invokes the method
<a class="syntax" href="#method-name"><span class="c010">method-name</span></a> of the object denoted by <a class="syntax" href="#expr"><span class="c010">expr</span></a>.</p><p>If <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> is a polymorphic method, its type should be known at
the invocation site. This is true for instance if <a class="syntax" href="#expr"><span class="c010">expr</span></a> is the name
of a fresh object (<span class="c004">let</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a> = <span class="c004">new</span>  <a class="syntax" href="#class-path"><span class="c010">class-path</span></a> … ) or if
there is a type constraint. Principality of the derivation can be
checked in the <span class="c003">-principal</span> mode.</p><!--TOC subsubsection id="sss:expr-obj-variables" Accessing and modifying instance variables-->
<h4 class="subsubsection" id="sss:expr-obj-variables"><a class="section-anchor" href="#sss:expr-obj-variables" aria-hidden="true"></a>Accessing and modifying instance variables</h4><!--SEC END --><p>The instance variables of a class are visible only in the body of the
methods defined in the same class or a class that inherits from the
class defining the instance variables. The expression <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a>
evaluates to the value of the given instance variable. The expression
<a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">&lt;-</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> assigns the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a> to the instance
variable <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a>, which must be mutable. The whole expression
<a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">&lt;-</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> evaluates to <span class="c004">()</span>.</p><!--TOC subsubsection id="sss:expr-obj-duplication" Object duplication-->
<h4 class="subsubsection" id="sss:expr-obj-duplication"><a class="section-anchor" href="#sss:expr-obj-duplication" aria-hidden="true"></a>Object duplication</h4><!--SEC END --><p>An object can be duplicated using the library function <span class="c003">Oo.copy</span>
(see module <a href="libref/Oo.html"><span class="c003">Oo</span></a>). Inside a method, the expression
 <span class="c004">{&lt;</span> [<a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a>  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>]  { <span class="c004">;</span> <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a>  [<span class="c004">=</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>] }] <span class="c004">&gt;}</span>
returns a copy of self with the given instance variables replaced by
the values of the associated expressions. A single instance variable
name <span class="c010">id</span> stands for <span class="c010">id</span> <span class="c004">=</span>  <span class="c010">id</span>. Other instance variables have the same
value in the returned object as in self.</p>
<!--TOC subsection id="ss:expr-coercions" 7.7.7  Coercions-->
<h3 class="subsection" id="ss:expr-coercions"><a class="section-anchor" href="#ss:expr-coercions" aria-hidden="true"></a>7.7.7  Coercions</h3><!--SEC END --><p>Expressions whose type contains object or polymorphic variant types
can be explicitly coerced (weakened) to a supertype.
The expression <span class="c004">(</span><a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">:&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><span class="c004">)</span> coerces the expression <a class="syntax" href="#expr"><span class="c010">expr</span></a>
to type <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>.
The expression <span class="c004">(</span><a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">:&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>2</sub><span class="c004">)</span> coerces the
expression <a class="syntax" href="#expr"><span class="c010">expr</span></a> from type <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> to type <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>2</sub>.</p><p>The former operator will sometimes fail to coerce an expression <a class="syntax" href="#expr"><span class="c010">expr</span></a>
from a type <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> to a type <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>2</sub>
even if type <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> is a subtype of type
<a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>2</sub>: in the current implementation it only expands two levels of
type abbreviations containing objects and/or polymorphic variants,
keeping only recursion when it is explicit in the class type (for objects).
As an exception to the above algorithm, if both the inferred type of <a class="syntax" href="#expr"><span class="c010">expr</span></a>
and <a class="syntax" href="#typexpr"><span class="c010">typ</span></a> are ground (<em>i.e.</em> do not contain type variables), the
former operator behaves as the latter one, taking the inferred type of
<a class="syntax" href="#expr"><span class="c010">expr</span></a> as <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub>. In case of failure with the former operator,
the latter one should be used.</p><p>It is only possible to coerce an expression <a class="syntax" href="#expr"><span class="c010">expr</span></a> from type
<a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> to type <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>2</sub>, if the type of <a class="syntax" href="#expr"><span class="c010">expr</span></a> is an instance of
<a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> (like for a type annotation), and <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> is a subtype
of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>2</sub>. The type of the coerced expression is an
instance of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>2</sub>. If the types contain variables,
they may be instantiated by the subtyping algorithm, but this is only
done after determining whether <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> is a potential subtype of
<a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>2</sub>. This means that typing may fail during this latter
unification step, even if some instance of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> is a subtype of
some instance of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>2</sub>.
In the following paragraphs we describe the subtyping relation used.</p><!--TOC subsubsection id="sss:expr-obj-types" Object types-->
<h4 class="subsubsection" id="sss:expr-obj-types"><a class="section-anchor" href="#sss:expr-obj-types" aria-hidden="true"></a>Object types</h4><!--SEC END --><p>A fixed object type admits as subtype any object type that includes all
its methods. The types of the methods shall be subtypes of those in
the supertype. Namely,
</p><div class="center">
 <span class="c004">&lt;</span> <a class="syntax" href="#method-name"><span class="c010">met</span></a><sub>1</sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> <span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#method-name"><span class="c010">met</span></a><sub><span class="c009">n</span></sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub><span class="c009">n</span></sub> <span class="c004">&gt;</span> 
</div><p>
is a supertype of
</p><div class="center">
 <span class="c004">&lt;</span> <a class="syntax" href="#method-name"><span class="c010">met</span></a><sub>1</sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub>1</sub> <span class="c004">;</span> … <span class="c004">;</span> <a class="syntax" href="#method-name"><span class="c010">met</span></a><sub><span class="c009">n</span></sub> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub><span class="c009">n</span></sub> <span class="c004">;</span>
<a class="syntax" href="#method-name"><span class="c010">met</span></a><sub><span class="c009">n</span>+1</sub> <span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub><span class="c009">n</span>+1</sub> <span class="c004">;</span> … <span class="c004">;</span> <a class="syntax" href="#method-name"><span class="c010">met</span></a><sub><span class="c009">n</span>+<span class="c009">m</span></sub> <span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub><span class="c009">n</span>+<span class="c009">m</span></sub>
 [<span class="c002"><span class="c003">;</span> <span class="c003">..</span></span>] <span class="c004">&gt;</span> 
</div><p>
which may contain an ellipsis <span class="c003">..</span> if every <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub><span class="c009">i</span></sub> is a supertype of
the corresponding <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub><span class="c009">i</span></sub>.</p><p>A monomorphic method type can be a supertype of a polymorphic method
type. Namely, if <a class="syntax" href="#typexpr"><span class="c010">typ</span></a> is an instance of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′, then  <span class="c004">'</span><span class="c010">a</span><sub>1</sub>
… <span class="c004">'</span><span class="c010">a</span><sub><span class="c009">n</span></sub> <span class="c004">.</span> <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′ is a subtype of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>.</p><p>Inside a class definition, newly defined types are not available for
subtyping, as the type abbreviations are not yet completely
defined. There is an exception for coercing <span class="c010">self</span> to the (exact)
type of its class: this is allowed if the type of <span class="c010">self</span> does not
appear in a contravariant position in the class type, <em>i.e.</em> if
there are no binary methods.</p><!--TOC subsubsection id="sss:expr-polyvar-types" Polymorphic variant types-->
<h4 class="subsubsection" id="sss:expr-polyvar-types"><a class="section-anchor" href="#sss:expr-polyvar-types" aria-hidden="true"></a>Polymorphic variant types</h4><!--SEC END --><p>A polymorphic variant type <a class="syntax" href="#typexpr"><span class="c010">typ</span></a> is a subtype of another polymorphic
variant type <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′ if the upper bound of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a> (<em>i.e.</em> the
maximum set of constructors that may appear in an instance of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>)
is included in the lower bound of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′, and the types of arguments
for the constructors of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a> are subtypes of those in
<a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′. Namely,
</p><div class="center">
 <span class="c004">[</span>[<span class="c004">&lt;</span>] <span class="c004">`</span><a class="syntax" href="#constr-name"><span class="c010">C</span></a><sub>1</sub> <span class="c004">of</span>  <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> <span class="c004">|</span> … <span class="c002"><span class="c003">|</span> <span class="c003">`</span></span> <a class="syntax" href="#constr-name"><span class="c010">C</span></a><sub><span class="c009">n</span></sub> <span class="c004">of</span>  <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub><span class="c009">n</span></sub> <span class="c004">]</span> 
</div><p>
which may be a shrinkable type, is a subtype of
</p><div class="center">
 <span class="c004">[</span>[<span class="c004">&gt;</span>] <span class="c004">`</span><a class="syntax" href="#constr-name"><span class="c010">C</span></a><sub>1</sub> <span class="c004">of</span>  <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub>1</sub> <span class="c004">|</span> … <span class="c002"><span class="c003">|</span> <span class="c003">`</span></span><a class="syntax" href="#constr-name"><span class="c010">C</span></a><sub><span class="c009">n</span></sub> <span class="c004">of</span>  <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub><span class="c009">n</span></sub>
<span class="c002"><span class="c003">|</span> <span class="c003">`</span></span><a class="syntax" href="#constr-name"><span class="c010">C</span></a><sub><span class="c009">n</span>+1</sub> <span class="c004">of</span> <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub><span class="c009">n</span>+1</sub> <span class="c004">|</span> … <span class="c002"><span class="c003">|</span> <span class="c003">`</span></span><a class="syntax" href="#constr-name"><span class="c010">C</span></a><sub><span class="c009">n</span>+<span class="c009">m</span></sub> <span class="c004">of</span>
<a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub><span class="c009">n</span>+<span class="c009">m</span></sub> <span class="c004">]</span> 
</div><p>
which may be an extensible type, if every <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub><span class="c009">i</span></sub> is a subtype of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub><span class="c009">i</span></sub>.</p><!--TOC subsubsection id="sss:expr-variance" Variance-->
<h4 class="subsubsection" id="sss:expr-variance"><a class="section-anchor" href="#sss:expr-variance" aria-hidden="true"></a>Variance</h4><!--SEC END --><p>Other types do not introduce new subtyping, but they may propagate the
subtyping of their arguments. For instance, <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> <span class="c004">*</span>  <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>2</sub> is a
subtype of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub>1</sub> <span class="c004">*</span> <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub>2</sub> when <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> and <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>2</sub> are
respectively subtypes of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub>1</sub> and <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub>2</sub>.
For function types, the relation is more subtle:
<a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>2</sub> is a subtype of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub>1</sub> <span class="c004">-&gt;</span> <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub>2</sub>
if <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>1</sub> is a supertype of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub>1</sub> and <a class="syntax" href="#typexpr"><span class="c010">typ</span></a><sub>2</sub> is a
subtype of <a class="syntax" href="#typexpr"><span class="c010">typ</span></a>′<sub>2</sub>. For this reason, function types are covariant in
their second argument (like tuples), but contravariant in their first
argument. Mutable types, like <span class="c003">array</span> or <span class="c003">ref</span> are neither covariant
nor contravariant, they are nonvariant, that is they do not propagate
subtyping.</p><p>For user-defined types, the variance is automatically inferred: a
parameter is covariant if it has only covariant occurrences,
contravariant if it has only contravariant occurrences,
variance-free if it has no occurrences, and nonvariant otherwise.
A variance-free parameter may change freely through subtyping, it does
not have to be a subtype or a supertype.
For abstract and private types, the variance must be given explicitly
(see section <a href="#ss%3Atypedefs">7.8.1</a>),
otherwise the default is nonvariant. This is also the case for
constrained arguments in type definitions.</p>
<!--TOC subsection id="ss:expr-other" 7.7.8  Other-->
<h3 class="subsection" id="ss:expr-other"><a class="section-anchor" href="#ss:expr-other" aria-hidden="true"></a>7.7.8  Other</h3><!--SEC END --><!--TOC subsubsection id="sss:expr-assertion" Assertion checking-->
<h4 class="subsubsection" id="sss:expr-assertion"><a class="section-anchor" href="#sss:expr-assertion" aria-hidden="true"></a>Assertion checking</h4><!--SEC END --><p><a id="hevea_manual.kwd86"></a></p><p>OCaml supports the <span class="c004">assert</span> construct to check debugging assertions.
The expression <span class="c004">assert</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> evaluates the expression <a class="syntax" href="#expr"><span class="c010">expr</span></a> and
returns <span class="c004">()</span> if <a class="syntax" href="#expr"><span class="c010">expr</span></a> evaluates to <span class="c004">true</span>. If it evaluates to
<span class="c004">false</span> the exception
<span class="c003">Assert_failure</span> is raised with the source file name and the
location of <a class="syntax" href="#expr"><span class="c010">expr</span></a> as arguments. Assertion
checking can be turned off with the <span class="c003">-noassert</span> compiler option. In
this case, <a class="syntax" href="#expr"><span class="c010">expr</span></a> is not evaluated at all.</p><p>As a special case, <span class="c004">assert false</span> is reduced to
<span class="c004">raise</span> <span class="c003"><span class="c002">(</span>Assert_failure ...<span class="c002">)</span></span>, which gives it a polymorphic
type. This means that it can be used in place of any expression (for
example as a branch of any pattern-matching). It also means that
the <span class="c004">assert false</span> “assertions” cannot be turned off by the
<span class="c003">-noassert</span> option.
<a id="hevea_manual5"></a></p><!--TOC subsubsection id="sss:expr-lazy" Lazy expressions-->
<h4 class="subsubsection" id="sss:expr-lazy"><a class="section-anchor" href="#sss:expr-lazy" aria-hidden="true"></a>Lazy expressions</h4><!--SEC END --><p>
<a id="hevea_manual.kwd87"></a></p><p>The expression <span class="c004">lazy</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> returns a value <span class="c009">v</span> of type <span class="c003">Lazy.t</span> that
encapsulates the computation of <a class="syntax" href="#expr"><span class="c010">expr</span></a>. The argument <a class="syntax" href="#expr"><span class="c010">expr</span></a> is not
evaluated at this point in the program. Instead, its evaluation will
be performed the first time the function <span class="c003">Lazy.force</span> is applied to the value
<span class="c009">v</span>, returning the actual value of <a class="syntax" href="#expr"><span class="c010">expr</span></a>. Subsequent applications
of <span class="c003">Lazy.force</span> to <span class="c009">v</span> do not evaluate <a class="syntax" href="#expr"><span class="c010">expr</span></a> again. Applications
of <span class="c003">Lazy.force</span> may be implicit through pattern matching (see <a href="#sss%3Apat-lazy">7.6</a>).</p><!--TOC subsubsection id="sss:expr-local-modules" Local modules-->
<h4 class="subsubsection" id="sss:expr-local-modules"><a class="section-anchor" href="#sss:expr-local-modules" aria-hidden="true"></a>Local modules</h4><!--SEC END --><p>
<a id="hevea_manual.kwd88"></a>
<a id="hevea_manual.kwd89"></a></p><p>The expression
<span class="c002"><span class="c003">let</span> <span class="c003">module</span></span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
locally binds the module expression <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> to the identifier
<a class="syntax" href="#module-name"><span class="c010">module-name</span></a> during the evaluation of the expression <a class="syntax" href="#expr"><span class="c010">expr</span></a>.
It then returns the value of <a class="syntax" href="#expr"><span class="c010">expr</span></a>. For example:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> remove_duplicates comparison_fun string_list =
   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">module</span> StringSet =
     Set.Make(<span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">type</span> t = string
                     <span class="ocamlkeyword">let</span> compare = comparison_fun <span class="ocamlkeyword">end</span>) <span class="ocamlkeyword">in</span>
   StringSet.elements
     (List.fold_right StringSet.add string_list StringSet.empty)</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> remove_duplicates :
  (string -&gt; string -&gt; int) -&gt; string list -&gt; string list = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><!--TOC subsubsection id="sss:local-opens" Local opens-->
<h4 class="subsubsection" id="sss:local-opens"><a class="section-anchor" href="#sss:local-opens" aria-hidden="true"></a>Local opens</h4><!--SEC END --><p>
<a id="hevea_manual.kwd90"></a>
<a id="hevea_manual.kwd91"></a></p><p>The expressions <span class="c002"><span class="c003">let</span> <span class="c003">open</span></span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> and
<a class="syntax" href="#module-path"><span class="c010">module-path</span></a><span class="c004">.(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><span class="c004">)</span> are strictly equivalent. These
constructions locally open the module referred to by the module path
<a class="syntax" href="#module-path"><span class="c010">module-path</span></a> in the respective scope of the expression <a class="syntax" href="#expr"><span class="c010">expr</span></a>.</p><p>When the body of a local open expression is delimited by
<span class="c002"><span class="c003">[</span> <span class="c003">]</span></span>, <span class="c002"><span class="c003">[|</span> <span class="c003">|]</span></span>, or <span class="c002"><span class="c003">{</span> <span class="c003">}</span></span>, the parentheses can be omitted.
For expression, parentheses can also be omitted for <span class="c002"><span class="c003">{&lt;</span> <span class="c003">&gt;}</span></span>.
For example, <a class="syntax" href="#module-path"><span class="c010">module-path</span></a><span class="c004">.[</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><span class="c004">]</span> is equivalent to
<a class="syntax" href="#module-path"><span class="c010">module-path</span></a><span class="c004">.([</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><span class="c004">])</span>, and <a class="syntax" href="#module-path"><span class="c010">module-path</span></a><span class="c004">.[|</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">|]</span> is
equivalent to <a class="syntax" href="#module-path"><span class="c010">module-path</span></a><span class="c004">.([|</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">|])</span>.</p>
<!--TOC section id="s:tydef" 7.8  Type and exception definitions-->
<h2 class="section" id="s:tydef"><a class="section-anchor" href="#s:tydef" aria-hidden="true"></a>7.8  Type and exception definitions</h2><!--SEC END --><!--NAME typedecl.html-->

<!--TOC subsection id="ss:typedefs" 7.8.1  Type definitions-->
<h3 class="subsection" id="ss:typedefs"><a class="section-anchor" href="#ss:typedefs" aria-hidden="true"></a>7.8.1  Type definitions</h3><!--SEC END --><p>Type definitions bind type constructors to data types: either
variant types, record types, type abbreviations, or abstract data
types. They also bind the value constructors and record fields
associated with the definition.</p><p><a id="hevea_manual.kwd92"></a>
<a id="hevea_manual.kwd93"></a>
<a id="hevea_manual.kwd94"></a>
<a id="hevea_manual.kwd95"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="type-definition"><span class="c010">type-definition</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">type</span> [<span class="c004">nonrec</span>] <a class="syntax" href="#typedef"><span class="c010">typedef</span></a>  { <span class="c004">and</span> <a class="syntax" href="#typedef"><span class="c010">typedef</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="typedef"><span class="c010">typedef</span></a></td><td class="c015">::=</td><td class="c017">
[<a class="syntax" href="#type-params"><span class="c010">type-params</span></a>]  <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a>  <a class="syntax" href="#type-information"><span class="c010">type-information</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="type-information"><span class="c010">type-information</span></a></td><td class="c015">::=</td><td class="c017">
[<a class="syntax" href="#type-equation"><span class="c010">type-equation</span></a>]  [<a class="syntax" href="#type-representation"><span class="c010">type-representation</span></a>]  { <a class="syntax" href="#type-constraint"><span class="c010">type-constraint</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="type-equation"><span class="c010">type-equation</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">=</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="type-representation"><span class="c010">type-representation</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">=</span> [<span class="c004">|</span>] <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a>  { <span class="c004">|</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">=</span> <a class="syntax" href="#record-decl"><span class="c010">record-decl</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">=</span> <span class="c004">|</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="type-params"><span class="c010">type-params</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#type-param"><span class="c010">type-param</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#type-param"><span class="c010">type-param</span></a>  { <span class="c004">,</span> <a class="syntax" href="#type-param"><span class="c010">type-param</span></a> } <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="type-param"><span class="c010">type-param</span></a></td><td class="c015">::=</td><td class="c017">
[<a class="syntax" href="#variance"><span class="c010">variance</span></a>] <span class="c004">'</span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="variance"><span class="c010">variance</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">+</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">-</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="record-decl"><span class="c010">record-decl</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">{</span> <a class="syntax" href="#field-decl"><span class="c010">field-decl</span></a>  { <span class="c004">;</span> <a class="syntax" href="#field-decl"><span class="c010">field-decl</span></a> }  [<span class="c004">;</span>] <span class="c004">}</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="constr-decl"><span class="c010">constr-decl</span></a></td><td class="c015">::=</td><td class="c017">
(<a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a> ∣  <span class="c004">[]</span> ∣  <span class="c004">(::)</span>) [ <span class="c004">of</span> <a class="syntax" href="#constr-args"><span class="c010">constr-args</span></a> ]
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="constr-args"><span class="c010">constr-args</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  { <span class="c004">*</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="field-decl"><span class="c010">field-decl</span></a></td><td class="c015">::=</td><td class="c017">
[<span class="c004">mutable</span>] <a class="syntax" href="#field-name"><span class="c010">field-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="type-constraint"><span class="c010">type-constraint</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">constraint</span> <span class="c004">'</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a> <span class="c004">=</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
</td></tr>
</table></td></tr>
</table></div><p>
<a id="hevea_manual.kwd96"></a>
<a id="hevea_manual.kwd97"></a>
See also the following language extensions:
<a href="#s%3Aprivate-types">private types</a>,
<a href="#s%3Agadts">generalized algebraic datatypes</a>,
<a href="#s%3Aattributes">attributes</a>,
<a href="#s%3Aextension-nodes">extension nodes</a>,
<a href="#s%3Aextensible-variants">extensible variant types</a> and
<a href="#s%3Ainline-records">inline records</a>.</p><p>Type definitions are introduced by the <span class="c003">type</span> keyword, and
consist in one or several simple definitions, possibly mutually
recursive, separated by the <span class="c003">and</span> keyword. Each simple definition
defines one type constructor.</p><p>A simple definition consists in a lowercase identifier, possibly
preceded by one or several type parameters, and followed by an
optional type equation, then an optional type representation, and then
a constraint clause. The identifier is the name of the type
constructor being defined.</p><p>In the right-hand side of type definitions, references to one of the
type constructor name being defined are considered as recursive,
unless <span class="c003">type</span> is followed by <span class="c003">nonrec</span>. The <span class="c003">nonrec</span> keyword was
introduced in OCaml 4.02.2.</p><p>The optional type parameters are either one type variable <span class="c004">'</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a>,
for type constructors with one parameter, or a list of type variables
<span class="c004">('</span><a class="syntax" href="#ident"><span class="c010">ident</span></a><sub>1</sub>,…,<span class="c004">'</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a><sub><span class="c009">n</span></sub><span class="c004">)</span>, for type constructors with several
parameters. Each type parameter may be prefixed by a variance
constraint <span class="c004">+</span> (resp. <span class="c004">-</span>) indicating that the parameter is
covariant (resp. contravariant). These type parameters can appear in
the type expressions of the right-hand side of the definition,
optionally restricted by a variance constraint ; <em>i.e.</em> a
covariant parameter may only appear on the right side of a functional
arrow (more precisely, follow the left branch of an even number of
arrows), and a contravariant parameter only the left side (left branch of
an odd number of arrows). If the type has a representation or
an equation, and the parameter is free (<em>i.e.</em> not bound via a
type constraint to a constructed type), its variance constraint is
checked but subtyping <em>etc.</em> will use the inferred variance of the
parameter, which may be less restrictive; otherwise (<em>i.e.</em> for abstract
types or non-free parameters), the variance must be given explicitly,
and the parameter is invariant if no variance is given.</p><p>The optional type equation <span class="c004">=</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> makes the defined type
equivalent to the type expression <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>:
one can be substituted for the other during typing.
If no type equation is given, a new type is generated: the defined type
is incompatible with any other type.</p><p>The optional type representation describes the data structure
representing the defined type, by giving the list of associated
constructors (if it is a variant type) or associated fields (if it is
a record type). If no type representation is given, nothing is
assumed on the structure of the type besides what is stated in the
optional type equation.</p><p>The type representation <span class="c004">=</span> [<span class="c004">|</span>] <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a>  { <span class="c004">|</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a> }
describes a variant type. The constructor declarations
<a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a><sub>1</sub>, …,  <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a><sub><span class="c009">n</span></sub> describe the constructors
associated to this variant type. The constructor
declaration <a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a> <span class="c004">of</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">*</span> … <span class="c004">*</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub>
declares the name <a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a> as a non-constant constructor, whose
arguments have types <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> …<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub>.
The constructor declaration <a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a>
declares the name <a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a> as a constant
constructor. Constructor names must be capitalized.</p><p>The type representation <span class="c002"><span class="c003">=</span> <span class="c003">{</span></span> <a class="syntax" href="#field-decl"><span class="c010">field-decl</span></a>  { <span class="c004">;</span> <a class="syntax" href="#field-decl"><span class="c010">field-decl</span></a> }  [<span class="c004">;</span>] <span class="c004">}</span>
describes a record type. The field declarations <a class="syntax" href="#field-decl"><span class="c010">field-decl</span></a><sub>1</sub>, …,
 <a class="syntax" href="#field-decl"><span class="c010">field-decl</span></a><sub><span class="c009">n</span></sub> describe the fields associated to this record type.
The field declaration <a class="syntax" href="#field-name"><span class="c010">field-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a> declares
<a class="syntax" href="#field-name"><span class="c010">field-name</span></a> as a field whose argument has type <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a>.
The field declaration <span class="c004">mutable</span> <a class="syntax" href="#field-name"><span class="c010">field-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a>
<a id="hevea_manual.kwd98"></a>
behaves similarly; in addition, it allows physical modification of
this field.
Immutable fields are covariant, mutable fields are non-variant.
Both mutable and immutable fields may have explicitly polymorphic
types. The polymorphism of the contents is statically checked whenever
a record value is created or modified. Extracted values may have their
types instantiated.</p><p>The two components of a type definition, the optional equation and the
optional representation, can be combined independently, giving
rise to four typical situations:</p><dl class="description"><dt class="dt-description">
<span class="c013">Abstract type: no equation, no representation.</span></dt><dd class="dd-description">  <br>
When appearing in a module signature, this definition specifies
nothing on the type constructor, besides its number of parameters:
its representation is hidden and it is assumed incompatible with any
other type.</dd><dt class="dt-description"><span class="c013">Type abbreviation: an equation, no representation.</span></dt><dd class="dd-description">  <br>
This defines the type constructor as an abbreviation for the type
expression on the right of the <span class="c004">=</span> sign.</dd><dt class="dt-description"><span class="c013">New variant type or record type: no equation, a representation.</span></dt><dd class="dd-description">  <br>
This generates a new type constructor and defines associated
constructors or fields, through which values of that type can be
directly built or inspected.</dd><dt class="dt-description"><span class="c013">Re-exported variant type or record type: an equation,
a representation.</span></dt><dd class="dd-description">  <br>
In this case, the type constructor is defined as an abbreviation for
the type expression given in the equation, but in addition the
constructors or fields given in the representation remain attached to
the defined type constructor. The type expression in the equation part
must agree with the representation: it must be of the same kind
(record or variant) and have exactly the same constructors or fields,
in the same order, with the same arguments. Moreover, the new type
constructor must have the same arity and the same type constraints as the
original type constructor.
</dd></dl><p>The type variables appearing as type parameters can optionally be
prefixed by <span class="c003">+</span> or <span class="c003">-</span> to indicate that the type constructor is
covariant or contravariant with respect to this parameter. This
variance information is used to decide subtyping relations when
checking the validity of <span class="c004">:&gt;</span> coercions
(see section <a href="#ss%3Aexpr-coercions">7.7.7</a>).</p><p>For instance, <span class="c003">type +'a t</span> declares <span class="c003">t</span> as an abstract type that is
covariant in its parameter; this means that if the type τ is a
subtype of the type σ, then τ <span class="c005"> t</span> is a subtype of σ
<span class="c005"> t</span>. Similarly, <span class="c003">type -'a t</span> declares that the abstract type <span class="c003">t</span> is
contravariant in its parameter: if τ is a subtype of σ, then
σ <span class="c005"> t</span> is a subtype of τ <span class="c005"> t</span>. If no <span class="c003">+</span> or <span class="c003">-</span> variance
annotation is given, the type constructor is assumed non-variant in the
corresponding parameter. For instance, the abstract type declaration
<span class="c003">type 'a t</span> means that τ <span class="c005"> t</span> is neither a subtype nor a
supertype of σ <span class="c005"> t</span> if τ is subtype of σ.</p><p>The variance indicated by the <span class="c003">+</span> and <span class="c003">-</span> annotations on parameters
is enforced only for abstract and private types, or when there are
type constraints.
Otherwise, for abbreviations, variant and record types without type
constraints, the variance properties of the type constructor
are inferred from its definition, and the variance annotations are
only checked for conformance with the definition.</p><p><a id="hevea_manual.kwd99"></a>
The construct  <span class="c002"><span class="c003">constraint</span> <span class="c003">'</span></span> <a class="syntax" href="#ident"><span class="c010">ident</span></a> <span class="c004">=</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  allows the
specification of
type parameters. Any actual type argument corresponding to the type
parameter <a class="syntax" href="#ident"><span class="c010">ident</span></a> has to be an instance of <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> (more precisely,
<a class="syntax" href="#ident"><span class="c010">ident</span></a> and <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> are unified). Type variables of <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> can
appear in the type equation and the type declaration.</p>
<!--TOC subsection id="ss:exndef" 7.8.2  Exception definitions-->
<h3 class="subsection" id="ss:exndef"><a class="section-anchor" href="#ss:exndef" aria-hidden="true"></a>7.8.2  Exception definitions</h3><!--SEC END --><p>
<a id="hevea_manual.kwd100"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="exception-definition"><span class="c010">exception-definition</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">exception</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">exception</span> <a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#constr"><span class="c010">constr</span></a>
</td></tr>
</table></td></tr>
</table></div><p>Exception definitions add new constructors to the built-in variant
type <code>exn</code> of exception values. The constructors are declared as
for a definition of a variant type.</p><p>The form <span class="c004">exception</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a>
generates a new exception, distinct from all other exceptions in the system.
The form <span class="c004">exception</span> <a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#constr"><span class="c010">constr</span></a>
gives an alternate name to an existing exception.

</p>
<!--TOC section id="s:classes" 7.9  Classes-->
<h2 class="section" id="s:classes"><a class="section-anchor" href="#s:classes" aria-hidden="true"></a>7.9  Classes</h2><!--SEC END --><!--NAME classes.html-->
<p>
Classes are defined using a small language, similar to the module
language.</p>
<!--TOC subsection id="ss:classes:class-types" 7.9.1  Class types-->
<h3 class="subsection" id="ss:classes:class-types"><a class="section-anchor" href="#ss:classes:class-types" aria-hidden="true"></a>7.9.1  Class types</h3><!--SEC END --><p>Class types are the class-level equivalent of type expressions: they
specify the general shape and type properties of classes.</p><p><a id="hevea_manual.kwd101"></a>
<a id="hevea_manual.kwd102"></a>
<a id="hevea_manual.kwd103"></a>
<a id="hevea_manual.kwd104"></a>
<a id="hevea_manual.kwd105"></a>
<a id="hevea_manual.kwd106"></a>
<a id="hevea_manual.kwd107"></a>
<a id="hevea_manual.kwd108"></a>
<a id="hevea_manual.kwd109"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="class-type"><span class="c010">class-type</span></a></td><td class="c015">::=</td><td class="c017">
[[<span class="c004">?</span>]<a class="syntax" href="#label-name"><span class="c010">label-name</span></a><span class="c004">:</span>]  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">-&gt;</span>  <a class="syntax" href="#class-type"><span class="c010">class-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">   <a class="syntax" href="#class-body-type"><span class="c010">class-body-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="class-body-type"><span class="c010">class-body-type</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">object</span> [<span class="c004">(</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">)</span>]  {<a class="syntax" href="#class-field-spec"><span class="c010">class-field-spec</span></a>} <span class="c004">end</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  [<span class="c004">[</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  {<span class="c004">,</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>} <span class="c004">]</span>]  <a class="syntax" href="#classtype-path"><span class="c010">classtype-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">let</span> <span class="c004">open</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">in</span>  <a class="syntax" href="#class-body-type"><span class="c010">class-body-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="class-field-spec"><span class="c010">class-field-spec</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">inherit</span> <a class="syntax" href="#class-body-type"><span class="c010">class-body-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">val</span> [<span class="c004">mutable</span>] [<span class="c004">virtual</span>] <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">val</span> <span class="c004">virtual</span> <span class="c004">mutable</span> <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">method</span> [<span class="c004">private</span>] [<span class="c004">virtual</span>] <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">method</span> <span class="c004">virtual</span> <span class="c004">private</span> <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">constraint</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
</td></tr>
</table></td></tr>
</table></div><p>
See also the following language extensions:
<a href="#s%3Aattributes">attributes</a> and
<a href="#s%3Aextension-nodes">extension nodes</a>.</p><!--TOC subsubsection id="sss:clty:simple" Simple class expressions-->
<h4 class="subsubsection" id="sss:clty:simple"><a class="section-anchor" href="#sss:clty:simple" aria-hidden="true"></a>Simple class expressions</h4><!--SEC END --><p>The expression <a class="syntax" href="#classtype-path"><span class="c010">classtype-path</span></a> is equivalent to the class type bound to
the name <a class="syntax" href="#classtype-path"><span class="c010">classtype-path</span></a>. Similarly, the expression
<span class="c004">[</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">,</span> …  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub> <span class="c004">]</span>  <a class="syntax" href="#classtype-path"><span class="c010">classtype-path</span></a> is equivalent to
the parametric class type bound to the name <a class="syntax" href="#classtype-path"><span class="c010">classtype-path</span></a>, in which
type parameters have been instantiated to respectively <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub>,
…<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub>.</p><!--TOC subsubsection id="sss:clty-fun" Class function type-->
<h4 class="subsubsection" id="sss:clty-fun"><a class="section-anchor" href="#sss:clty-fun" aria-hidden="true"></a>Class function type</h4><!--SEC END --><p>The class type expression <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">-&gt;</span>  <a class="syntax" href="#class-type"><span class="c010">class-type</span></a> is the type of
class functions (functions from values to classes) that take as
argument a value of type <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> and return as result a class of
type <a class="syntax" href="#class-type"><span class="c010">class-type</span></a>.</p><!--TOC subsubsection id="sss:clty:body" Class body type-->
<h4 class="subsubsection" id="sss:clty:body"><a class="section-anchor" href="#sss:clty:body" aria-hidden="true"></a>Class body type</h4><!--SEC END --><p>The class type expression
<span class="c004">object</span> [<span class="c004">(</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">)</span>]  {<a class="syntax" href="#class-field-spec"><span class="c010">class-field-spec</span></a>} <span class="c004">end</span>
is the type of a class body. It specifies its instance variables and
methods. In this type, <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> is matched against the self type, therefore
providing a name for the self type.</p><p>A class body will match a class body type if it provides definitions
for all the components specified in the class body type, and these
definitions meet the type requirements given in the class body type.
Furthermore, all methods either virtual or public present in the class
body must also be present in the class body type (on the other hand, some
instance variables and concrete private methods may be omitted). A
virtual method will match a concrete method, which makes it possible
to forget its implementation. An immutable instance variable will match a
mutable instance variable.</p><!--TOC subsubsection id="sss:clty-open" Local opens-->
<h4 class="subsubsection" id="sss:clty-open"><a class="section-anchor" href="#sss:clty-open" aria-hidden="true"></a>Local opens</h4><!--SEC END --><p>Local opens are supported in class types since OCaml 4.06.</p><!--TOC subsubsection id="sss:clty-inheritance" Inheritance-->
<h4 class="subsubsection" id="sss:clty-inheritance"><a class="section-anchor" href="#sss:clty-inheritance" aria-hidden="true"></a>Inheritance</h4><!--SEC END --><p><a id="hevea_manual.kwd110"></a></p><p>The inheritance construct <span class="c004">inherit</span> <a class="syntax" href="#class-body-type"><span class="c010">class-body-type</span></a> provides for inclusion of
methods and instance variables from other class types.
The instance variable and method types from <a class="syntax" href="#class-body-type"><span class="c010">class-body-type</span></a> are added
into the current class type.</p><!--TOC subsubsection id="sss:clty-variable" Instance variable specification-->
<h4 class="subsubsection" id="sss:clty-variable"><a class="section-anchor" href="#sss:clty-variable" aria-hidden="true"></a>Instance variable specification</h4><!--SEC END --><p><a id="hevea_manual.kwd111"></a>
<a id="hevea_manual.kwd112"></a></p><p>A specification of an instance variable is written
<span class="c004">val</span> [<span class="c004">mutable</span>] [<span class="c004">virtual</span>] <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>, where
<a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a>
is the name of the instance variable and <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> its expected type.
The flag <span class="c004">mutable</span> indicates whether this instance variable can be
physically modified.
The flag <span class="c004">virtual</span> indicates that this instance variable is not
initialized. It can be initialized later through inheritance.</p><p>An instance variable specification will hide any previous
specification of an instance variable of the same name.</p><!--TOC subsubsection id="sss:clty-meth" Method specification-->
<h4 class="subsubsection" id="sss:clty-meth"><a class="section-anchor" href="#sss:clty-meth" aria-hidden="true"></a>Method specification</h4><!--SEC END --><p><a id="hevea_manual.kwd113"></a>
<a id="hevea_manual.kwd114"></a></p><p>The specification of a method is written
<span class="c004">method</span> [<span class="c004">private</span>] <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a>, where
<a class="syntax" href="#method-name"><span class="c010">method-name</span></a> is the name of the method and <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a> its
expected type, possibly polymorphic. The flag <span class="c004">private</span> indicates
that the method cannot be accessed from outside the object.</p><p>The polymorphism may be left implicit in public method specifications:
any type variable which is not bound to a class parameter and does not
appear elsewhere inside the class specification will be assumed to be
universal, and made polymorphic in the resulting method type.
Writing an explicit polymorphic type will disable this behaviour.</p><p>If several specifications are present for the same method, they
must have compatible types.
Any non-private specification of a method forces it to be public.</p><!--TOC subsubsection id="sss:class-virtual-meth-spec" Virtual method specification-->
<h4 class="subsubsection" id="sss:class-virtual-meth-spec"><a class="section-anchor" href="#sss:class-virtual-meth-spec" aria-hidden="true"></a>Virtual method specification</h4><!--SEC END --><p><a id="hevea_manual.kwd115"></a>
<a id="hevea_manual.kwd116"></a></p><p>A virtual method specification is written <span class="c004">method</span> [<span class="c004">private</span>]
<span class="c004">virtual</span> <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a>, where <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> is the
name of the method and <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a> its expected type.</p><!--TOC subsubsection id="sss:class-constraints" Constraints on type parameters-->
<h4 class="subsubsection" id="sss:class-constraints"><a class="section-anchor" href="#sss:class-constraints" aria-hidden="true"></a>Constraints on type parameters</h4><!--SEC END --><p><a id="hevea_manual.kwd117"></a></p><p>The construct <span class="c004">constraint</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">=</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>2</sub> forces the two
type expressions to be equal. This is typically used to specify type
parameters: in this way, they can be bound to specific type
expressions.</p>
<!--TOC subsection id="ss:class-expr" 7.9.2  Class expressions-->
<h3 class="subsection" id="ss:class-expr"><a class="section-anchor" href="#ss:class-expr" aria-hidden="true"></a>7.9.2  Class expressions</h3><!--SEC END --><p>Class expressions are the class-level equivalent of value expressions:
they evaluate to classes, thus providing implementations for the
specifications expressed in class types.</p><p><a id="hevea_manual.kwd118"></a>
<a id="hevea_manual.kwd119"></a>
<a id="hevea_manual.kwd120"></a>
<a id="hevea_manual.kwd121"></a>
<a id="hevea_manual.kwd122"></a>
<a id="hevea_manual.kwd123"></a>
<a id="hevea_manual.kwd124"></a>
<a id="hevea_manual.kwd125"></a>
<a id="hevea_manual.kwd126"></a>
<a id="hevea_manual.kwd127"></a>
<a id="hevea_manual.kwd128"></a>
<a id="hevea_manual.kwd129"></a>
<a id="hevea_manual.kwd130"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="class-expr"><span class="c010">class-expr</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#class-path"><span class="c010">class-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">[</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  {<span class="c004">,</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>} <span class="c004">]</span>  <a class="syntax" href="#class-path"><span class="c010">class-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">(</span> <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">(</span> <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#class-type"><span class="c010">class-type</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>  {<a class="syntax" href="#argument"><span class="c010">argument</span></a>}<sup>+</sup>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">fun</span> {<a class="syntax" href="#parameter"><span class="c010">parameter</span></a>}<sup>+</sup> <span class="c004">-&gt;</span>  <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">let</span> [<span class="c004">rec</span>] <a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a>  {<span class="c004">and</span> <a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a>} <span class="c004">in</span>  <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">object</span> <a class="syntax" href="#class-body"><span class="c010">class-body</span></a> <span class="c004">end</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">let</span> <span class="c004">open</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">in</span>  <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="class-field"><span class="c010">class-field</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">inherit</span> <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>  [<span class="c004">as</span> <a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">inherit!</span> <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>  [<span class="c004">as</span> <a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">val</span> [<span class="c004">mutable</span>] <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>] <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">val!</span> [<span class="c004">mutable</span>] <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>] <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">val</span> [<span class="c004">mutable</span>] <span class="c004">virtual</span> <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">val</span> <span class="c004">virtual</span> <span class="c004">mutable</span> <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">method</span> [<span class="c004">private</span>] <a class="syntax" href="#method-name"><span class="c010">method-name</span></a>  {<a class="syntax" href="#parameter"><span class="c010">parameter</span></a>}  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>] <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">method!</span> [<span class="c004">private</span>] <a class="syntax" href="#method-name"><span class="c010">method-name</span></a>  {<a class="syntax" href="#parameter"><span class="c010">parameter</span></a>}  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>] <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">method</span> [<span class="c004">private</span>] <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">method!</span> [<span class="c004">private</span>] <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">method</span> [<span class="c004">private</span>] <span class="c004">virtual</span> <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">method</span> <span class="c004">virtual</span> <span class="c004">private</span> <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">constraint</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">initializer</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</td></tr>
</table></td></tr>
</table></div><p>
See also the following language extensions:
<a href="#s%3Alocally-abstract">locally abstract types</a>,
<a href="#s%3Aattributes">attributes</a> and
<a href="#s%3Aextension-nodes">extension nodes</a>.</p><!--TOC subsubsection id="sss:class-simple" Simple class expressions-->
<h4 class="subsubsection" id="sss:class-simple"><a class="section-anchor" href="#sss:class-simple" aria-hidden="true"></a>Simple class expressions</h4><!--SEC END --><p>The expression <a class="syntax" href="#class-path"><span class="c010">class-path</span></a> evaluates to the class bound to the name
<a class="syntax" href="#class-path"><span class="c010">class-path</span></a>. Similarly, the expression
<span class="c004">[</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">,</span> …  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub> <span class="c004">]</span>  <a class="syntax" href="#class-path"><span class="c010">class-path</span></a>
evaluates to the parametric class bound to the name <a class="syntax" href="#class-path"><span class="c010">class-path</span></a>,
in which type parameters have been instantiated respectively to
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub>, …<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub><span class="c009">n</span></sub>.</p><p>The expression <span class="c004">(</span> <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a> <span class="c004">)</span> evaluates to the same module as
<a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>.</p><p>The expression <span class="c004">(</span> <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#class-type"><span class="c010">class-type</span></a> <span class="c004">)</span> checks that
<a class="syntax" href="#class-type"><span class="c010">class-type</span></a> matches the type of <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a> (that is, that the
implementation <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a> meets the type specification
<a class="syntax" href="#class-type"><span class="c010">class-type</span></a>). The whole expression evaluates to the same class as
<a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>, except that all components not specified in
<a class="syntax" href="#class-type"><span class="c010">class-type</span></a> are hidden and can no longer be accessed.</p><!--TOC subsubsection id="sss:class-app" Class application-->
<h4 class="subsubsection" id="sss:class-app"><a class="section-anchor" href="#sss:class-app" aria-hidden="true"></a>Class application</h4><!--SEC END --><p>Class application is denoted by juxtaposition of (possibly labeled)
expressions. It denotes the class whose constructor is the first
expression applied to the given arguments. The arguments are
evaluated as for expression application, but the constructor itself will
only be evaluated when objects are created. In particular, side-effects
caused by the application of the constructor will only occur at object
creation time.</p><!--TOC subsubsection id="sss:class-fun" Class function-->
<h4 class="subsubsection" id="sss:class-fun"><a class="section-anchor" href="#sss:class-fun" aria-hidden="true"></a>Class function</h4><!--SEC END --><p>The expression <span class="c004">fun</span> [[<span class="c004">?</span>]<a class="syntax" href="#label-name"><span class="c010">label-name</span></a><span class="c004">:</span>] <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">-&gt;</span>  <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a> evaluates
to a function from values to classes.
When this function is applied to a value <span class="c009">v</span>, this value is
matched against the pattern <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> and the result is the result of
the evaluation of <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a> in the extended environment.</p><p>Conversion from functions with default values to functions with
patterns only works identically for class functions as for normal
functions.</p><p>The expression
</p><div class="center">
<span class="c004">fun</span> <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub>1</sub> …  <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub><span class="c009">n</span></sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>
</div><p>
is a short form for
</p><div class="center">
<span class="c004">fun</span> <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub>1</sub> <span class="c004">-&gt;</span> … <span class="c004">fun</span>  <a class="syntax" href="#parameter"><span class="c010">parameter</span></a><sub><span class="c009">n</span></sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><!--TOC subsubsection id="sss:class-localdefs" Local definitions-->
<h4 class="subsubsection" id="sss:class-localdefs"><a class="section-anchor" href="#sss:class-localdefs" aria-hidden="true"></a>Local definitions</h4><!--SEC END --><p>The <span class="c003">let</span> and <span class="c003">let rec</span> constructs bind value names locally,
as for the core language expressions.</p><p>If a local definition occurs at the very beginning of a class
definition, it will be evaluated when the class is created (just as if
the definition was outside of the class).
Otherwise, it will be evaluated when the object constructor is called.</p><!--TOC subsubsection id="sss:class-opens" Local opens-->
<h4 class="subsubsection" id="sss:class-opens"><a class="section-anchor" href="#sss:class-opens" aria-hidden="true"></a>Local opens</h4><!--SEC END --><p>Local opens are supported in class expressions since OCaml 4.06.</p><!--TOC subsubsection id="sss:class-body" Class body-->
<h4 class="subsubsection" id="sss:class-body"><a class="section-anchor" href="#sss:class-body" aria-hidden="true"></a>Class body</h4><!--SEC END --><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="class-body"><span class="c010">class-body</span></a></td><td class="c015">::=</td><td class="c017">  [<span class="c004">(</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>] <span class="c004">)</span>]  { <a class="syntax" href="#class-field"><span class="c010">class-field</span></a> }
</td></tr>
</table></td></tr>
</table></div><p>
The expression
<span class="c004">object</span> <a class="syntax" href="#class-body"><span class="c010">class-body</span></a> <span class="c004">end</span> denotes
a class body. This is the prototype for an object : it lists the
instance variables and methods of an object of this class.</p><p>A class body is a class value: it is not evaluated at once. Rather,
its components are evaluated each time an object is created.</p><p>In a class body, the pattern <span class="c004">(</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>  [<span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>] <span class="c004">)</span> is
matched against self, therefore providing a binding for self and self
type. Self can only be used in method and initializers.</p><p>Self type cannot be a closed object type, so that the class remains
extensible.</p><p>Since OCaml 4.01, it is an error if the same method or instance
variable name is defined several times in the same class body.</p><!--TOC subsubsection id="sss:class-inheritance" Inheritance-->
<h4 class="subsubsection" id="sss:class-inheritance"><a class="section-anchor" href="#sss:class-inheritance" aria-hidden="true"></a>Inheritance</h4><!--SEC END --><p><a id="hevea_manual.kwd131"></a></p><p>The inheritance construct <span class="c004">inherit</span> <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a> allows reusing
methods and instance variables from other classes. The class
expression <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a> must evaluate to a class body. The instance
variables, methods and initializers from this class body are added
into the current class. The addition of a method will override any
previously defined method of the same name.</p><p><a id="hevea_manual.kwd132"></a>
An ancestor can be bound by appending <span class="c004">as</span> <a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>
to the inheritance construct. <a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a> is not a true
variable and can only be used to select a method, i.e. in an expression
<a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a> <span class="c004">#</span>  <a class="syntax" href="#method-name"><span class="c010">method-name</span></a>. This gives access to the
method <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> as it was defined in the parent class even if it is
redefined in the current class.
The scope of this ancestor binding is limited to the current class.
The ancestor method may be called from a subclass but only indirectly.</p><!--TOC subsubsection id="sss:class-variables" Instance variable definition-->
<h4 class="subsubsection" id="sss:class-variables"><a class="section-anchor" href="#sss:class-variables" aria-hidden="true"></a>Instance variable definition</h4><!--SEC END --><p><a id="hevea_manual.kwd133"></a>
<a id="hevea_manual.kwd134"></a></p><p>The definition <span class="c004">val</span> [<span class="c004">mutable</span>] <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> adds an
instance variable <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> whose initial value is the value of
expression <a class="syntax" href="#expr"><span class="c010">expr</span></a>.
The flag <span class="c004">mutable</span> allows physical modification of this variable by
methods.</p><p>An instance variable can only be used in the methods and
initializers that follow its definition.</p><p>Since version 3.10, redefinitions of a visible instance variable with
the same name do not create a new variable, but are merged, using the
last value for initialization. They must have identical types and
mutability.
However, if an instance variable is hidden by
omitting it from an interface, it will be kept distinct from
other instance variables with the same name.</p><!--TOC subsubsection id="sss:class-virtual-variable" Virtual instance variable definition-->
<h4 class="subsubsection" id="sss:class-virtual-variable"><a class="section-anchor" href="#sss:class-virtual-variable" aria-hidden="true"></a>Virtual instance variable definition</h4><!--SEC END --><p><a id="hevea_manual.kwd135"></a>
<a id="hevea_manual.kwd136"></a></p><p>A variable specification is written <span class="c004">val</span> [<span class="c004">mutable</span>] <span class="c004">virtual</span>
<a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>. It specifies whether the variable is
modifiable, and gives its type.</p><p>Virtual instance variables were added in version 3.10.</p><!--TOC subsubsection id="sss:class-method" Method definition-->
<h4 class="subsubsection" id="sss:class-method"><a class="section-anchor" href="#sss:class-method" aria-hidden="true"></a>Method definition</h4><!--SEC END --><p><a id="hevea_manual.kwd137"></a>
<a id="hevea_manual.kwd138"></a></p><p>A method definition is written <span class="c004">method</span> <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>. The
definition of a method overrides any previous definition of this
method. The method will be public (that is, not private) if any of
the definition states so.</p><p>A private method, <span class="c002"><span class="c003">method</span> <span class="c003">private</span></span> <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>, is a
method that can only be invoked on self (from other methods of the
same object, defined in this class or one of its subclasses). This
invocation is performed using the expression
<a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">#</span>  <a class="syntax" href="#method-name"><span class="c010">method-name</span></a>, where <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> is directly bound to
self at the beginning of the class definition. Private methods do
not appear in object types. A method may have both public and private
definitions, but as soon as there is a public one, all subsequent
definitions will be made public.</p><p>Methods may have an explicitly polymorphic type, allowing them to be
used polymorphically in programs (even for the same object). The
explicit declaration may be done in one of three ways: (1) by giving an
explicit polymorphic type in the method definition, immediately after
the method name, <em>i.e.</em>
<span class="c004">method</span> [<span class="c004">private</span>] <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span>  {<span class="c004">'</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a>}<sup>+</sup> <span class="c004">.</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>
 <a class="syntax" href="#expr"><span class="c010">expr</span></a>; (2) by a forward declaration of the explicit polymorphic type
through a virtual method definition; (3) by importing such a
declaration through inheritance and/or constraining the type of <em>self</em>.</p><p>Some special expressions are available in method bodies for
manipulating instance variables and duplicating self:
</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c015">::=</td><td class="c017">
…
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">&lt;-</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">{&lt;</span> [ <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>  { <span class="c004">;</span> <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> }  [<span class="c004">;</span>] ] <span class="c004">&gt;}</span>
</td></tr>
</table></td></tr>
</table></div><p>The expression <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> <span class="c004">&lt;-</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> modifies in-place the current
object by replacing the value associated to <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> by the
value of <a class="syntax" href="#expr"><span class="c010">expr</span></a>. Of course, this instance variable must have been
declared mutable.</p><p>The expression
<span class="c004">{&lt;</span> <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a><sub>1</sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a><sub><span class="c009">n</span></sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> <span class="c004">&gt;}</span>
evaluates to a copy of the current object in which the values of
instance variables <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a><sub>1</sub>, …,  <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a><sub><span class="c009">n</span></sub> have
been replaced by the values of the corresponding expressions <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>,
…,  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub>.</p><!--TOC subsubsection id="sss:class-virtual-meth" Virtual method definition-->
<h4 class="subsubsection" id="sss:class-virtual-meth"><a class="section-anchor" href="#sss:class-virtual-meth" aria-hidden="true"></a>Virtual method definition</h4><!--SEC END --><p><a id="hevea_manual.kwd139"></a>
<a id="hevea_manual.kwd140"></a></p><p>A method specification is written <span class="c004">method</span> [<span class="c004">private</span>] <span class="c004">virtual</span>
<a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a>. It specifies whether the method is
public or private, and gives its type. If the method is intended to be
polymorphic, the type must be explicitly polymorphic.</p><!--TOC subsubsection id="sss:class-explicit-overriding" Explicit overriding-->
<h4 class="subsubsection" id="sss:class-explicit-overriding"><a class="section-anchor" href="#sss:class-explicit-overriding" aria-hidden="true"></a>Explicit overriding</h4><!--SEC END --><p>Since Ocaml 3.12, the keywords <span class="c004">inherit!</span>, <span class="c004">val!</span> and <span class="c004">method!</span>
have the same semantics as <span class="c004">inherit</span>, <span class="c004">val</span> and <span class="c004">method</span>, but
they additionally require the definition they introduce to be
overriding. Namely, <span class="c004">method!</span> requires <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> to be already
defined in this class, <span class="c004">val!</span> requires <a class="syntax" href="#inst-var-name"><span class="c010">inst-var-name</span></a> to be already
defined in this class, and <span class="c004">inherit!</span> requires <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a> to
override some definitions. If no such overriding occurs, an error is
signaled.</p><p>As a side-effect, these 3 keywords avoid the warnings 7
(method override) and 13 (instance variable override).
Note that warning 7 is disabled by default.</p><!--TOC subsubsection id="sss:class-type-constraints" Constraints on type parameters-->
<h4 class="subsubsection" id="sss:class-type-constraints"><a class="section-anchor" href="#sss:class-type-constraints" aria-hidden="true"></a>Constraints on type parameters</h4><!--SEC END --><p><a id="hevea_manual.kwd141"></a>
The construct <span class="c004">constraint</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">=</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>2</sub> forces the two
type expressions to be equals. This is typically used to specify type
parameters: in that way they can be bound to specific type
expressions.</p><!--TOC subsubsection id="sss:class-initializers" Initializers-->
<h4 class="subsubsection" id="sss:class-initializers"><a class="section-anchor" href="#sss:class-initializers" aria-hidden="true"></a>Initializers</h4><!--SEC END --><p><a id="hevea_manual.kwd142"></a></p><p>A class initializer <span class="c004">initializer</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> specifies an expression that
will be evaluated whenever an object is created from the class, once
all its instance variables have been initialized.</p>
<!--TOC subsection id="ss:class-def" 7.9.3  Class definitions-->
<h3 class="subsection" id="ss:class-def"><a class="section-anchor" href="#ss:class-def" aria-hidden="true"></a>7.9.3  Class definitions</h3><!--SEC END --><p>
<a id="s:classdef"></a></p><p><a id="hevea_manual.kwd143"></a>
<a id="hevea_manual.kwd144"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="class-definition"><span class="c010">class-definition</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">class</span> <a class="syntax" href="#class-binding"><span class="c010">class-binding</span></a>  { <span class="c004">and</span> <a class="syntax" href="#class-binding"><span class="c010">class-binding</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="class-binding"><span class="c010">class-binding</span></a></td><td class="c015">::=</td><td class="c017">
[<span class="c004">virtual</span>] [<span class="c004">[</span> <a class="syntax" href="#type-parameters"><span class="c010">type-parameters</span></a> <span class="c004">]</span>]  <a class="syntax" href="#class-name"><span class="c010">class-name</span></a>
 {<a class="syntax" href="#parameter"><span class="c010">parameter</span></a>}  [<span class="c004">:</span> <a class="syntax" href="#class-type"><span class="c010">class-type</span></a>]  <span class="c004">=</span>  <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="type-parameters"><span class="c010">type-parameters</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">'</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a>  { <span class="c004">,</span> <span class="c004">'</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a> }
</td></tr>
</table></td></tr>
</table></div><p>A class definition <span class="c004">class</span> <a class="syntax" href="#class-binding"><span class="c010">class-binding</span></a>  { <span class="c004">and</span> <a class="syntax" href="#class-binding"><span class="c010">class-binding</span></a> } is
recursive. Each <a class="syntax" href="#class-binding"><span class="c010">class-binding</span></a> defines a <a class="syntax" href="#class-name"><span class="c010">class-name</span></a> that can be
used in the whole expression except for inheritance. It can also be
used for inheritance, but only in the definitions that follow its own.</p><p>A class binding binds the class name <a class="syntax" href="#class-name"><span class="c010">class-name</span></a> to the value of
expression <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>. It also binds the class type <a class="syntax" href="#class-name"><span class="c010">class-name</span></a> to
the type of the class, and defines two type abbreviations :
<a class="syntax" href="#class-name"><span class="c010">class-name</span></a> and <span class="c004">#</span> <a class="syntax" href="#class-name"><span class="c010">class-name</span></a>. The first one is the type of
objects of this class, while the second is more general as it unifies
with the type of any object belonging to a subclass (see
section <a href="#sss%3Atypexpr-sharp-types">7.4</a>).</p><!--TOC subsubsection id="sss:class-virtual" Virtual class-->
<h4 class="subsubsection" id="sss:class-virtual"><a class="section-anchor" href="#sss:class-virtual" aria-hidden="true"></a>Virtual class</h4><!--SEC END --><p>A class must be flagged virtual if one of its methods is virtual (that
is, appears in the class type, but is not actually defined).
Objects cannot be created from a virtual class.</p><!--TOC subsubsection id="sss:class-type-params" Type parameters-->
<h4 class="subsubsection" id="sss:class-type-params"><a class="section-anchor" href="#sss:class-type-params" aria-hidden="true"></a>Type parameters</h4><!--SEC END --><p>The class type parameters correspond to the ones of the class type and
of the two type abbreviations defined by the class binding. They must
be bound to actual types in the class definition using type
constraints. So that the abbreviations are well-formed, type
variables of the inferred type of the class must either be type
parameters or be bound in the constraint clause.</p>
<!--TOC subsection id="ss:class-spec" 7.9.4  Class specifications-->
<h3 class="subsection" id="ss:class-spec"><a class="section-anchor" href="#ss:class-spec" aria-hidden="true"></a>7.9.4  Class specifications</h3><!--SEC END --><p><a id="hevea_manual.kwd145"></a>
<a id="hevea_manual.kwd146"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="class-specification"><span class="c010">class-specification</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">class</span> <a class="syntax" href="#class-spec"><span class="c010">class-spec</span></a>  { <span class="c004">and</span> <a class="syntax" href="#class-spec"><span class="c010">class-spec</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="class-spec"><span class="c010">class-spec</span></a></td><td class="c015">::=</td><td class="c017">
[<span class="c004">virtual</span>] [<span class="c004">[</span> <a class="syntax" href="#type-parameters"><span class="c010">type-parameters</span></a> <span class="c004">]</span>]  <a class="syntax" href="#class-name"><span class="c010">class-name</span></a> <span class="c004">:</span>
 <a class="syntax" href="#class-type"><span class="c010">class-type</span></a>
</td></tr>
</table></td></tr>
</table></div><p>This is the counterpart in signatures of class definitions.
A class specification matches a class definition if they have the same
type parameters and their types match.</p>
<!--TOC subsection id="ss:classtype" 7.9.5  Class type definitions-->
<h3 class="subsection" id="ss:classtype"><a class="section-anchor" href="#ss:classtype" aria-hidden="true"></a>7.9.5  Class type definitions</h3><!--SEC END --><p><a id="hevea_manual.kwd147"></a>
<a id="hevea_manual.kwd148"></a>
<a id="hevea_manual.kwd149"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="classtype-definition"><span class="c010">classtype-definition</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">class</span> <span class="c004">type</span> <a class="syntax" href="#classtype-def"><span class="c010">classtype-def</span></a>
 { <span class="c004">and</span> <a class="syntax" href="#classtype-def"><span class="c010">classtype-def</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="classtype-def"><span class="c010">classtype-def</span></a></td><td class="c015">::=</td><td class="c017">
[<span class="c004">virtual</span>] [<span class="c004">[</span> <a class="syntax" href="#type-parameters"><span class="c010">type-parameters</span></a> <span class="c004">]</span>]  <a class="syntax" href="#class-name"><span class="c010">class-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#class-body-type"><span class="c010">class-body-type</span></a>
</td></tr>
</table></td></tr>
</table></div><p>A class type definition <span class="c004">class</span> <a class="syntax" href="#class-name"><span class="c010">class-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#class-body-type"><span class="c010">class-body-type</span></a>
defines an abbreviation <a class="syntax" href="#class-name"><span class="c010">class-name</span></a> for the class body type
<a class="syntax" href="#class-body-type"><span class="c010">class-body-type</span></a>. As for class definitions, two type abbreviations
<a class="syntax" href="#class-name"><span class="c010">class-name</span></a> and <span class="c004">#</span> <a class="syntax" href="#class-name"><span class="c010">class-name</span></a> are also defined. The definition can
be parameterized by some type parameters. If any method in the class
type body is virtual, the definition must be flagged <span class="c004">virtual</span>.</p><p>Two class type definitions match if they have the same type parameters
and they expand to matching types.

</p>
<!--TOC section id="s:modtypes" 7.10  Module types (module specifications)-->
<h2 class="section" id="s:modtypes"><a class="section-anchor" href="#s:modtypes" aria-hidden="true"></a>7.10  Module types (module specifications)</h2><!--SEC END --><!--NAME modtypes.html-->
<p>Module types are the module-level equivalent of type expressions: they
specify the general shape and type properties of modules.</p><p><a id="hevea_manual.kwd150"></a>
<a id="hevea_manual.kwd151"></a>
<a id="hevea_manual.kwd152"></a>
<a id="hevea_manual.kwd153"></a>
<a id="hevea_manual.kwd154"></a>
<a id="hevea_manual.kwd155"></a>
<a id="hevea_manual.kwd156"></a>
<a id="hevea_manual.kwd157"></a>
<a id="hevea_manual.kwd158"></a>
<a id="hevea_manual.kwd159"></a>
<a id="hevea_manual.kwd160"></a>
<a id="hevea_manual.kwd161"></a>
<a id="hevea_manual.kwd162"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="module-type"><span class="c010">module-type</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#modtype-path"><span class="c010">modtype-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">sig</span> { <a class="syntax" href="#specification"><span class="c010">specification</span></a>  [<span class="c004">;;</span>] } <span class="c004">end</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">functor</span> <span class="c004">(</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span> <span class="c004">-&gt;</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">-&gt;</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">with</span>  <a class="syntax" href="#mod-constraint"><span class="c010">mod-constraint</span></a>  { <span class="c004">and</span> <a class="syntax" href="#mod-constraint"><span class="c010">mod-constraint</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="mod-constraint"><span class="c010">mod-constraint</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">type</span> [<a class="syntax" href="#type-params"><span class="c010">type-params</span></a>]  <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>  <a class="syntax" href="#type-equation"><span class="c010">type-equation</span></a>  { <a class="syntax" href="#type-constraint"><span class="c010">type-constraint</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">=</span>  <a class="syntax" href="#extended-module-path"><span class="c010">extended-module-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="specification"><span class="c010">specification</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">val</span> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">external</span> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#external-declaration"><span class="c010">external-declaration</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#type-definition"><span class="c010">type-definition</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">exception</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#class-specification"><span class="c010">class-specification</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#classtype-definition"><span class="c010">classtype-definition</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a>  { <span class="c004">(</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span> }
<span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <span class="c004">type</span> <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <span class="c004">type</span> <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">open</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">include</span> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
</td></tr>
</table></td></tr>
</table></div><p>
See also the following language extensions:
<a href="#s%3Amodule-type-of">recovering the type of a module</a>,
<a href="#s%3Asignature-substitution">substitution inside a signature</a>,
<a href="#s%3Amodule-alias">type-level module aliases</a>,
<a href="#s%3Aattributes">attributes</a>,
<a href="#s%3Aextension-nodes">extension nodes</a> and
<a href="#s%3Agenerative-functors">generative functors</a>.</p>
<!--TOC subsection id="ss:mty-simple" 7.10.1  Simple module types-->
<h3 class="subsection" id="ss:mty-simple"><a class="section-anchor" href="#ss:mty-simple" aria-hidden="true"></a>7.10.1  Simple module types</h3><!--SEC END --><p>The expression <a class="syntax" href="#modtype-path"><span class="c010">modtype-path</span></a> is equivalent to the module type bound
to the name <a class="syntax" href="#modtype-path"><span class="c010">modtype-path</span></a>.
The expression <span class="c004">(</span> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span> denotes the same type as
<a class="syntax" href="#module-type"><span class="c010">module-type</span></a>.</p>
<!--TOC subsection id="ss:mty-signatures" 7.10.2  Signatures-->
<h3 class="subsection" id="ss:mty-signatures"><a class="section-anchor" href="#ss:mty-signatures" aria-hidden="true"></a>7.10.2  Signatures</h3><!--SEC END --><p><a id="hevea_manual.kwd163"></a>
<a id="hevea_manual.kwd164"></a></p><p>Signatures are type specifications for structures. Signatures
<span class="c004">sig</span> … <span class="c004">end</span> are collections of type specifications for value
names, type names, exceptions, module names and module type names. A
structure will match a signature if the structure provides definitions
(implementations) for all the names specified in the signature (and
possibly more), and these definitions meet the type requirements given
in the signature.</p><p>An optional <span class="c004">;;</span> is allowed after each specification in a
signature. It serves as a syntactic separator with no semantic
meaning.</p><!--TOC subsubsection id="sss:mty-values" Value specifications-->
<h4 class="subsubsection" id="sss:mty-values"><a class="section-anchor" href="#sss:mty-values" aria-hidden="true"></a>Value specifications</h4><!--SEC END --><p><a id="hevea_manual.kwd165"></a></p><p>A specification of a value component in a signature is written
<span class="c004">val</span> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>, where <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> is the name of the
value and <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> its expected type.</p><p><a id="hevea_manual.kwd166"></a></p><p>The form <span class="c004">external</span> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#external-declaration"><span class="c010">external-declaration</span></a>
is similar, except that it requires in addition the name to be
implemented as the external function specified in <a class="syntax" href="#external-declaration"><span class="c010">external-declaration</span></a>
(see chapter <a href="#c%3Aintf-c">20</a>).</p><!--TOC subsubsection id="sss:mty-type" Type specifications-->
<h4 class="subsubsection" id="sss:mty-type"><a class="section-anchor" href="#sss:mty-type" aria-hidden="true"></a>Type specifications</h4><!--SEC END --><p><a id="hevea_manual.kwd167"></a></p><p>A specification of one or several type components in a signature is
written <span class="c004">type</span> <a class="syntax" href="#typedef"><span class="c010">typedef</span></a>  { <span class="c004">and</span> <a class="syntax" href="#typedef"><span class="c010">typedef</span></a> } and consists of a sequence
of mutually recursive definitions of type names.</p><p>Each type definition in the signature specifies an optional type
equation <span class="c004">=</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> and an optional type representation
<span class="c004">=</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a> … or <span class="c002"><span class="c003">=</span> <span class="c003">{</span></span> <a class="syntax" href="#field-decl"><span class="c010">field-decl</span></a> … <span class="c004">}</span>.
The implementation of the type name in a matching structure must
be compatible with the type expression specified in the equation (if
given), and have the specified representation (if given). Conversely,
users of that signature will be able to rely on the type equation
or type representation, if given. More precisely, we have the
following four situations:</p><dl class="description"><dt class="dt-description">
<span class="c013">Abstract type: no equation, no representation.</span></dt><dd class="dd-description">   <br>
Names that are defined as abstract types in a signature can be
implemented in a matching structure by any kind of type definition
(provided it has the same number of type parameters). The exact
implementation of the type will be hidden to the users of the
structure. In particular, if the type is implemented as a variant type
or record type, the associated constructors and fields will not be
accessible to the users; if the type is implemented as an
abbreviation, the type equality between the type name and the
right-hand side of the abbreviation will be hidden from the users of the
structure. Users of the structure consider that type as incompatible
with any other type: a fresh type has been generated.</dd><dt class="dt-description"><span class="c013">Type abbreviation: an equation </span><span class="c004">=</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><span class="c013">, no representation.</span></dt><dd class="dd-description">   <br>
The type name must be implemented by a type compatible with <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>.
All users of the structure know that the type name is
compatible with <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>.</dd><dt class="dt-description"><span class="c013">New variant type or record type: no equation, a representation.</span></dt><dd class="dd-description">   <br>
The type name must be implemented by a variant type or record type
with exactly the constructors or fields specified. All users of the
structure have access to the constructors or fields, and can use them
to create or inspect values of that type. However, users of the
structure consider that type as incompatible with any other type: a
fresh type has been generated.</dd><dt class="dt-description"><span class="c013">Re-exported variant type or record type: an equation,
a representation.</span></dt><dd class="dd-description">   <br>
This case combines the previous two: the representation of the type is
made visible to all users, and no fresh type is generated.
</dd></dl><!--TOC subsubsection id="sss:mty-exn" Exception specification-->
<h4 class="subsubsection" id="sss:mty-exn"><a class="section-anchor" href="#sss:mty-exn" aria-hidden="true"></a>Exception specification</h4><!--SEC END --><p><a id="hevea_manual.kwd168"></a></p><p>The specification <span class="c004">exception</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a> in a signature requires the
matching structure to provide an exception with the name and arguments
specified in the definition, and makes the exception available to all
users of the structure.</p><!--TOC subsubsection id="sss:mty-class" Class specifications-->
<h4 class="subsubsection" id="sss:mty-class"><a class="section-anchor" href="#sss:mty-class" aria-hidden="true"></a>Class specifications</h4><!--SEC END --><p><a id="hevea_manual.kwd169"></a></p><p>A specification of one or several classes in a signature is written
<span class="c004">class</span> <a class="syntax" href="#class-spec"><span class="c010">class-spec</span></a>  { <span class="c004">and</span> <a class="syntax" href="#class-spec"><span class="c010">class-spec</span></a> } and consists of a sequence
of mutually recursive definitions of class names.</p><p>Class specifications are described more precisely in
section <a href="#ss%3Aclass-spec">7.9.4</a>.</p><!--TOC subsubsection id="sss:mty-classtype" Class type specifications-->
<h4 class="subsubsection" id="sss:mty-classtype"><a class="section-anchor" href="#sss:mty-classtype" aria-hidden="true"></a>Class type specifications</h4><!--SEC END --><p><a id="hevea_manual.kwd170"></a>
<a id="hevea_manual.kwd171"></a></p><p>A specification of one or several classe types in a signature is
written <span class="c002"><span class="c003">class</span> <span class="c003">type</span></span> <a class="syntax" href="#classtype-def"><span class="c010">classtype-def</span></a> { <span class="c004">and</span> <a class="syntax" href="#classtype-def"><span class="c010">classtype-def</span></a> } and
consists of a sequence of mutually recursive definitions of class type
names. Class type specifications are described more precisely in
section <a href="#ss%3Aclasstype">7.9.5</a>.</p><!--TOC subsubsection id="sss:mty-module" Module specifications-->
<h4 class="subsubsection" id="sss:mty-module"><a class="section-anchor" href="#sss:mty-module" aria-hidden="true"></a>Module specifications</h4><!--SEC END --><p><a id="hevea_manual.kwd172"></a></p><p>A specification of a module component in a signature is written
<span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>, where <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> is the
name of the module component and <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> its expected type.
Modules can be nested arbitrarily; in particular, functors can appear
as components of structures and functor types as components of
signatures.</p><p>For specifying a module component that is a functor, one may write
</p><div class="center">
<span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">(</span>  <span class="c010">name</span><sub>1</sub> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>1</sub> <span class="c004">)</span>
… <span class="c004">(</span>  <span class="c010">name</span><sub><span class="c009">n</span></sub> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub><span class="c009">n</span></sub> <span class="c002"><span class="c003">)</span>
<span class="c003">:</span></span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
</div><p>
instead of
</p><div class="center">
<span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c002"><span class="c003">:</span>
<span class="c003">functor</span> <span class="c003">(</span></span>  <span class="c010">name</span><sub>1</sub> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>1</sub> <span class="c002"><span class="c003">)</span> <span class="c003">-&gt;</span></span> …
<span class="c004">-&gt;</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
</div><!--TOC subsubsection id="sss:mty-mty" Module type specifications-->
<h4 class="subsubsection" id="sss:mty-mty"><a class="section-anchor" href="#sss:mty-mty" aria-hidden="true"></a>Module type specifications</h4><!--SEC END --><p><a id="hevea_manual.kwd173"></a>
<a id="hevea_manual.kwd174"></a></p><p>A module type component of a signature can be specified either as a
manifest module type or as an abstract module type.</p><p>An abstract module type specification
<span class="c002"><span class="c003">module</span> <span class="c003">type</span></span> <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a> allows the name <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a> to be
implemented by any module type in a matching signature, but hides the
implementation of the module type to all users of the signature.</p><p>A manifest module type specification
<span class="c002"><span class="c003">module</span> <span class="c003">type</span></span> <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
requires the name <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a> to be implemented by the module type
<a class="syntax" href="#module-type"><span class="c010">module-type</span></a> in a matching signature, but makes the equality between
<a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a> and <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> apparent to all users of the signature.</p>
<!--TOC subsubsection id="sss:mty-open" Opening a module path-->
<h4 class="subsubsection" id="sss:mty-open"><a class="section-anchor" href="#sss:mty-open" aria-hidden="true"></a>Opening a module path</h4><!--SEC END --><p><a id="hevea_manual.kwd175"></a></p><p>The expression <span class="c004">open</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> in a signature does not specify
any components. It simply affects the parsing of the following items
of the signature, allowing components of the module denoted by
<a class="syntax" href="#module-path"><span class="c010">module-path</span></a> to be referred to by their simple names <span class="c010">name</span> instead of
path accesses <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span>  <span class="c010">name</span>. The scope of the <span class="c004">open</span>
stops at the end of the signature expression.</p>
<!--TOC subsubsection id="sss:mty-include" Including a signature-->
<h4 class="subsubsection" id="sss:mty-include"><a class="section-anchor" href="#sss:mty-include" aria-hidden="true"></a>Including a signature</h4><!--SEC END --><p><a id="hevea_manual.kwd176"></a></p><p>The expression <span class="c004">include</span> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> in a signature performs textual
inclusion of the components of the signature denoted by <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>.
It behaves as if the components of the included signature were copied
at the location of the <span class="c004">include</span>. The <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> argument must
refer to a module type that is a signature, not a functor type.</p>
<!--TOC subsection id="ss:mty-functors" 7.10.3  Functor types-->
<h3 class="subsection" id="ss:mty-functors"><a class="section-anchor" href="#ss:mty-functors" aria-hidden="true"></a>7.10.3  Functor types</h3><!--SEC END --><p><a id="hevea_manual.kwd177"></a></p><p>The module type expression
<span class="c002"><span class="c003">functor</span> <span class="c003">(</span></span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>1</sub> <span class="c002"><span class="c003">)</span> <span class="c003">-&gt;</span></span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>2</sub>
is the type of functors (functions from modules to modules) that take
as argument a module of type <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>1</sub> and return as result a
module of type <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>2</sub>. The module type <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>2</sub> can
use the name <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> to refer to type components of the actual
argument of the functor. If the type <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>2</sub> does not
depend on type components of <a class="syntax" href="#module-name"><span class="c010">module-name</span></a>, the module type expression
can be simplified with the alternative short syntax
 <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>1</sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>2</sub> .
No restrictions are placed on the type of the functor argument; in
particular, a functor may take another functor as argument
(“higher-order” functor).</p>
<!--TOC subsection id="ss:mty-with" 7.10.4  The <span class="c003">with</span> operator-->
<h3 class="subsection" id="ss:mty-with"><a class="section-anchor" href="#ss:mty-with" aria-hidden="true"></a>7.10.4  The <span class="c003">with</span> operator</h3><!--SEC END --><p><a id="hevea_manual.kwd178"></a></p><p>Assuming <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> denotes a signature, the expression
<a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">with</span>  <a class="syntax" href="#mod-constraint"><span class="c010">mod-constraint</span></a> { <span class="c004">and</span> <a class="syntax" href="#mod-constraint"><span class="c010">mod-constraint</span></a> } denotes
the same signature where type equations have been added to some of the
type specifications, as described by the constraints following the
<span class="c003">with</span> keyword. The constraint <span class="c004">type</span> [<a class="syntax" href="#type-parameters"><span class="c010">type-parameters</span></a>]  <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>
<span class="c004">=</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> adds the type equation <span class="c004">=</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> to the specification
of the type component named <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a> of the constrained signature.
The constraint <span class="c004">module</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">=</span>  <a class="syntax" href="#extended-module-path"><span class="c010">extended-module-path</span></a> adds
type equations to all type components of the sub-structure denoted by
<a class="syntax" href="#module-path"><span class="c010">module-path</span></a>, making them equivalent to the corresponding type
components of the structure denoted by <a class="syntax" href="#extended-module-path"><span class="c010">extended-module-path</span></a>.</p><p>For instance, if the module type name <span class="c003">S</span> is bound to the signature
</p><pre>        sig type t module M: (sig type u end) end
</pre><p>then <span class="c003">S with type t=int</span> denotes the signature
</p><pre>        sig type t=int module M: (sig type u end) end
</pre><p>and <span class="c003">S with module M = N</span> denotes the signature
</p><pre>        sig type t module M: (sig type u=N.u end) end
</pre><p>A functor taking two arguments of type <span class="c003">S</span> that share their <span class="c003">t</span> component
is written
</p><pre>        functor (A: S) (B: S with type t = A.t) ...
</pre><p>
Constraints are added left to right. After each constraint has been
applied, the resulting signature must be a subtype of the signature
before the constraint was applied. Thus, the <span class="c004">with</span> operator can
only add information on the type components of a signature, but never
remove information.

</p>
<!--TOC section id="s:module-expr" 7.11  Module expressions (module implementations)-->
<h2 class="section" id="s:module-expr"><a class="section-anchor" href="#s:module-expr" aria-hidden="true"></a>7.11  Module expressions (module implementations)</h2><!--SEC END --><!--NAME modules.html-->
<p>Module expressions are the module-level equivalent of value
expressions: they evaluate to modules, thus providing implementations
for the specifications expressed in module types.</p><p><a id="hevea_manual.kwd179"></a>
<a id="hevea_manual.kwd180"></a>
<a id="hevea_manual.kwd181"></a>
<a id="hevea_manual.kwd182"></a>
<a id="hevea_manual.kwd183"></a>
<a id="hevea_manual.kwd184"></a>
<a id="hevea_manual.kwd185"></a>
<a id="hevea_manual.kwd186"></a>
<a id="hevea_manual.kwd187"></a>
<a id="hevea_manual.kwd188"></a>
<a id="hevea_manual.kwd189"></a>
<a id="hevea_manual.kwd190"></a></p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="module-expr"><span class="c010">module-expr</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#module-path"><span class="c010">module-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">struct</span> [ <a class="syntax" href="#module-items"><span class="c010">module-items</span></a> ] <span class="c004">end</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">functor</span> <span class="c004">(</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span> <span class="c004">-&gt;</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">(</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="module-items"><span class="c010">module-items</span></a></td><td class="c015">::=</td><td class="c017">
{<span class="c004">;;</span>} ( <a class="syntax" href="#definition"><span class="c010">definition</span></a> ∣  <a class="syntax" href="#expr"><span class="c010">expr</span></a> )  { {<span class="c004">;;</span>} ( <a class="syntax" href="#definition"><span class="c010">definition</span></a> ∣  <span class="c004">;;</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>) }  {<span class="c004">;;</span>}
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="definition"><span class="c010">definition</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">let</span> [<span class="c004">rec</span>] <a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a>  { <span class="c004">and</span> <a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">external</span> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#external-declaration"><span class="c010">external-declaration</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#type-definition"><span class="c010">type-definition</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#exception-definition"><span class="c010">exception-definition</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#class-definition"><span class="c010">class-definition</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#classtype-definition"><span class="c010">classtype-definition</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a>  { <span class="c004">(</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span> }
 [ <span class="c004">:</span> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> ]  <span class="c004">=</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <span class="c004">type</span> <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">open</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">include</span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>
</td></tr>
</table></td></tr>
</table></div><p>
See also the following language extensions:
<a href="#s%3Arecursive-modules">recursive modules</a>,
<a href="#s%3Afirst-class-modules">first-class modules</a>,
<a href="#s%3Aexplicit-overriding-open">overriding in open statements</a>,
<a href="#s%3Aattributes">attributes</a>,
<a href="#s%3Aextension-nodes">extension nodes</a> and
<a href="#s%3Agenerative-functors">generative functors</a>.</p>
<!--TOC subsection id="ss:mexpr-simple" 7.11.1  Simple module expressions-->
<h3 class="subsection" id="ss:mexpr-simple"><a class="section-anchor" href="#ss:mexpr-simple" aria-hidden="true"></a>7.11.1  Simple module expressions</h3><!--SEC END --><p>The expression <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> evaluates to the module bound to the name
<a class="syntax" href="#module-path"><span class="c010">module-path</span></a>.</p><p>The expression <span class="c004">(</span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">)</span> evaluates to the same module as
<a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>.</p><p>The expression <span class="c004">(</span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span> checks that the
type of <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> is a subtype of <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>, that is, that all
components specified in <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> are implemented in
<a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>, and their implementation meets the requirements given
in <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>. In other terms, it checks that the implementation
<a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> meets the type specification <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>. The whole
expression evaluates to the same module as <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>, except that
all components not specified in <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> are hidden and can no
longer be accessed.</p>
<!--TOC subsection id="ss:mexpr-structures" 7.11.2  Structures-->
<h3 class="subsection" id="ss:mexpr-structures"><a class="section-anchor" href="#ss:mexpr-structures" aria-hidden="true"></a>7.11.2  Structures</h3><!--SEC END --><p><a id="hevea_manual.kwd191"></a>
<a id="hevea_manual.kwd192"></a></p><p>Structures <span class="c004">struct</span> … <span class="c004">end</span> are collections of definitions for
value names, type names, exceptions, module names and module type
names. The definitions are evaluated in the order in which they appear
in the structure. The scopes of the bindings performed by the
definitions extend to the end of the structure. As a consequence, a
definition may refer to names bound by earlier definitions in the same
structure.</p><p>For compatibility with toplevel phrases (chapter <a href="#c%3Acamllight">10</a>),
optional <span class="c004">;;</span> are allowed after and before each definition in a structure. These
<span class="c004">;;</span> have no semantic meanings. Similarly, an <a class="syntax" href="#expr"><span class="c010">expr</span></a> preceded by <span class="c003">;;</span> is allowed as
a component of a structure. It is equivalent to <span class="c002"><span class="c003">let</span> <span class="c003">_</span> <span class="c003">=</span></span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>, i.e. <a class="syntax" href="#expr"><span class="c010">expr</span></a> is
evaluated for its side-effects but is not bound to any identifier. If <a class="syntax" href="#expr"><span class="c010">expr</span></a> is
the first component of a structure, the preceding <span class="c003">;;</span> can be omitted.</p><!--TOC subsubsection id="sss:mexpr-value-defs" Value definitions-->
<h4 class="subsubsection" id="sss:mexpr-value-defs"><a class="section-anchor" href="#sss:mexpr-value-defs" aria-hidden="true"></a>Value definitions</h4><!--SEC END --><p><a id="hevea_manual.kwd193"></a></p><p>A value definition <span class="c004">let</span> [<span class="c004">rec</span>] <a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a>  { <span class="c004">and</span> <a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a> }
bind value names in the same way as a <span class="c004">let</span> … <span class="c004">in</span> … expression
(see section <a href="#sss%3Aexpr-localdef">7.7.2</a>). The value names appearing in the
left-hand sides of the bindings are bound to the corresponding values
in the right-hand sides.</p><p><a id="hevea_manual.kwd194"></a></p><p>A value definition <span class="c004">external</span> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#external-declaration"><span class="c010">external-declaration</span></a>
implements <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> as the external function specified in
<a class="syntax" href="#external-declaration"><span class="c010">external-declaration</span></a> (see chapter <a href="#c%3Aintf-c">20</a>).</p><!--TOC subsubsection id="sss:mexpr-type-defs" Type definitions-->
<h4 class="subsubsection" id="sss:mexpr-type-defs"><a class="section-anchor" href="#sss:mexpr-type-defs" aria-hidden="true"></a>Type definitions</h4><!--SEC END --><p><a id="hevea_manual.kwd195"></a></p><p>A definition of one or several type components is written
<span class="c004">type</span> <a class="syntax" href="#typedef"><span class="c010">typedef</span></a>  { <span class="c004">and</span> <a class="syntax" href="#typedef"><span class="c010">typedef</span></a> } and consists of a sequence
of mutually recursive definitions of type names.</p><!--TOC subsubsection id="sss:mexpr-exn-defs" Exception definitions-->
<h4 class="subsubsection" id="sss:mexpr-exn-defs"><a class="section-anchor" href="#sss:mexpr-exn-defs" aria-hidden="true"></a>Exception definitions</h4><!--SEC END --><p><a id="hevea_manual.kwd196"></a></p><p>Exceptions are defined with the syntax <span class="c004">exception</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a>
or <span class="c004">exception</span> <a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#constr"><span class="c010">constr</span></a>.</p><!--TOC subsubsection id="sss:mexpr-class-defs" Class definitions-->
<h4 class="subsubsection" id="sss:mexpr-class-defs"><a class="section-anchor" href="#sss:mexpr-class-defs" aria-hidden="true"></a>Class definitions</h4><!--SEC END --><p><a id="hevea_manual.kwd197"></a></p><p>A definition of one or several classes is written <span class="c004">class</span>
<a class="syntax" href="#class-binding"><span class="c010">class-binding</span></a>  { <span class="c004">and</span> <a class="syntax" href="#class-binding"><span class="c010">class-binding</span></a> } and consists of a sequence of
mutually recursive definitions of class names. Class definitions are
described more precisely in section <a href="#ss%3Aclass-def">7.9.3</a>.</p><!--TOC subsubsection id="sss:mexpr-classtype-defs" Class type definitions-->
<h4 class="subsubsection" id="sss:mexpr-classtype-defs"><a class="section-anchor" href="#sss:mexpr-classtype-defs" aria-hidden="true"></a>Class type definitions</h4><!--SEC END --><p><a id="hevea_manual.kwd198"></a>
<a id="hevea_manual.kwd199"></a></p><p>A definition of one or several classes is written
<span class="c002"><span class="c003">class</span> <span class="c003">type</span></span> <a class="syntax" href="#classtype-def"><span class="c010">classtype-def</span></a>  { <span class="c004">and</span> <a class="syntax" href="#classtype-def"><span class="c010">classtype-def</span></a> } and consists of
a sequence of mutually recursive definitions of class type names.
Class type definitions are described more precisely in
section <a href="#ss%3Aclasstype">7.9.5</a>.</p><!--TOC subsubsection id="sss:mexpr-module-defs" Module definitions-->
<h4 class="subsubsection" id="sss:mexpr-module-defs"><a class="section-anchor" href="#sss:mexpr-module-defs" aria-hidden="true"></a>Module definitions</h4><!--SEC END --><p><a id="hevea_manual.kwd200"></a></p><p>The basic form for defining a module component is
<span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>, which evaluates <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> and binds
the result to the name <a class="syntax" href="#module-name"><span class="c010">module-name</span></a>.</p><p>One can write
</p><div class="center">
<span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>
</div><p>
instead of
</p><div class="center">
<span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c002"><span class="c003">=</span> <span class="c003">(</span></span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span>.
</div><p>
Another derived form is
</p><div class="center">
<span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">(</span>  <span class="c010">name</span><sub>1</sub> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>1</sub> <span class="c004">)</span> …
<span class="c004">(</span>  <span class="c010">name</span><sub><span class="c009">n</span></sub> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub><span class="c009">n</span></sub> <span class="c002"><span class="c003">)</span> <span class="c003">=</span></span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>
</div><p>
which is equivalent to
</p><div class="center">
<span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c002"><span class="c003">=</span>
<span class="c003">functor</span> <span class="c003">(</span></span>  <span class="c010">name</span><sub>1</sub> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>1</sub> <span class="c002"><span class="c003">)</span> <span class="c003">-&gt;</span></span> …
<span class="c004">-&gt;</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>
</div><!--TOC subsubsection id="sss:mexpr-modtype-defs" Module type definitions-->
<h4 class="subsubsection" id="sss:mexpr-modtype-defs"><a class="section-anchor" href="#sss:mexpr-modtype-defs" aria-hidden="true"></a>Module type definitions</h4><!--SEC END --><p><a id="hevea_manual.kwd201"></a>
<a id="hevea_manual.kwd202"></a></p><p>A definition for a module type is written
<span class="c002"><span class="c003">module</span> <span class="c003">type</span></span> <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>.
It binds the name <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a> to the module type denoted by the
expression <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>.</p><!--TOC subsubsection id="sss:mexpr-open" Opening a module path-->
<h4 class="subsubsection" id="sss:mexpr-open"><a class="section-anchor" href="#sss:mexpr-open" aria-hidden="true"></a>Opening a module path</h4><!--SEC END --><p><a id="hevea_manual.kwd203"></a></p><p>The expression <span class="c004">open</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> in a structure does not define any
components nor perform any bindings. It simply affects the parsing of
the following items of the structure, allowing components of the
module denoted by <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> to be referred to by their simple names
<span class="c010">name</span> instead of path accesses <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span>  <span class="c010">name</span>. The scope of
the <span class="c004">open</span> stops at the end of the structure expression.</p><!--TOC subsubsection id="sss:mexpr-include" Including the components of another structure-->
<h4 class="subsubsection" id="sss:mexpr-include"><a class="section-anchor" href="#sss:mexpr-include" aria-hidden="true"></a>Including the components of another structure</h4><!--SEC END --><p><a id="hevea_manual.kwd204"></a></p><p>The expression <span class="c004">include</span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> in a structure re-exports in
the current structure all definitions of the structure denoted by
<a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>. For instance, if you define a module <span class="c003">S</span> as below


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> S = <span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">type</span> t = int  <span class="ocamlkeyword">let</span> x = 2 <span class="ocamlkeyword">end</span></div></div>

</div><p>


defining the module <span class="c003">B</span> as


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> B = <span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">include</span> S  <span class="ocamlkeyword">let</span> y = (x + 1 : t) <span class="ocamlkeyword">end</span></div></div>

</div><p>


is equivalent to defining it as


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> B = <span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">type</span> t = S.t  <span class="ocamlkeyword">let</span> x = S.x  <span class="ocamlkeyword">let</span> y = (x + 1 : t) <span class="ocamlkeyword">end</span></div></div>

</div><p>


The difference between <span class="c004">open</span> and <span class="c004">include</span> is that <span class="c004">open</span>
simply provides short names for the components of the opened
structure, without defining any components of the current structure,
while <span class="c004">include</span> also adds definitions for the components of the
included structure.</p>
<!--TOC subsection id="ss:mexpr-functors" 7.11.3  Functors-->
<h3 class="subsection" id="ss:mexpr-functors"><a class="section-anchor" href="#ss:mexpr-functors" aria-hidden="true"></a>7.11.3  Functors</h3><!--SEC END --><!--TOC subsubsection id="sss:mexpr-functor-defs" Functor definition-->
<h4 class="subsubsection" id="sss:mexpr-functor-defs"><a class="section-anchor" href="#sss:mexpr-functor-defs" aria-hidden="true"></a>Functor definition</h4><!--SEC END --><p><a id="hevea_manual.kwd205"></a></p><p>The expression <span class="c002"><span class="c003">functor</span> <span class="c003">(</span></span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c002"><span class="c003">)</span> <span class="c003">-&gt;</span></span>
 <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> evaluates to a functor that takes as argument modules of
the type <a class="syntax" href="#module-type"><span class="c010">module-type</span></a><sub>1</sub>, binds <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> to these modules,
evaluates <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> in the extended environment, and returns the
resulting modules as results. No restrictions are placed on the type of the
functor argument; in particular, a functor may take another functor as
argument (“higher-order” functor).</p><!--TOC subsubsection id="sss:mexpr-functor-app" Functor application-->
<h4 class="subsubsection" id="sss:mexpr-functor-app"><a class="section-anchor" href="#sss:mexpr-functor-app" aria-hidden="true"></a>Functor application</h4><!--SEC END --><p>The expression <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a><sub>1</sub> <span class="c004">(</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a><sub>2</sub> <span class="c004">)</span> evaluates
<a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a><sub>1</sub> to a functor and <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a><sub>2</sub> to a module, and
applies the former to the latter. The type of <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a><sub>2</sub> must
match the type expected for the arguments of the functor <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a><sub>1</sub>.</p>
<!--TOC section id="s:compilation-units" 7.12  Compilation units-->
<h2 class="section" id="s:compilation-units"><a class="section-anchor" href="#s:compilation-units" aria-hidden="true"></a>7.12  Compilation units</h2><!--SEC END --><!--NAME compunit.html-->
<div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="unit-interface"><span class="c010">unit-interface</span></a></td><td class="c015">::=</td><td class="c017"> { <a class="syntax" href="#specification"><span class="c010">specification</span></a>  [<span class="c004">;;</span>] }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="unit-implementation"><span class="c010">unit-implementation</span></a></td><td class="c015">::=</td><td class="c017"> [ <a class="syntax" href="#module-items"><span class="c010">module-items</span></a> ]
</td></tr>
</table></td></tr>
</table></div><p>Compilation units bridge the module system and the separate
compilation system. A compilation unit is composed of two parts: an
interface and an implementation. The interface contains a sequence of
specifications, just as the inside of a <span class="c004">sig</span> … <span class="c004">end</span>
signature expression. The implementation contains a sequence of
definitions and expressions, just as the inside of a
<span class="c004">struct</span> … <span class="c004">end</span> module
expression. A compilation unit also has a name <span class="c010">unit-name</span>, derived
from the names of the files containing the interface and the
implementation (see chapter <a href="#c%3Acamlc">9</a> for more details). A
compilation unit behaves roughly as the module definition
</p><div class="center">
<span class="c002"><span class="c003">module</span> <span class="c010">unit-name</span> <span class="c003">:</span> <span class="c003">sig</span></span>  <a class="syntax" href="#unit-interface"><span class="c010">unit-interface</span></a> <span class="c002"><span class="c003">end</span> <span class="c003">=</span>
<span class="c003">struct</span></span>  <a class="syntax" href="#unit-implementation"><span class="c010">unit-implementation</span></a> <span class="c004">end</span>
</div><p>A compilation unit can refer to other compilation units by their
names, as if they were regular modules. For instance, if <span class="c003">U</span> is a
compilation unit that defines a type <span class="c003">t</span>, other compilation units can
refer to that type under the name <span class="c003">U.t</span>; they can also refer to <span class="c003">U</span> as
a whole structure. Except for names of other compilation units, a unit
interface or unit implementation must not have any other free variables.
In other terms, the type-checking and compilation of an interface or
implementation proceeds in the initial environment
</p><div class="center">
<span class="c010">name</span><sub>1</sub> <span class="c002"><span class="c003">:</span> <span class="c003">sig</span></span>  <a class="syntax" href="#specification"><span class="c010">specification</span></a><sub>1</sub> <span class="c004">end</span> …
 <span class="c010">name</span><sub><span class="c009">n</span></sub> <span class="c002"><span class="c003">:</span> <span class="c003">sig</span></span>  <a class="syntax" href="#specification"><span class="c010">specification</span></a><sub><span class="c009">n</span></sub> <span class="c004">end</span>
</div><p>
where <span class="c010">name</span><sub>1</sub> …  <span class="c010">name</span><sub><span class="c009">n</span></sub> are the names of the other
compilation units available in the search path (see
chapter <a href="#c%3Acamlc">9</a> for more details) and <a class="syntax" href="#specification"><span class="c010">specification</span></a><sub>1</sub> …
 <a class="syntax" href="#specification"><span class="c010">specification</span></a><sub><span class="c009">n</span></sub> are their respective interfaces.

</p><!--CUT END -->

<!--TOC chapter id="sec238" Chapter 8  Language extensions-->
<h1 class="chapter" id="sec238">Chapter 8  Language extensions</h1><!--SEC END --><p> <a id="c:extensions"></a>
</p><!--NAME extn.html-->
<p>This chapter describes language extensions and convenience features
that are implemented in OCaml, but not described in the
OCaml reference manual.</p><!--CUT DEF section  -->
<!--TOC section id="s:letrecvalues" 8.1  Recursive definitions of values-->
<h2 class="section" id="s:letrecvalues"><a class="section-anchor" href="#s:letrecvalues" aria-hidden="true"></a>8.1  Recursive definitions of values</h2><!--SEC END --><!--NAME letrecvalues.html-->
<p>(Introduced in Objective Caml 1.00)</p><p>As mentioned in section <a href="#sss%3Aexpr-localdef">7.7.2</a>, the <span class="c002"><span class="c003">let</span> <span class="c003">rec</span></span> binding
construct, in addition to the definition of recursive functions,
also supports a certain class of recursive definitions of
non-functional values, such as
</p><div class="center">
<span class="c002"><span class="c003">let</span> <span class="c003">rec</span></span> <span class="c010">name</span><sub>1</sub> <span class="c002"><span class="c003">=</span> <span class="c003">1</span> <span class="c003">::</span></span>  <span class="c010">name</span><sub>2</sub>
<span class="c004">and</span>  <span class="c010">name</span><sub>2</sub> <span class="c002"><span class="c003">=</span> <span class="c003">2</span> <span class="c003">::</span></span>  <span class="c010">name</span><sub>1</sub>
<span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p>
which binds <span class="c010">name</span><sub>1</sub> to the cyclic list <span class="c003">1::2::1::2::</span>…, and
<span class="c010">name</span><sub>2</sub> to the cyclic list <span class="c003">2::1::2::1::</span>…Informally, the class of accepted definitions consists of those
definitions where the defined names occur only inside function
bodies or as argument to a data constructor.</p><p>More precisely, consider the expression:
</p><div class="center">
<span class="c002"><span class="c003">let</span> <span class="c003">rec</span></span> <span class="c010">name</span><sub>1</sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">and</span> … <span class="c004">and</span>  <span class="c010">name</span><sub><span class="c009">n</span></sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</div><p>
It will be accepted if each one of <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> …  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> is
statically constructive with respect to <span class="c010">name</span><sub>1</sub> …  <span class="c010">name</span><sub><span class="c009">n</span></sub>,
is not immediately linked to any of <span class="c010">name</span><sub>1</sub> …  <span class="c010">name</span><sub><span class="c009">n</span></sub>,
and is not an array constructor whose arguments have abstract type.</p><p>An expression <span class="c010">e</span> is said to be <em>statically constructive
with respect to</em> the variables <span class="c010">name</span><sub>1</sub> …  <span class="c010">name</span><sub><span class="c009">n</span></sub> if at least
one of the following conditions is true:
</p><ul class="itemize"><li class="li-itemize">
<span class="c010">e</span> has no free occurrence of any of <span class="c010">name</span><sub>1</sub> …  <span class="c010">name</span><sub><span class="c009">n</span></sub>
</li><li class="li-itemize"><span class="c010">e</span> is a variable
</li><li class="li-itemize"><span class="c010">e</span> has the form <span class="c004">fun</span> … <span class="c004">-&gt;</span> …
</li><li class="li-itemize"><span class="c010">e</span> has the form <span class="c004">function</span> … <span class="c004">-&gt;</span> …
</li><li class="li-itemize"><span class="c010">e</span> has the form <span class="c002"><span class="c003">lazy</span> <span class="c003">(</span></span> … <span class="c004">)</span>
</li><li class="li-itemize"><span class="c010">e</span> has one of the following forms, where each one of
<a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> …  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">m</span></sub> is statically constructive with respect to
<span class="c010">name</span><sub>1</sub> …  <span class="c010">name</span><sub><span class="c009">n</span></sub>, and <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub> is statically constructive with
respect to <span class="c010">name</span><sub>1</sub> …  <span class="c010">name</span><sub><span class="c009">n</span></sub>,  <span class="c010">xname</span><sub>1</sub> …  <span class="c010">xname</span><sub><span class="c009">m</span></sub>:
<ul class="itemize"><li class="li-itemize">
<span class="c004">let</span> [<span class="c004">rec</span>] <span class="c010">xname</span><sub>1</sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">and</span> …
<span class="c004">and</span>  <span class="c010">xname</span><sub><span class="c009">m</span></sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">m</span></sub> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub>
</li><li class="li-itemize"><span class="c002"><span class="c003">let</span> <span class="c003">module</span></span> … <span class="c004">in</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>
</li><li class="li-itemize"><a class="syntax" href="#constr"><span class="c010">constr</span></a> <span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">,</span> … <span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">m</span></sub><span class="c004">)</span>
</li><li class="li-itemize"><span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a> <span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">,</span> … <span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">m</span></sub><span class="c004">)</span>
</li><li class="li-itemize"><span class="c004">[|</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">m</span></sub> <span class="c004">|]</span>
</li><li class="li-itemize"><span class="c004">{</span> <a class="syntax" href="#field"><span class="c010">field</span></a><sub>1</sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">m</span></sub> =  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">m</span></sub> <span class="c004">}</span>
</li><li class="li-itemize"><span class="c004">{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">with</span>  <a class="syntax" href="#field"><span class="c010">field</span></a><sub>2</sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub><span class="c004">;</span> … <span class="c004">;</span>
 <a class="syntax" href="#field"><span class="c010">field</span></a><sub><span class="c009">m</span></sub> =  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">m</span></sub> <span class="c004">}</span> where <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> is not immediately
linked to <span class="c010">name</span><sub>1</sub> …  <span class="c010">name</span><sub><span class="c009">n</span></sub>
</li><li class="li-itemize"><span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">,</span> … <span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">m</span></sub> <span class="c004">)</span>
</li><li class="li-itemize"><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">m</span></sub>
</li></ul>
</li></ul><p>An expression <span class="c010">e</span> is said to be <em>immediately linked to</em> the variable
<span class="c010">name</span> in the following cases:
</p><ul class="itemize"><li class="li-itemize">
<span class="c010">e</span> is <span class="c010">name</span>
</li><li class="li-itemize"><span class="c010">e</span> has the form <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">;</span> … <span class="c004">;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">m</span></sub> where <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">m</span></sub>
is immediately linked to <span class="c010">name</span>
</li><li class="li-itemize"><span class="c010">e</span> has the form <span class="c004">let</span> [<span class="c004">rec</span>] <span class="c010">xname</span><sub>1</sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">and</span> …
<span class="c004">and</span>  <span class="c010">xname</span><sub><span class="c009">m</span></sub> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">m</span></sub> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub> where <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub> is immediately
linked to <span class="c010">name</span> or to one of the <span class="c010">xname</span><sub><span class="c009">i</span></sub> such that <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">i</span></sub>
is immediately linked to <span class="c010">name</span>.
</li></ul>
<!--TOC section id="s:recursive-modules" 8.2  Recursive modules-->
<h2 class="section" id="s:recursive-modules"><a class="section-anchor" href="#s:recursive-modules" aria-hidden="true"></a>8.2  Recursive modules</h2><!--SEC END --><p>
<a id="hevea_manual.kwd206"></a>
<a id="hevea_manual.kwd207"></a></p><p>(Introduced in Objective Caml 3.07)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#definition"><span class="c010">definition</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <span class="c004">rec</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> 
 { <span class="c004">and</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#specification"><span class="c010">specification</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <span class="c004">rec</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
 { <span class="c004">and</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a><span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> }
</td></tr>
</table></td></tr>
</table></div><p>Recursive module definitions, introduced by the <span class="c004">module rec</span> …<span class="c004">and</span> … construction, generalize regular module definitions
<span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> and module specifications
<span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> by allowing the defining
<a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> and the <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> to refer recursively to the module
identifiers being defined. A typical example of a recursive module
definition is:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">rec</span> A : <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> t = Leaf <span class="ocamlkeyword">of</span> string | Node <span class="ocamlkeyword">of</span> ASet.t
   <span class="ocamlkeyword">val</span> compare: t -&gt; t -&gt; int
 <span class="ocamlkeyword">end</span> = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">type</span> t = Leaf <span class="ocamlkeyword">of</span> string | Node <span class="ocamlkeyword">of</span> ASet.t
   <span class="ocamlkeyword">let</span> compare t1 t2 =
     <span class="ocamlkeyword">match</span> (t1, t2) <span class="ocamlkeyword">with</span>
     | (Leaf s1, Leaf s2) -&gt; Stdlib.compare s1 s2
     | (Leaf _, Node _) -&gt; 1
     | (Node _, Leaf _) -&gt; -1
     | (Node n1, Node n2) -&gt; ASet.compare n1 n2
 <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">and</span> ASet
   : Set.S <span class="ocamlkeyword">with</span> <span class="ocamlkeyword">type</span> elt = A.t
   = Set.Make(A)</div></div>

</div><p>


It can be given the following specification:


</p><div class="caml-example signature">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">rec</span> A : <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> t = Leaf <span class="ocamlkeyword">of</span> string | Node <span class="ocamlkeyword">of</span> ASet.t
   <span class="ocamlkeyword">val</span> compare: t -&gt; t -&gt; int
 <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">and</span> ASet : Set.S <span class="ocamlkeyword">with</span> <span class="ocamlkeyword">type</span> elt = A.t</div></div>

</div><p>This is an experimental extension of OCaml: the class of
recursive definitions accepted, as well as its dynamic semantics are
not final and subject to change in future releases.</p><p>Currently, the compiler requires that all dependency cycles between
the recursively-defined module identifiers go through at least one
“safe” module. A module is “safe” if all value definitions that
it contains have function types <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">-&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>2</sub>. Evaluation of a
recursive module definition proceeds by building initial values for
the safe modules involved, binding all (functional) values to
<span class="c002"><span class="c003">fun</span> <span class="c003">_</span> <span class="c003">-&gt;</span> <span class="c003">raise</span></span> <span class="c003">Undefined_recursive_module</span>. The defining
module expressions are then evaluated, and the initial values
for the safe modules are replaced by the values thus computed. If a
function component of a safe module is applied during this computation
(which corresponds to an ill-founded recursive definition), the
<span class="c003">Undefined_recursive_module</span> exception is raised at runtime:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">rec</span> M: <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">val</span> f: unit -&gt; int <span class="ocamlkeyword">end</span> = <span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">let</span> f () = N.x <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">and</span> N:<span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">val</span> x: int <span class="ocamlkeyword">end</span> = <span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">let</span> x = M.f () <span class="ocamlkeyword">end</span></div>



<div class="pre caml-output ok">Exception: Undefined_recursive_module (<span class="ocamlstring">"exten.etex"</span>, 1, 43).</div></div>

</div><p>If there are no safe modules along a dependency cycle, an error is raised</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">rec</span> M: <span class="ocamlkeyword">sig</span> <span class="ocamlhighlight">val x: int</span> <span class="ocamlkeyword">end</span> = <span class="ocamlhighlight">struct let x = N.y end</span>
 <span class="ocamlkeyword">and</span> N:<span class="ocamlkeyword">sig</span> <span class="ocamlhighlight">val x: int</span> <span class="ocamlkeyword">val</span> y:int <span class="ocamlkeyword">end</span> = <span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">let</span> x = M.x <span class="ocamlkeyword">let</span> y = 0 <span class="ocamlkeyword">end</span></div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: Cannot safely evaluate the definition of the following cycle
       of recursively-defined modules: M -&gt; N -&gt; M.
       There are no safe modules in this cycle (see manual section 8.2).
  Module M defines an unsafe value, x .
  Module N defines an unsafe value, x .</div></div>

</div><p>Note that, in the <a class="syntax" href="#specification"><span class="c010">specification</span></a> case, the <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>s must be
parenthesized if they use the <span class="c004">with</span> <a class="syntax" href="#mod-constraint"><span class="c010">mod-constraint</span></a> construct.</p>
<!--TOC section id="s:private-types" 8.3  Private types-->
<h2 class="section" id="s:private-types"><a class="section-anchor" href="#s:private-types" aria-hidden="true"></a>8.3  Private types</h2><!--SEC END --><!--NAME privatetypes.html-->
<p>
<a id="hevea_manual.kwd208"></a></p><p>Private type declarations in module signatures, of the form
<span class="c003">type t = private ...</span>, enable libraries to
reveal some, but not all aspects of the implementation of a type to
clients of the library. In this respect, they strike a middle ground
between abstract type declarations, where no information is revealed
on the type implementation, and data type definitions and type
abbreviations, where all aspects of the type implementation are
publicized. Private type declarations come in three flavors: for
variant and record types (section <a href="#ss%3Aprivate-types-variant">8.3.1</a>),
for type abbreviations (section <a href="#ss%3Aprivate-types-abbrev">8.3.2</a>),
and for row types (section <a href="#ss%3Aprivate-rows">8.3.3</a>).</p>
<!--TOC subsection id="ss:private-types-variant" 8.3.1  Private variant and record types-->
<h3 class="subsection" id="ss:private-types-variant"><a class="section-anchor" href="#ss:private-types-variant" aria-hidden="true"></a>8.3.1  Private variant and record types</h3><!--SEC END --><p>(Introduced in Objective Caml 3.07)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#type-representation"><span class="c010">type-representation</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">=</span> <span class="c004">private</span> [ <span class="c004">|</span> ] <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a>  { <span class="c004">|</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">=</span> <span class="c004">private</span> <a class="syntax" href="#record-decl"><span class="c010">record-decl</span></a>
</td></tr>
</table></td></tr>
</table></div><p>Values of a variant or record type declared <span class="c004">private</span>
can be de-structured normally in pattern-matching or via
the <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.</span>  <a class="syntax" href="#field"><span class="c010">field</span></a> notation for record accesses. However, values of
these types cannot be constructed directly by constructor application
or record construction. Moreover, assignment on a mutable field of a
private record type is not allowed.</p><p>The typical use of private types is in the export signature of a
module, to ensure that construction of values of the private type always
go through the functions provided by the module, while still allowing
pattern-matching outside the defining module. For example:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> M : <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> t = <span class="ocamlkeyword">private</span> A | B <span class="ocamlkeyword">of</span> int
   <span class="ocamlkeyword">val</span> a : t
   <span class="ocamlkeyword">val</span> b : int -&gt; t
 <span class="ocamlkeyword">end</span> = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">type</span> t = A | B <span class="ocamlkeyword">of</span> int
   <span class="ocamlkeyword">let</span> a = A
   <span class="ocamlkeyword">let</span> b n = <span class="ocamlkeyword">assert</span> (n &gt; 0); B n
 <span class="ocamlkeyword">end</span></div></div>

</div><p>


Here, the <span class="c004">private</span> declaration ensures that in any value of type
<span class="c003">M.t</span>, the argument to the <span class="c003">B</span> constructor is always a positive integer.</p><p>With respect to the variance of their parameters, private types are
handled like abstract types. That is, if a private type has
parameters, their variance is the one explicitly given by prefixing
the parameter by a ‘<span class="c003">+</span>’ or a ‘<span class="c003">-</span>’, it is invariant otherwise.</p>
<!--TOC subsection id="ss:private-types-abbrev" 8.3.2  Private type abbreviations-->
<h3 class="subsection" id="ss:private-types-abbrev"><a class="section-anchor" href="#ss:private-types-abbrev" aria-hidden="true"></a>8.3.2  Private type abbreviations</h3><!--SEC END --><p>(Introduced in Objective Caml 3.11)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#type-equation"><span class="c010">type-equation</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">=</span> <span class="c004">private</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
</td></tr>
</table></td></tr>
</table></div><p>Unlike a regular type abbreviation, a private type abbreviation
declares a type that is distinct from its implementation type <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>.
However, coercions from the type to <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> are permitted.
Moreover, the compiler “knows” the implementation type and can take
advantage of this knowledge to perform type-directed optimizations.</p><p>The following example uses a private type abbreviation to define a
module of nonnegative integers:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> N : <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> t = <span class="ocamlkeyword">private</span> int
   <span class="ocamlkeyword">val</span> of_int: int -&gt; t
   <span class="ocamlkeyword">val</span> to_int: t -&gt; int
 <span class="ocamlkeyword">end</span> = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">type</span> t = int
   <span class="ocamlkeyword">let</span> of_int n = <span class="ocamlkeyword">assert</span> (n &gt;= 0); n
   <span class="ocamlkeyword">let</span> to_int n = n
 <span class="ocamlkeyword">end</span></div></div>

</div><p>


The type <span class="c003">N.t</span> is incompatible with <span class="c003">int</span>, ensuring that nonnegative
integers and regular integers are not confused. However, if <span class="c003">x</span> has
type <span class="c003">N.t</span>, the coercion <span class="c003">(x :&gt; int)</span> is legal and returns the
underlying integer, just like <span class="c003">N.to_int x</span>. Deep coercions are also
supported: if <span class="c003">l</span> has type <span class="c003">N.t list</span>, the coercion <span class="c003">(l :&gt; int list)</span>
returns the list of underlying integers, like <span class="c003">List.map N.to_int l</span>
but without copying the list <span class="c003">l</span>.</p><p>Note that the coercion <span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">:&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">)</span> is actually an abbreviated
form,
and will only work in presence of private abbreviations if neither the
type of <a class="syntax" href="#expr"><span class="c010">expr</span></a> nor <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> contain any type variables. If they do,
you must use the full form <span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> <span class="c004">:&gt;</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>2</sub> <span class="c004">)</span> where
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a><sub>1</sub> is the expected type of <a class="syntax" href="#expr"><span class="c010">expr</span></a>. Concretely, this would be <span class="c003">(x : N.t :&gt; int)</span> and <span class="c003">(l : N.t list :&gt; int list)</span> for the above examples.</p>
<!--TOC subsection id="ss:private-rows" 8.3.3  Private row types-->
<h3 class="subsection" id="ss:private-rows"><a class="section-anchor" href="#ss:private-rows" aria-hidden="true"></a>8.3.3  Private row types</h3><!--SEC END --><p>
<a id="hevea_manual.kwd209"></a></p><p>(Introduced in Objective Caml 3.09)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#type-equation"><span class="c010">type-equation</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">=</span> <span class="c004">private</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
</td></tr>
</table></td></tr>
</table></div><p>Private row types are type abbreviations where part of the
structure of the type is left abstract. Concretely <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> in the
above should denote either an object type or a polymorphic variant
type, with some possibility of refinement left. If the private
declaration is used in an interface, the corresponding implementation
may either provide a ground instance, or a refined private type.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> M : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> c = <span class="ocamlkeyword">private</span> &lt; x : int; .. &gt; <span class="ocamlkeyword">val</span> o : c <span class="ocamlkeyword">end</span> =
 <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">class</span> c = <span class="ocamlkeyword">object</span> <span class="ocamlkeyword">method</span> x = 3 <span class="ocamlkeyword">method</span> y = 2 <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">let</span> o = <span class="ocamlkeyword">new</span> c
 <span class="ocamlkeyword">end</span></div></div>

</div><p>


This declaration does more than hiding the <span class="c003">y</span> method, it also makes
the type <span class="c003">c</span> incompatible with any other closed object type, meaning
that only <span class="c003">o</span> will be of type <span class="c003">c</span>. In that respect it behaves
similarly to private record types. But private row types are
more flexible with respect to incremental refinement. This feature can
be used in combination with functors.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> F(X : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> c = <span class="ocamlkeyword">private</span> &lt; x : int; .. &gt; <span class="ocamlkeyword">end</span>) =
 <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">let</span> get_x (o : X.c) = o#x
 <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">module</span> G(X : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> c = <span class="ocamlkeyword">private</span> &lt; x : int; y : int; .. &gt; <span class="ocamlkeyword">end</span>) =
 <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">include</span> F(X)
   <span class="ocamlkeyword">let</span> get_y (o : X.c) = o#y
 <span class="ocamlkeyword">end</span></div></div>

</div><p>A polymorphic variant type [t], for example


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = [ `A <span class="ocamlkeyword">of</span> int | `B <span class="ocamlkeyword">of</span> bool ]</div></div>

</div><p>


can be refined in two ways. A definition [u] may add new field to [t],
and the declaration


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> u = <span class="ocamlkeyword">private</span> [&gt; t]</div></div>

</div><p>


will keep those new fields abstract. Construction of values of type
[u] is possible using the known variants of [t], but any
pattern-matching will require a default case to handle the potential
extra fields. Dually, a declaration [u] may restrict the fields of [t]
through abstraction: the declaration


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> v = <span class="ocamlkeyword">private</span> [&lt; t &gt; `A]</div></div>

</div><p>


corresponds to private variant types. One cannot create a value of the
private type [v], except using the constructors that are explicitly
listed as present, <span class="c003">(`A n)</span> in this example; yet, when
patter-matching on a [v], one should assume that any of the
constructors of [t] could be present.</p><p>Similarly to abstract types, the variance of type parameters
is not inferred, and must be given explicitly.</p>
<!--TOC section id="s:locally-abstract" 8.4  Locally abstract types-->
<h2 class="section" id="s:locally-abstract"><a class="section-anchor" href="#s:locally-abstract" aria-hidden="true"></a>8.4  Locally abstract types</h2><!--SEC END --><p>
<a id="hevea_manual.kwd210"></a>
<a id="hevea_manual.kwd211"></a>
</p><!--NAME locallyabstract.html-->
<p>(Introduced in OCaml 3.12, short syntax added in 4.03)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#parameter"><span class="c010">parameter</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <span class="c004">type</span> {<a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a>}<sup>+</sup> <span class="c004">)</span>
</td></tr>
</table></td></tr>
</table></div><p>The expression <span class="c002"><span class="c003">fun</span> <span class="c003">(</span> <span class="c003">type</span></span> <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a> <span class="c002"><span class="c003">)</span> <span class="c003">-&gt;</span></span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> introduces a
type constructor named <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a> which is considered abstract
in the scope of the sub-expression, but then replaced by a fresh type
variable. Note that contrary to what the syntax could suggest, the
expression <span class="c002"><span class="c003">fun</span> <span class="c003">(</span> <span class="c003">type</span></span> <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a> <span class="c002"><span class="c003">)</span> <span class="c003">-&gt;</span></span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> itself does not
suspend the evaluation of <a class="syntax" href="#expr"><span class="c010">expr</span></a> as a regular abstraction would. The
syntax has been chosen to fit nicely in the context of function
declarations, where it is generally used. It is possible to freely mix
regular function parameters with pseudo type parameters, as in:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f = <span class="ocamlkeyword">fun</span> (<span class="ocamlkeyword">type</span> t) (foo : t list) -&gt; …</div></div>

</div><p>


and even use the alternative syntax for declaring functions:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f (<span class="ocamlkeyword">type</span> t) (foo : t list) = …</div></div>

</div><p>


If several locally abstract types need to be introduced, it is possible to use
the syntax
<span class="c002"><span class="c003">fun</span> <span class="c003">(</span> <span class="c003">type</span></span> <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a><sub>1</sub> …  <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a><sub><span class="c009">n</span></sub> <span class="c002"><span class="c003">)</span> <span class="c003">-&gt;</span></span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
as syntactic sugar for <span class="c002"><span class="c003">fun</span> <span class="c003">(</span> <span class="c003">type</span></span> <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a><sub>1</sub> <span class="c002"><span class="c003">)</span> <span class="c003">-&gt;</span></span> … <span class="c002"><span class="c003">-&gt;</span>
<span class="c003">fun</span> <span class="c003">(</span> <span class="c003">type</span></span>  <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a><sub><span class="c009">n</span></sub> <span class="c002"><span class="c003">)</span> <span class="c003">-&gt;</span></span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>. For instance,


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f = <span class="ocamlkeyword">fun</span> (<span class="ocamlkeyword">type</span> t u v) -&gt; <span class="ocamlkeyword">fun</span> (foo : (t * u * v) list) -&gt; …
 <span class="ocamlkeyword">let</span> f' (<span class="ocamlkeyword">type</span> t u v) (foo : (t * u * v) list) = …</div></div>

</div><p>This construction is useful because the type constructors it introduces
can be used in places where a type variable is not allowed. For
instance, one can use it to define an exception in a local module
within a polymorphic function.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f (<span class="ocamlkeyword">type</span> t) () =
   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">module</span> M = <span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">exception</span> E <span class="ocamlkeyword">of</span> t <span class="ocamlkeyword">end</span> <span class="ocamlkeyword">in</span>
   (<span class="ocamlkeyword">fun</span> x -&gt; M.E x), (<span class="ocamlkeyword">function</span> M.E x -&gt; Some x | _ -&gt; None)</div></div>

</div><p>Here is another example:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> sort_uniq (<span class="ocamlkeyword">type</span> s) (cmp : s -&gt; s -&gt; int) =
   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">module</span> S = Set.Make(<span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">type</span> t = s <span class="ocamlkeyword">let</span> compare = cmp <span class="ocamlkeyword">end</span>) <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">fun</span> l -&gt;
     S.elements (List.fold_right S.add l S.empty)</div></div>

</div><p>It is also extremely useful for first-class modules (see
section <a href="#s%3Afirst-class-modules">8.5</a>) and generalized algebraic datatypes
(GADTs: see section <a href="#s%3Agadts">8.10</a>).</p>
<!--TOC paragraph id="p:polymorpic-locally-abstract" Polymorphic syntax-->
<h5 class="paragraph" id="p:polymorpic-locally-abstract"><a class="section-anchor" href="#p:polymorpic-locally-abstract" aria-hidden="true"></a>Polymorphic syntax</h5><!--SEC END --><p> (Introduced in OCaml 4.00)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">:</span> <span class="c004">type</span>  { <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a> }<sup>+</sup> <span class="c004">.</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#class-field"><span class="c010">class-field</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">method</span> [<span class="c004">private</span>] <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span> <span class="c004">type</span>
 { <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a> }<sup>+</sup> <span class="c004">.</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">method!</span> [<span class="c004">private</span>] <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> <span class="c004">:</span> <span class="c004">type</span>
 { <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a> }<sup>+</sup> <span class="c004">.</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</td></tr>
</table></td></tr>
</table></div><p>The <span class="c004">(type</span> <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a><span class="c004">)</span> syntax construction by itself does not make
polymorphic the type variable it introduces, but it can be combined
with explicit polymorphic annotations where needed.
The above rule is provided as syntactic sugar to make this easier:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> f : <span class="ocamlkeyword">type</span> t1 t2. t1 * t2 list -&gt; t1 = …</div></div>

</div><p>


is automatically expanded into


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> f : 't1 't2. 't1 * 't2 list -&gt; 't1 =
   <span class="ocamlkeyword">fun</span> (<span class="ocamlkeyword">type</span> t1) (<span class="ocamlkeyword">type</span> t2) -&gt; ( … : t1 * t2 list -&gt; t1)</div></div>

</div><p>


This syntax can be very useful when defining recursive functions involving
GADTs, see the section <a href="#s%3Agadts">8.10</a> for a more detailed explanation.</p><p>The same feature is provided for method definitions.</p>
<!--TOC section id="s:first-class-modules" 8.5  First-class modules-->
<h2 class="section" id="s:first-class-modules"><a class="section-anchor" href="#s:first-class-modules" aria-hidden="true"></a>8.5  First-class modules</h2><!--SEC END --><p>
<a id="hevea_manual.kwd212"></a>
<a id="hevea_manual.kwd213"></a>
<a id="hevea_manual.kwd214"></a>
<a id="hevea_manual.kwd215"></a>
</p><!--NAME firstclassmodules.html-->
<p>(Introduced in OCaml 3.12; pattern syntax and package type inference
introduced in 4.00; structural comparison of package types introduced in 4.02.;
fewer parens required starting from 4.05)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(module</span> <a class="syntax" href="#package-type"><span class="c010">package-type</span></a><span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(val</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>  [<span class="c004">:</span> <a class="syntax" href="#package-type"><span class="c010">package-type</span></a>]<span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(module</span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>  [<span class="c004">:</span> <a class="syntax" href="#package-type"><span class="c010">package-type</span></a>]<span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a>  [<span class="c004">:</span> <a class="syntax" href="#package-type"><span class="c010">package-type</span></a>]<span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="package-type"><span class="c010">package-type</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#modtype-path"><span class="c010">modtype-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#modtype-path"><span class="c010">modtype-path</span></a> <span class="c004">with</span>  <a class="syntax" href="#package-constraint"><span class="c010">package-constraint</span></a>  { <span class="c004">and</span> <a class="syntax" href="#package-constraint"><span class="c010">package-constraint</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="package-constraint"><span class="c010">package-constraint</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">type</span> <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a> <span class="c004">=</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>Modules are typically thought of as static components. This extension
makes it possible to pack a module as a first-class value, which can
later be dynamically unpacked into a module.</p><p>The expression <span class="c002"><span class="c003">(</span> <span class="c003">module</span></span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#package-type"><span class="c010">package-type</span></a> <span class="c004">)</span> converts the
module (structure or functor) denoted by module expression <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>
to a value of the core language that encapsulates this module. The
type of this core language value is <span class="c002"><span class="c003">(</span> <span class="c003">module</span></span> <a class="syntax" href="#package-type"><span class="c010">package-type</span></a> <span class="c004">)</span>.
The <a class="syntax" href="#package-type"><span class="c010">package-type</span></a> annotation can be omitted if it can be inferred
from the context.</p><p>Conversely, the module expression <span class="c002"><span class="c003">(</span> <span class="c003">val</span></span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#package-type"><span class="c010">package-type</span></a> <span class="c004">)</span>
evaluates the core language expression <a class="syntax" href="#expr"><span class="c010">expr</span></a> to a value, which must
have type <span class="c004">module</span> <a class="syntax" href="#package-type"><span class="c010">package-type</span></a>, and extracts the module that was
encapsulated in this value. Again <a class="syntax" href="#package-type"><span class="c010">package-type</span></a> can be omitted if the
type of <a class="syntax" href="#expr"><span class="c010">expr</span></a> is known.
If the module expression is already parenthesized, like the arguments
of functors are, no additional parens are needed: <span class="c003">Map.Make(val key)</span>.</p><p>The pattern <span class="c002"><span class="c003">(</span> <span class="c003">module</span></span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#package-type"><span class="c010">package-type</span></a> <span class="c004">)</span> matches a
package with type <a class="syntax" href="#package-type"><span class="c010">package-type</span></a> and binds it to <a class="syntax" href="#module-name"><span class="c010">module-name</span></a>.
It is not allowed in toplevel let bindings.
Again <a class="syntax" href="#package-type"><span class="c010">package-type</span></a> can be omitted if it can be inferred from the
enclosing pattern.</p><p>The <a class="syntax" href="#package-type"><span class="c010">package-type</span></a> syntactic class appearing in the <span class="c002"><span class="c003">(</span> <span class="c003">module</span></span>
<a class="syntax" href="#package-type"><span class="c010">package-type</span></a> <span class="c004">)</span> type expression and in the annotated forms represents a
subset of module types.
This subset consists of named module types with optional constraints
of a limited form: only non-parametrized types can be specified.</p><p>For type-checking purposes (and starting from OCaml 4.02), package types
are compared using the structural comparison of module types.</p><p>In general, the module expression <span class="c002"><span class="c003">(</span> <span class="c003">val</span></span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">:</span>  <a class="syntax" href="#package-type"><span class="c010">package-type</span></a>
<span class="c004">)</span> cannot be used in the body of a functor, because this could cause
unsoundness in conjunction with applicative functors.
Since OCaml 4.02, this is relaxed in two ways:
if <a class="syntax" href="#package-type"><span class="c010">package-type</span></a> does not contain nominal type declarations (<em>i.e.</em> types that are created with a proper identity), then this
expression can be used anywhere, and even if it contains such types
it can be used inside the body of a generative
functor, described in section <a href="#s%3Agenerative-functors">8.15</a>.
It can also be used anywhere in the context of a local module binding
<span class="c002"><span class="c003">let</span> <span class="c003">module</span></span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c002"><span class="c003">=</span> <span class="c003">(</span> <span class="c003">val</span></span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> <span class="c004">:</span>  <a class="syntax" href="#package-type"><span class="c010">package-type</span></a> <span class="c002"><span class="c003">)</span>
<span class="c003">in</span></span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub>.</p>
<!--TOC paragraph id="p:fst-mod-example" Basic example-->
<h5 class="paragraph" id="p:fst-mod-example"><a class="section-anchor" href="#p:fst-mod-example" aria-hidden="true"></a>Basic example</h5><!--SEC END --><p> A typical use of first-class modules is to
select at run-time among several implementations of a signature.
Each implementation is a structure that we can encapsulate as a
first-class module, then store in a data structure such as a hash
table:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> picture = …
 <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> DEVICE = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">val</span> draw : picture -&gt; unit
   …
 <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">let</span> devices : (string, (<span class="ocamlkeyword">module</span> DEVICE)) Hashtbl.t = Hashtbl.create 17

 <span class="ocamlkeyword">module</span> SVG = <span class="ocamlkeyword">struct</span> … <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">let</span> _ = Hashtbl.add devices <span class="ocamlstring">"SVG"</span> (<span class="ocamlkeyword">module</span> SVG : DEVICE)

 <span class="ocamlkeyword">module</span> PDF = <span class="ocamlkeyword">struct</span> … <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">let</span> _ = Hashtbl.add devices <span class="ocamlstring">"PDF"</span> (<span class="ocamlkeyword">module</span> PDF : DEVICE)</div></div>

</div><p>We can then select one implementation based on command-line
arguments, for instance:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> parse_cmdline () = …
 <span class="ocamlkeyword">module</span> Device =
   (<span class="ocamlkeyword">val</span> (<span class="ocamlkeyword">let</span> device_name = parse_cmdline () <span class="ocamlkeyword">in</span>
         <span class="ocamlkeyword">try</span> Hashtbl.find devices device_name
         <span class="ocamlkeyword">with</span> Not_found -&gt;
           Printf.eprintf <span class="ocamlstring">"Unknown device %s\n"</span> device_name;
           exit 2)
    : DEVICE)</div></div>

</div><p>


Alternatively, the selection can be performed within a function:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> draw_using_device device_name picture =
   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">module</span> Device =
     (<span class="ocamlkeyword">val</span> (Hashtbl.find devices device_name) : DEVICE)
   <span class="ocamlkeyword">in</span>
   Device.draw picture</div></div>

</div>
<!--TOC paragraph id="p:fst-mod-advexamples" Advanced examples-->
<h5 class="paragraph" id="p:fst-mod-advexamples"><a class="section-anchor" href="#p:fst-mod-advexamples" aria-hidden="true"></a>Advanced examples</h5><!--SEC END --><p>
With first-class modules, it is possible to parametrize some code over the
implementation of a module without using a functor.</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> sort (<span class="ocamlkeyword">type</span> s) (<span class="ocamlkeyword">module</span> Set : Set.S <span class="ocamlkeyword">with</span> <span class="ocamlkeyword">type</span> elt = s) l =
   Set.elements (List.fold_right Set.add l Set.empty)</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> sort : (<span class="ocamlkeyword">module</span> Set.S <span class="ocamlkeyword">with</span> <span class="ocamlkeyword">type</span> elt = 's) -&gt; 's list -&gt; 's list = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>To use this function, one can wrap the <span class="c003">Set.Make</span> functor:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> make_set (<span class="ocamlkeyword">type</span> s) cmp =
   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">module</span> S = Set.Make(<span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">type</span> t = s
     <span class="ocamlkeyword">let</span> compare = cmp
   <span class="ocamlkeyword">end</span>) <span class="ocamlkeyword">in</span>
   (<span class="ocamlkeyword">module</span> S : Set.S <span class="ocamlkeyword">with</span> <span class="ocamlkeyword">type</span> elt = s)</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> make_set : ('s -&gt; 's -&gt; int) -&gt; (<span class="ocamlkeyword">module</span> Set.S <span class="ocamlkeyword">with</span> <span class="ocamlkeyword">type</span> elt = 's) = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div>
<!--TOC section id="s:module-type-of" 8.6  Recovering the type of a module-->
<h2 class="section" id="s:module-type-of"><a class="section-anchor" href="#s:module-type-of" aria-hidden="true"></a>8.6  Recovering the type of a module</h2><!--SEC END --><!--NAME moduletypeof.html-->
<p><a id="hevea_manual.kwd216"></a>
<a id="hevea_manual.kwd217"></a>
<a id="hevea_manual.kwd218"></a>
<a id="hevea_manual.kwd219"></a></p><p>(Introduced in OCaml 3.12)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#module-type"><span class="c010">module-type</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <span class="c004">type</span> <span class="c004">of</span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>
</td></tr>
</table></td></tr>
</table></div><p>The construction <span class="c002"><span class="c003">module</span> <span class="c003">type</span> <span class="c003">of</span></span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> expands to the module type
(signature or functor type) inferred for the module expression <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>.
To make this module type reusable in many situations, it is
intentionally not strengthened: abstract types and datatypes are not
explicitly related with the types of the original module.
For the same reason, module aliases in the inferred type are expanded.</p><p>A typical use, in conjunction with the signature-level <span class="c004">include</span>
construct, is to extend the signature of an existing structure.
In that case, one wants to keep the types equal to types in the
original module. This can done using the following idiom.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> MYHASH = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">include</span> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> <span class="ocamlkeyword">of</span> <span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">include</span> Hashtbl <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">val</span> replace: ('a, 'b) t -&gt; 'a -&gt; 'b -&gt; unit
 <span class="ocamlkeyword">end</span></div></div>

</div><p>


The signature <span class="c003">MYHASH</span> then contains all the fields of the signature
of the module <span class="c003">Hashtbl</span> (with strengthened type definitions), plus the
new field <span class="c003">replace</span>. An implementation of this signature can be
obtained easily by using the <span class="c004">include</span> construct again, but this
time at the structure level:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> MyHash : MYHASH = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">include</span> Hashtbl
   <span class="ocamlkeyword">let</span> replace t k v = remove t k; add t k v
 <span class="ocamlkeyword">end</span></div></div>

</div><p>Another application where the absence of strengthening comes handy, is
to provide an alternative implementation for an existing module.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> MySet : <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> <span class="ocamlkeyword">of</span> Set = <span class="ocamlkeyword">struct</span>
   …
 <span class="ocamlkeyword">end</span></div></div>

</div><p>


This idiom guarantees that <span class="c003">Myset</span> is compatible with Set, but allows
it to represent sets internally in a different way.</p>
<!--TOC section id="s:signature-substitution" 8.7  Substituting inside a signature-->
<h2 class="section" id="s:signature-substitution"><a class="section-anchor" href="#s:signature-substitution" aria-hidden="true"></a>8.7  Substituting inside a signature</h2><!--SEC END --><p>
<a id="hevea_manual.kwd220"></a>
<a id="hevea_manual.kwd221"></a>
<a id="hevea_manual.kwd222"></a>
</p><!--NAME signaturesubstitution.html-->

<!--TOC subsection id="ss:destructive-substitution" 8.7.1  Destructive substitutions-->
<h3 class="subsection" id="ss:destructive-substitution"><a class="section-anchor" href="#ss:destructive-substitution" aria-hidden="true"></a>8.7.1  Destructive substitutions</h3><!--SEC END --><p>(Introduced in OCaml 3.12, generalized in 4.06)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#mod-constraint"><span class="c010">mod-constraint</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">type</span> [<a class="syntax" href="#type-params"><span class="c010">type-params</span></a>]  <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a> <span class="c004">:=</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">:=</span>  <a class="syntax" href="#extended-module-path"><span class="c010">extended-module-path</span></a>
</td></tr>
</table></td></tr>
</table></div><p>A “destructive” substitution (<span class="c004">with</span> ... <span class="c004">:=</span> ...) behaves essentially like
normal signature constraints (<span class="c004">with</span> ... <span class="c004">=</span> ...), but it additionally removes
the redefined type or module from the signature.</p><p>Prior to OCaml 4.06, there were a number of restrictions: one could only remove
types and modules at the outermost level (not inside submodules), and in the
case of <span class="c004">with type</span> the definition had to be another type constructor with the
same type parameters.</p><p>A natural application of destructive substitution is merging two
signatures sharing a type name.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> Printable = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> t
   <span class="ocamlkeyword">val</span> print : Format.formatter -&gt; t -&gt; unit
 <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> Comparable = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> t
   <span class="ocamlkeyword">val</span> compare : t -&gt; t -&gt; int
 <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> PrintableComparable = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">include</span> Printable
   <span class="ocamlkeyword">include</span> Comparable <span class="ocamlkeyword">with</span> <span class="ocamlkeyword">type</span> t := t
 <span class="ocamlkeyword">end</span></div></div>

</div><p>One can also use this to completely remove a field:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> S = Comparable <span class="ocamlkeyword">with</span> <span class="ocamlkeyword">type</span> t := int</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> S = <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">val</span> compare : int -&gt; int -&gt; int <span class="ocamlkeyword">end</span></div></div>

</div><p>


or to rename one:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> S = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> u
   <span class="ocamlkeyword">include</span> Comparable <span class="ocamlkeyword">with</span> <span class="ocamlkeyword">type</span> t := u
 <span class="ocamlkeyword">end</span></div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> S = <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> u <span class="ocamlkeyword">val</span> compare : u -&gt; u -&gt; int <span class="ocamlkeyword">end</span></div></div>

</div><p>Note that you can also remove manifest types, by substituting with the
same type.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> ComparableInt = Comparable <span class="ocamlkeyword">with</span> <span class="ocamlkeyword">type</span> t = int ;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> ComparableInt = <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> t = int <span class="ocamlkeyword">val</span> compare : t -&gt; t -&gt; int <span class="ocamlkeyword">end</span></div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> CompareInt = ComparableInt <span class="ocamlkeyword">with</span> <span class="ocamlkeyword">type</span> t := int</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> CompareInt = <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">val</span> compare : int -&gt; int -&gt; int <span class="ocamlkeyword">end</span></div></div>

</div>
<!--TOC subsection id="ss:local-substitution" 8.7.2  Local substitution declarations-->
<h3 class="subsection" id="ss:local-substitution"><a class="section-anchor" href="#ss:local-substitution" aria-hidden="true"></a>8.7.2  Local substitution declarations</h3><!--SEC END --><p>(Introduced in OCaml 4.08)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#specification"><span class="c010">specification</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">type</span> <a class="syntax" href="#type-subst"><span class="c010">type-subst</span></a>  { <span class="c004">and</span> <a class="syntax" href="#type-subst"><span class="c010">type-subst</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:=</span>  <a class="syntax" href="#extended-module-path"><span class="c010">extended-module-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018"><a class="syntax" id="type-subst"><span class="c010">type-subst</span></a></td><td class="c015">::=</td><td class="c017">
[<a class="syntax" href="#type-params"><span class="c010">type-params</span></a>]  <a class="syntax" href="#typeconstr-name"><span class="c010">typeconstr-name</span></a> <span class="c004">:=</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  { <a class="syntax" href="#type-constraint"><span class="c010">type-constraint</span></a> }
</td></tr>
</table></td></tr>
</table></div><p>Local substitutions behave like destructive substitutions (<span class="c004">with</span> ... <span class="c004">:=</span> ...)
but instead of being applied to a whole signature after the fact, they are
introduced during the specification of the signature, and will apply to all the
items that follow.</p><p>This provides a convenient way to introduce local names for types and modules
when defining a signature:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> S = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> t
   <span class="ocamlkeyword">module</span> Sub : <span class="ocamlkeyword">sig</span>
     <span class="ocamlkeyword">type</span> outer := t
     <span class="ocamlkeyword">type</span> t
     <span class="ocamlkeyword">val</span> to_outer : t -&gt; outer
   <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">end</span></div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> S =
  <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> t <span class="ocamlkeyword">module</span> Sub : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> t <span class="ocamlkeyword">val</span> to_outer : t/1 -&gt; t/2 <span class="ocamlkeyword">end</span> <span class="ocamlkeyword">end</span></div></div>

</div><p>Note that, unlike type declarations, type substitution declarations are not
recursive, so substitutions like the following are rejected:</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> S = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> 'a poly_list := [ `Cons <span class="ocamlkeyword">of</span> 'a * 'a <span class="ocamlhighlight">poly_list</span> | `Nil ]
 <span class="ocamlkeyword">end</span> ;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: Unbound type constructor poly_list</div></div>

</div>
<!--TOC section id="s:module-alias" 8.8  Type-level module aliases-->
<h2 class="section" id="s:module-alias"><a class="section-anchor" href="#s:module-alias" aria-hidden="true"></a>8.8  Type-level module aliases</h2><!--SEC END --><p>
<a id="hevea_manual.kwd223"></a>
</p><!--NAME modulealias.html-->
<p>(Introduced in OCaml 4.02)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#specification"><span class="c010">specification</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-path"><span class="c010">module-path</span></a>
</td></tr>
</table></td></tr>
</table></div><p>The above specification, inside a signature, only matches a module
definition equal to <a class="syntax" href="#module-path"><span class="c010">module-path</span></a>. Conversely, a type-level module
alias can be matched by itself, or by any supertype of the type of the
module it references.</p><p>There are several restrictions on <a class="syntax" href="#module-path"><span class="c010">module-path</span></a>:
</p><ol class="enumerate" type=1><li class="li-enumerate">
it should be of the form <span class="c009">M</span><sub>0</sub>.<span class="c009">M</span><sub>1</sub>...<span class="c009">M</span><sub><span class="c009">n</span></sub> (<em>i.e.</em> without
functor applications);
</li><li class="li-enumerate">inside the body of a functor, <span class="c009">M</span><sub>0</sub> should not be one of the
functor parameters;
</li><li class="li-enumerate">inside a recursive module definition, <span class="c009">M</span><sub>0</sub> should not be one of
the recursively defined modules.
</li></ol><p>Such specifications are also inferred. Namely, when <span class="c010">P</span> is a path
satisfying the above constraints,


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> N = P</div></div>

</div><p>


has type


</p><div class="caml-example signature">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> N = P</div></div>

</div><p>Type-level module aliases are used when checking module path
equalities. That is, in a context where module name <span class="c010">N</span> is known to be
an alias for <span class="c010">P</span>, not only these two module paths check as equal, but
<span class="c010">F</span> (<span class="c010">N</span>) and <span class="c010">F</span> (<span class="c010">P</span>) are also recognized as equal. In the default
compilation mode, this is the only difference with the previous
approach of module aliases having just the same module type as the
module they reference.</p><p>When the compiler flag <span class="c004">-no-alias-deps</span> is enabled, type-level
module aliases are also exploited to avoid introducing dependencies
between compilation units. Namely, a module alias referring to a
module inside another compilation unit does not introduce a link-time
dependency on that compilation unit, as long as it is not
dereferenced; it still introduces a compile-time dependency if the
interface needs to be read, <em>i.e.</em> if the module is a submodule
of the compilation unit, or if some type components are referred to.
Additionally, accessing a module alias introduces a link-time
dependency on the compilation unit containing the module referenced by
the alias, rather than the compilation unit containing the alias.
Note that these differences in link-time behavior may be incompatible
with the previous behavior, as some compilation units might not be
extracted from libraries, and their side-effects ignored.</p><p>These weakened dependencies make possible to use module aliases in
place of the <span class="c004">-pack</span> mechanism. Suppose that you have a library
<span class="c004">Mylib</span> composed of modules <span class="c004">A</span> and <span class="c004">B</span>. Using <span class="c004">-pack</span>, one
would issue the command line
</p><pre>ocamlc -pack a.cmo b.cmo -o mylib.cmo
</pre><p>and as a result obtain a <span class="c004">Mylib</span> compilation unit, containing
physically <span class="c004">A</span> and <span class="c004">B</span> as submodules, and with no dependencies on
their respective compilation units.
Here is a concrete example of a possible alternative approach:
</p><ol class="enumerate" type=1><li class="li-enumerate">
Rename the files containing <span class="c004">A</span> and <span class="c004">B</span> to <span class="c004">Mylib__A</span> and
<span class="c004">Mylib__B</span>.
</li><li class="li-enumerate">Create a packing interface <span class="c004">Mylib.ml</span>, containing the
following lines.
<pre>module A = Mylib__A
module B = Mylib__B
</pre></li><li class="li-enumerate">Compile <span class="c004">Mylib.ml</span> using <span class="c004">-no-alias-deps</span>, and the other
files using <span class="c004">-no-alias-deps</span> and <span class="c002"><span class="c003">-open</span> <span class="c003">Mylib</span></span> (the last one is
equivalent to adding the line <span class="c002"><span class="c003">open!</span> <span class="c003">Mylib</span></span> at the top of each
file).
<pre>ocamlc -c -no-alias-deps Mylib.ml
ocamlc -c -no-alias-deps -open Mylib Mylib__*.mli Mylib__*.ml
</pre></li><li class="li-enumerate">Finally, create a library containing all the compilation units,
and export all the compiled interfaces.
<pre>ocamlc -a Mylib*.cmo -o Mylib.cma
</pre></li></ol><p>
This approach lets you access <span class="c004">A</span> and <span class="c004">B</span> directly inside the
library, and as <span class="c004">Mylib.A</span> and <span class="c004">Mylib.B</span> from outside.
It also has the advantage that <span class="c004">Mylib</span> is no longer monolithic: if
you use <span class="c004">Mylib.A</span>, only <span class="c004">Mylib__A</span> will be linked in, not
<span class="c004">Mylib__B</span>.
</p><p>Note the use of double underscores in <span class="c004">Mylib__A</span> and
<span class="c004">Mylib__B</span>. These were chosen on purpose; the compiler uses the
following heuristic when printing paths: given a path <span class="c004">Lib__fooBar</span>,
if <span class="c004">Lib.FooBar</span> exists and is an alias for <span class="c004">Lib__fooBar</span>, then the
compiler will always display <span class="c004">Lib.FooBar</span> instead of
<span class="c004">Lib__fooBar</span>. This way the long <span class="c004">Mylib__</span> names stay hidden and
all the user sees is the nicer dot names. This is how the OCaml
standard library is compiled.</p>
<!--TOC section id="s:explicit-overriding-open" 8.9  Overriding in open statements-->
<h2 class="section" id="s:explicit-overriding-open"><a class="section-anchor" href="#s:explicit-overriding-open" aria-hidden="true"></a>8.9  Overriding in open statements</h2><!--SEC END --><p>
<a id="hevea_manual.kwd224"></a>
</p><!--NAME overridingopen.html-->
<p>(Introduced in OCaml 4.01)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#definition"><span class="c010">definition</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">open!</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#specification"><span class="c010">specification</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">open!</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">let</span> <span class="c004">open!</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">class-body-type</span></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">let</span> <span class="c004">open!</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">in</span>  <a class="syntax" href="#class-body-type"><span class="c010">class-body-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">class-expr</span></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">let</span> <span class="c004">open!</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">in</span>  <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>Since OCaml 4.01, <span class="c004">open</span> statements shadowing an existing identifier
(which is later used) trigger the warning 44. Adding a <span class="c004">!</span>
character after the <span class="c004">open</span> keyword indicates that such a shadowing is
intentional and should not trigger the warning.</p><p>This is also available (since OCaml 4.06) for local opens in class
expressions and class type expressions.</p>
<!--TOC section id="s:gadts" 8.10  Generalized algebraic datatypes-->
<h2 class="section" id="s:gadts"><a class="section-anchor" href="#s:gadts" aria-hidden="true"></a>8.10  Generalized algebraic datatypes</h2><!--SEC END --><p> <a id="hevea_manual.kwd225"></a>
<a id="hevea_manual.kwd226"></a>
</p><!--NAME gadts.html-->
<p>(Introduced in OCaml 4.00)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a> <span class="c004">:</span>  [ <a class="syntax" href="#constr-args"><span class="c010">constr-args</span></a> <span class="c004">-&gt;</span> ]  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#type-param"><span class="c010">type-param</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [<a class="syntax" href="#variance"><span class="c010">variance</span></a>] <span class="c004">_</span>
</td></tr>
</table></td></tr>
</table></div><p>Generalized algebraic datatypes, or GADTs, extend usual sum types in
two ways: constraints on type parameters may change depending on the
value constructor, and some type variables may be existentially
quantified.
Adding constraints is done by giving an explicit return type
(the rightmost <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> in the above syntax), where type parameters
are instantiated.
This return type must use the same type constructor as the type being
defined, and have the same number of parameters.
Variables are made existential when they appear inside a constructor’s
argument, but not in its return type.</p><p>Since the use of a return type often eliminates the need to name type
parameters in the left-hand side of a type definition, one can replace
them with anonymous types <span class="c004">_</span> in that case.</p><p>The constraints associated to each constructor can be recovered
through pattern-matching.
Namely, if the type of the scrutinee of a pattern-matching contains
a locally abstract type, this type can be refined according to the
constructor used.
These extra constraints are only valid inside the corresponding branch
of the pattern-matching.
If a constructor has some existential variables, fresh locally
abstract types are generated, and they must not escape the
scope of this branch.</p>
<!--TOC paragraph id="p:gadts-recfun" Recursive functions-->
<h5 class="paragraph" id="p:gadts-recfun"><a class="section-anchor" href="#p:gadts-recfun" aria-hidden="true"></a>Recursive functions</h5><!--SEC END --><p>Here is a concrete example:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> _ term =
   | Int : int -&gt; int term
   | Add : (int -&gt; int -&gt; int) term
   | App : ('b -&gt; 'a) term * 'b term -&gt; 'a term

 <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> eval : <span class="ocamlkeyword">type</span> a. a term -&gt; a = <span class="ocamlkeyword">function</span>
   | Int n    -&gt; n                 <span class="ocamlcomment">(* a = int *)</span>
   | Add      -&gt; (<span class="ocamlkeyword">fun</span> x y -&gt; x+y)  <span class="ocamlcomment">(* a = int -&gt; int -&gt; int *)</span>
   | App(f,x) -&gt; (eval f) (eval x)
           <span class="ocamlcomment">(* eval called at types (b-&gt;a) and b for fresh b *)</span></div></div>

</div><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> two = eval (App (App (Add, Int 1), Int 1))</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> two : int = 2</div></div>

</div><p>


It is important to remark that the function <span class="c003">eval</span> is using the
polymorphic syntax for locally abstract types. When defining a recursive
function that manipulates a GADT, explicit polymorphic recursion should
generally be used. For instance, the following definition fails with a
type error:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> eval (<span class="ocamlkeyword">type</span> a) : a term -&gt; a = <span class="ocamlkeyword">function</span>
   | Int n    -&gt; n
   | Add      -&gt; (<span class="ocamlkeyword">fun</span> x y -&gt; x+y)
   | App(f,x) -&gt; (eval <span class="ocamlhighlight">f</span>) (eval x)</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type ($App_'b -&gt; a) term
       but an expression was expected of type 'a
       The type constructor $App_'b would escape its scope</div></div>

</div><p>


In absence of an explicit polymorphic annotation, a monomorphic type
is inferred for the recursive function. If a recursive call occurs
inside the function definition at a type that involves an existential
GADT type variable, this variable flows to the type of the recursive
function, and thus escapes its scope. In the above example, this happens
in the branch <span class="c003">App(f,x)</span> when <span class="c003">eval</span> is called with <span class="c003">f</span> as an argument.
In this branch, the type of <span class="c003">f</span> is <span class="c003">($App_ 'b-&gt; a)</span>. The prefix <span class="c003">$</span> in
<span class="c003">$App_ 'b</span> denotes an existential type named by the compiler
(see <a href="#p%3Aexistential-names">8.10</a>). Since the type of <span class="c003">eval</span> is
<span class="c003">'a term -&gt; 'a</span>, the call <span class="c003">eval f</span> makes the existential type <span class="c003">$App_'b</span>
flow to the type variable <span class="c003">'a</span> and escape its scope. This triggers the
above error.</p>
<!--TOC paragraph id="p:gadts-type-inference" Type inference-->
<h5 class="paragraph" id="p:gadts-type-inference"><a class="section-anchor" href="#p:gadts-type-inference" aria-hidden="true"></a>Type inference</h5><!--SEC END --><p>Type inference for GADTs is notoriously hard.
This is due to the fact some types may become ambiguous when escaping
from a branch.
For instance, in the <span class="c003">Int</span> case above, <span class="c003">n</span> could have either type <span class="c003">int</span>
or <span class="c003">a</span>, and they are not equivalent outside of that branch.
As a first approximation, type inference will always work if a
pattern-matching is annotated with types containing no free type
variables (both on the scrutinee and the return type).
This is the case in the above example, thanks to the type annotation
containing only locally abstract types.</p><p>In practice, type inference is a bit more clever than that: type
annotations do not need to be immediately on the pattern-matching, and
the types do not have to be always closed.
As a result, it is usually enough to only annotate functions, as in
the example above. Type annotations are
propagated in two ways: for the scrutinee, they follow the flow of
type inference, in a way similar to polymorphic methods; for the
return type, they follow the structure of the program, they are split
on functions, propagated to all branches of a pattern matching,
and go through tuples, records, and sum types.
Moreover, the notion of ambiguity used is stronger: a type is only
seen as ambiguous if it was mixed with incompatible types (equated by
constraints), without type annotations between them.
For instance, the following program types correctly.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> sum : <span class="ocamlkeyword">type</span> a. a term -&gt; _ = <span class="ocamlkeyword">fun</span> x -&gt;
   <span class="ocamlkeyword">let</span> y =
     <span class="ocamlkeyword">match</span> x <span class="ocamlkeyword">with</span>
     | Int n -&gt; n
     | Add   -&gt; 0
     | App(f,x) -&gt; sum f + sum x
   <span class="ocamlkeyword">in</span> y + 1</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> sum : 'a term -&gt; int = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>


Here the return type <span class="c003">int</span> is never mixed with <span class="c003">a</span>, so it is seen as
non-ambiguous, and can be inferred.
When using such partial type annotations we strongly suggest
specifying the <span class="c003">-principal</span> mode, to check that inference is
principal.</p><p>The exhaustiveness check is aware of GADT constraints, and can
automatically infer that some cases cannot happen.
For instance, the following pattern matching is correctly seen as
exhaustive (the <span class="c003">Add</span> case cannot happen).


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> get_int : int term -&gt; int = <span class="ocamlkeyword">function</span>
   | Int n    -&gt; n
   | App(_,_) -&gt; 0</div></div>

</div>
<!--TOC paragraph id="p:gadt-refutation-cases" Refutation cases-->
<h5 class="paragraph" id="p:gadt-refutation-cases"><a class="section-anchor" href="#p:gadt-refutation-cases" aria-hidden="true"></a>Refutation cases</h5><!--SEC END --><p> (Introduced in OCaml 4.03)</p><p>Usually, the exhaustiveness check only tries to check whether the
cases omitted from the pattern matching are typable or not.
However, you can force it to try harder by adding <em>refutation cases</em>:
</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="matching-case"><span class="c010">matching-case</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a>  [<span class="c004">when</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>] <span class="c004">-&gt;</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a> <span class="c004">-&gt;</span> <span class="c004">.</span>
</td></tr>
</table></td></tr>
</table></div><p>
In presence of a refutation case, the exhaustiveness check will first
compute the intersection of the pattern with the complement of the
cases preceding it. It then checks whether the resulting patterns can
really match any concrete values by trying to type-check them.
Wild cards in the generated patterns are handled in a special way: if
their type is a variant type with only GADT constructors, then the
pattern is split into the different constructors, in order to check whether
any of them is possible (this splitting is not done for arguments of these
constructors, to avoid non-termination). We also split tuples and
variant types with only one case, since they may contain GADTs inside.
For instance, the following code is deemed exhaustive:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> _ t =
   | Int : int t
   | Bool : bool t

 <span class="ocamlkeyword">let</span> deep : (char t * int) option -&gt; char = <span class="ocamlkeyword">function</span>
   | None -&gt; 'c'
   | _ -&gt; .</div></div>

</div><p>Namely, the inferred remaining case is <span class="c003">Some _</span>, which is split into
<span class="c003">Some (Int, _)</span> and <span class="c003">Some (Bool, _)</span>, which are both untypable because
<span class="c003">deep</span> expects a non-existing <span class="c003">char t</span> as the first element of the tuple.
Note that the refutation case could be omitted here, because it is
automatically added when there is only one case in the pattern
matching.</p><p>Another addition is that the redundancy check is now aware of GADTs: a
case will be detected as redundant if it could be replaced by a
refutation case using the same pattern.</p>
<!--TOC paragraph id="p:gadts-advexamples" Advanced examples-->
<h5 class="paragraph" id="p:gadts-advexamples"><a class="section-anchor" href="#p:gadts-advexamples" aria-hidden="true"></a>Advanced examples</h5><!--SEC END --><p>
The <span class="c003">term</span> type we have defined above is an <em>indexed</em> type, where
a type parameter reflects a property of the value contents.
Another use of GADTs is <em>singleton</em> types, where a GADT value
represents exactly one type. This value can be used as runtime
representation for this type, and a function receiving it can have a
polytypic behavior.</p><p>Here is an example of a polymorphic function that takes the
runtime representation of some type <span class="c003">t</span> and a value of the same type,
then pretty-prints the value as a string:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> _ typ =
   | Int : int typ
   | String : string typ
   | Pair : 'a typ * 'b typ -&gt; ('a * 'b) typ

 <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> to_string: <span class="ocamlkeyword">type</span> t. t typ -&gt; t -&gt; string =
   <span class="ocamlkeyword">fun</span> t x -&gt;
   <span class="ocamlkeyword">match</span> t <span class="ocamlkeyword">with</span>
   | Int -&gt; Int.to_string x
   | String -&gt; Printf.sprintf <span class="ocamlstring">"%S"</span> x
   | Pair(t1,t2) -&gt;
       <span class="ocamlkeyword">let</span> (x1, x2) = x <span class="ocamlkeyword">in</span>
       Printf.sprintf <span class="ocamlstring">"(%s,%s)"</span> (to_string t1 x1) (to_string t2 x2)</div></div>

</div><p>Another frequent application of GADTs is equality witnesses.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> (_,_) eq = Eq : ('a,'a) eq

 <span class="ocamlkeyword">let</span> cast : <span class="ocamlkeyword">type</span> a b. (a,b) eq -&gt; a -&gt; b = <span class="ocamlkeyword">fun</span> Eq x -&gt; x</div></div>

</div><p>


Here type <span class="c003">eq</span> has only one constructor, and by matching on it one
adds a local constraint allowing the conversion between <span class="c003">a</span> and <span class="c003">b</span>.
By building such equality witnesses, one can make equal types which
are syntactically different.</p><p>Here is an example using both singleton types and equality witnesses
to implement dynamic types.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> eq_type : <span class="ocamlkeyword">type</span> a b. a typ -&gt; b typ -&gt; (a,b) eq option =
   <span class="ocamlkeyword">fun</span> a b -&gt;
   <span class="ocamlkeyword">match</span> a, b <span class="ocamlkeyword">with</span>
   | Int, Int -&gt; Some Eq
   | String, String -&gt; Some Eq
   | Pair(a1,a2), Pair(b1,b2) -&gt;
       <span class="ocamlkeyword">begin</span> <span class="ocamlkeyword">match</span> eq_type a1 b1, eq_type a2 b2 <span class="ocamlkeyword">with</span>
       | Some Eq, Some Eq -&gt; Some Eq
       | _ -&gt; None
       <span class="ocamlkeyword">end</span>
   | _ -&gt; None

 <span class="ocamlkeyword">type</span> dyn = Dyn : 'a typ * 'a -&gt; dyn

 <span class="ocamlkeyword">let</span> get_dyn : <span class="ocamlkeyword">type</span> a. a typ -&gt; dyn -&gt; a option =
   <span class="ocamlkeyword">fun</span> a (Dyn(b,x)) -&gt;
   <span class="ocamlkeyword">match</span> eq_type a b <span class="ocamlkeyword">with</span>
   | None -&gt; None
   | Some Eq -&gt; Some x</div></div>

</div>
<!--TOC paragraph id="p:existential-names" Existential type names in error messages-->
<h5 class="paragraph" id="p:existential-names"><a class="section-anchor" href="#p:existential-names" aria-hidden="true"></a>Existential type names in error messages</h5><!--SEC END --><p>(Updated in OCaml 4.03.0)</p><p>The typing of pattern matching in presence of GADT can generate many
existential types. When necessary, error messages refer to these
existential types using compiler-generated names. Currently, the
compiler generates these names according to the following nomenclature:
</p><ul class="itemize"><li class="li-itemize">
First, types whose name starts with a <span class="c003">$</span> are existentials.
</li><li class="li-itemize"><span class="c003">$Constr_'a</span> denotes an existential type introduced for the type
variable <span class="c003">'a</span> of the GADT constructor <span class="c003">Constr</span>:


<div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> any = Any : 'name -&gt; any
 <span class="ocamlkeyword">let</span> escape (Any x) = <span class="ocamlhighlight">x</span></div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type $Any_'name
       but an expression was expected of type 'a
       The type constructor $Any_'name would escape its scope</div></div>

</div>


</li><li class="li-itemize"><span class="c003">$Constr</span> denotes an existential type introduced for an anonymous type variable in the GADT constructor <span class="c003">Constr</span>:


<div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> any = Any : _ -&gt; any
 <span class="ocamlkeyword">let</span> escape (Any x) = <span class="ocamlhighlight">x</span></div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This expression has type $Any but an expression was expected of type
         'a
       The type constructor $Any would escape its scope</div></div>

</div>


</li><li class="li-itemize"><span class="c003">$'a</span> if the existential variable was unified with the type variable <span class="c003">'a</span> during typing:


<div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> ('arg,'result,'aux) fn =
   | Fun: ('a -&gt;'b) -&gt; ('a,'b,unit) fn
   | Mem1: ('a -&gt;'b) * 'a * 'b -&gt; ('a, 'b, 'a * 'b) fn
  <span class="ocamlkeyword">let</span> apply: ('arg,'result, _ ) fn -&gt; 'arg -&gt; 'result = <span class="ocamlkeyword">fun</span> f x -&gt;
   <span class="ocamlkeyword">match</span> f <span class="ocamlkeyword">with</span>
   | Fun f -&gt; f x
   | <span class="ocamlhighlight">Mem1 (f,y,fy)</span> -&gt; <span class="ocamlkeyword">if</span> x = y <span class="ocamlkeyword">then</span> fy <span class="ocamlkeyword">else</span> f x</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This pattern matches values of type
         ($'arg, 'result, $'arg * 'result) fn
       but a pattern was expected which matches values of type
         ($'arg, 'result, unit) fn
       The type constructor $'arg would escape its scope</div></div>

</div>


</li><li class="li-itemize"><span class="c003">$n</span> (n a number) is an internally generated existential which could not be named using one of the previous schemes.
</li></ul><p>As shown by the last item, the current behavior is imperfect
and may be improved in future versions.</p>
<!--TOC paragraph id="p:gadt-equation-nonlocal-abstract" Equations on non-local abstract types-->
<h5 class="paragraph" id="p:gadt-equation-nonlocal-abstract"><a class="section-anchor" href="#p:gadt-equation-nonlocal-abstract" aria-hidden="true"></a>Equations on non-local abstract types</h5><!--SEC END --><p> (Introduced in OCaml
4.04)</p><p>GADT pattern-matching may also add type equations to non-local
abstract types. The behaviour is the same as with local abstract
types. Reusing the above <span class="c003">eq</span> type, one can write:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> M : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> t <span class="ocamlkeyword">val</span> x : t <span class="ocamlkeyword">val</span> e : (t,int) eq <span class="ocamlkeyword">end</span> = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">type</span> t = int
   <span class="ocamlkeyword">let</span> x = 33
   <span class="ocamlkeyword">let</span> e = Eq
 <span class="ocamlkeyword">end</span>

 <span class="ocamlkeyword">let</span> x : int = <span class="ocamlkeyword">let</span> Eq = M.e <span class="ocamlkeyword">in</span> M.x</div></div>

</div><p>Of course, not all abstract types can be refined, as this would
contradict the exhaustiveness check. Namely, builtin types (those
defined by the compiler itself, such as <span class="c003">int</span> or <span class="c003">array</span>), and
abstract types defined by the local module, are non-instantiable, and
as such cause a type error rather than introduce an equation.</p>
<!--TOC section id="s:bigarray-access" 8.11  Syntax for Bigarray access-->
<h2 class="section" id="s:bigarray-access"><a class="section-anchor" href="#s:bigarray-access" aria-hidden="true"></a>8.11  Syntax for Bigarray access</h2><!--SEC END --><!--NAME bigarray.html-->
<p>(Introduced in Objective Caml 3.00)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.{</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>  { <span class="c004">,</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> } <span class="c004">}</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.{</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>  { <span class="c004">,</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> } <span class="c004">}</span> <span class="c004">&lt;-</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
</td></tr>
</table></td></tr>
</table></div><p>This extension provides syntactic sugar for getting and setting
elements in the arrays provided by the <a href="libref/Bigarray.html"><span class="c003">Bigarray</span></a> module.</p><p>The short expressions are translated into calls to functions of the
<span class="c003">Bigarray</span> module as described in the following table.</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">expression</span></td><td class="c014"><span class="c013">translation</span> </td></tr>
<tr><td class="c016">
<a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub><span class="c004">.{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">}</span></td><td class="c016"><span class="c003">Bigarray.Array1.get </span><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub> </td></tr>
<tr><td class="c016"><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub><span class="c004">.{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c002"><span class="c003">}</span> <span class="c003">&lt;-</span></span> <a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c016"><span class="c003">Bigarray.Array1.set </span><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> </td></tr>
<tr><td class="c016"><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub><span class="c004">.{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub><span class="c004">}</span></td><td class="c016"><span class="c003">Bigarray.Array2.get </span><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub> </td></tr>
<tr><td class="c016"><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub><span class="c004">.{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub><span class="c002"><span class="c003">}</span> <span class="c003">&lt;-</span></span> <a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c016"><span class="c003">Bigarray.Array2.set </span><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> </td></tr>
<tr><td class="c016"><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub><span class="c004">.{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub><span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub><span class="c004">}</span></td><td class="c016"><span class="c003">Bigarray.Array3.get </span><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub> </td></tr>
<tr><td class="c016"><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub><span class="c004">.{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub><span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub><span class="c002"><span class="c003">}</span> <span class="c003">&lt;-</span></span> <a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c016"><span class="c003">Bigarray.Array3.set </span><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>2</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>3</sub>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> </td></tr>
<tr><td class="c016"><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub><span class="c004">.{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">,</span> …<span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub><span class="c004">}</span></td><td class="c016"><span class="c003">Bigarray.Genarray.get </span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub> <span class="c004">[|</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">,</span> … <span class="c004">,</span>
 <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> <span class="c004">|]</span> </td></tr>
<tr><td class="c016"><a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub><span class="c004">.{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">,</span> …<span class="c004">,</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub><span class="c002"><span class="c003">}</span> <span class="c003">&lt;-</span></span> <a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c016"><span class="c003">Bigarray.Genarray.set </span> <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>0</sub> <span class="c004">[|</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub>1</sub><span class="c004">,</span> … <span class="c004">,</span>
 <a class="syntax" href="#expr"><span class="c010">expr</span></a><sub><span class="c009">n</span></sub> <span class="c004">|]</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a> </td></tr>
</table></div></div><p>The last two entries are valid for any <span class="c009">n</span> &gt; 3.</p>
<!--TOC section id="s:attributes" 8.12  Attributes-->
<h2 class="section" id="s:attributes"><a class="section-anchor" href="#s:attributes" aria-hidden="true"></a>8.12  Attributes</h2><!--SEC END --><!--NAME attributes.html-->
<p><a id="hevea_manual.kwd227"></a></p><p>(Introduced in OCaml 4.02,
infix notations for constructs other than expressions added in 4.03)</p><p>Attributes are “decorations” of the syntax tree which are mostly
ignored by the type-checker but can be used by external tools. An
attribute is made of an identifier and a payload, which can be a
structure, a type expression (prefixed with <span class="c003">:</span>), a signature
(prefixed with <span class="c003">:</span>) or a pattern (prefixed with <span class="c003">?</span>) optionally
followed by a <span class="c003">when</span> clause:</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="attr-id"><span class="c010">attr-id</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <a class="syntax" href="#capitalized-ident"><span class="c010">capitalized-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <a class="syntax" href="#attr-id"><span class="c010">attr-id</span></a> <span class="c004">.</span>  <a class="syntax" href="#attr-id"><span class="c010">attr-id</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="attr-payload"><span class="c010">attr-payload</span></a></td><td class="c015">::=</td><td class="c017">
[ <a class="syntax" href="#module-items"><span class="c010">module-items</span></a> ]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">:</span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">:</span> [ <a class="syntax" href="#specification"><span class="c010">specification</span></a> ]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">?</span> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>  [<span class="c004">when</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>]
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>The first form of attributes is attached with a postfix notation on
“algebraic” categories:</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="attribute"><span class="c010">attribute</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">[@</span> <a class="syntax" href="#attr-id"><span class="c010">attr-id</span></a>  <a class="syntax" href="#attr-payload"><span class="c010">attr-payload</span></a> <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a>  <a class="syntax" href="#attribute"><span class="c010">attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  <a class="syntax" href="#attribute"><span class="c010">attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#pattern"><span class="c010">pattern</span></a>  <a class="syntax" href="#attribute"><span class="c010">attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>  <a class="syntax" href="#attribute"><span class="c010">attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#module-type"><span class="c010">module-type</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>  <a class="syntax" href="#attribute"><span class="c010">attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">class-expr</span></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#class-expr"><span class="c010">class-expr</span></a>  <a class="syntax" href="#attribute"><span class="c010">attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">class-type</span></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#class-type"><span class="c010">class-type</span></a>  <a class="syntax" href="#attribute"><span class="c010">attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>This form of attributes can also be inserted after the <span class="c004">`</span><a class="syntax" href="#tag-name"><span class="c010">tag-name</span></a>
in polymorphic variant type expressions (<a class="syntax" href="#tag-spec-first"><span class="c010">tag-spec-first</span></a>, <a class="syntax" href="#tag-spec"><span class="c010">tag-spec</span></a>,
<a class="syntax" href="#tag-spec-full"><span class="c010">tag-spec-full</span></a>) or after the <a class="syntax" href="#method-name"><span class="c010">method-name</span></a> in <a class="syntax" href="#method-type"><span class="c010">method-type</span></a>.</p><p>The same syntactic form is also used to attach attributes to labels and
constructors in type declarations:</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<span class="c010">field-decl</span></td><td class="c015">::=</td><td class="c017">
[<span class="c004">mutable</span>] <a class="syntax" href="#field-name"><span class="c010">field-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#poly-typexpr"><span class="c010">poly-typexpr</span></a>  {<a class="syntax" href="#attribute"><span class="c010">attribute</span></a>}
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a></td><td class="c015">::=</td><td class="c017">
(<a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a> ∣  <span class="c004">()</span>) [ <span class="c004">of</span> <a class="syntax" href="#constr-args"><span class="c010">constr-args</span></a> ]  {<a class="syntax" href="#attribute"><span class="c010">attribute</span></a>}
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>Note: when a label declaration is followed by a semi-colon, attributes
can also be put after the semi-colon (in which case they are merged to
those specified before).</p><p>The second form of attributes are attached to “blocks” such as type
declarations, class fields, etc:</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="item-attribute"><span class="c010">item-attribute</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">[@@</span> <a class="syntax" href="#attr-id"><span class="c010">attr-id</span></a>  <a class="syntax" href="#attr-payload"><span class="c010">attr-payload</span></a> <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">typedef</span></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#typedef"><span class="c010">typedef</span></a>  <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">exception-definition</span></td><td class="c015">::=</td><td class="c017">
<span class="c004">exception</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">exception</span> <a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#constr"><span class="c010">constr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">module-items</span></td><td class="c015">::=</td><td class="c017">
[<span class="c004">;;</span>] ( <a class="syntax" href="#definition"><span class="c010">definition</span></a> ∣  <a class="syntax" href="#expr"><span class="c010">expr</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> } )  { [<span class="c004">;;</span>] <a class="syntax" href="#definition"><span class="c010">definition</span></a> ∣  <span class="c004">;;</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> } }  [<span class="c004">;;</span>]
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">class-binding</span></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#class-binding"><span class="c010">class-binding</span></a>  <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">class-spec</span></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#class-spec"><span class="c010">class-spec</span></a>  <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">classtype-def</span></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#classtype-def"><span class="c010">classtype-def</span></a>  <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#definition"><span class="c010">definition</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">let</span> [<span class="c004">rec</span>] <a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a>  { <span class="c004">and</span> <a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">external</span> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#external-declaration"><span class="c010">external-declaration</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#type-definition"><span class="c010">type-definition</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#exception-definition"><span class="c010">exception-definition</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#class-definition"><span class="c010">class-definition</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#classtype-definition"><span class="c010">classtype-definition</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a>  { <span class="c004">(</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span> }
 [ <span class="c004">:</span> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> ]  <span class="c004">=</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <span class="c004">type</span> <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">open</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">include</span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <span class="c004">rec</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">=</span> 
 <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> } 
 { <span class="c004">and</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> 
 { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> } }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#specification"><span class="c010">specification</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">val</span> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">external</span> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#external-declaration"><span class="c010">external-declaration</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#type-definition"><span class="c010">type-definition</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">exception</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#class-specification"><span class="c010">class-specification</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#classtype-definition"><span class="c010">classtype-definition</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a>  { <span class="c004">(</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span> }
<span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <span class="c004">type</span> <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <span class="c004">type</span> <a class="syntax" href="#modtype-name"><span class="c010">modtype-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">open</span> <a class="syntax" href="#module-path"><span class="c010">module-path</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">include</span> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>  { <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">class-field-spec</span></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#class-field-spec"><span class="c010">class-field-spec</span></a>  <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#class-field"><span class="c010">class-field</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#class-field"><span class="c010">class-field</span></a>  <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>A third form of attributes appears as stand-alone structure or
signature items in the module or class sub-languages. They are not
attached to any specific node in the syntax tree:</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="floating-attribute"><span class="c010">floating-attribute</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">[@@@</span> <a class="syntax" href="#attr-id"><span class="c010">attr-id</span></a>  <a class="syntax" href="#attr-payload"><span class="c010">attr-payload</span></a> <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#definition"><span class="c010">definition</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#floating-attribute"><span class="c010">floating-attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#specification"><span class="c010">specification</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#floating-attribute"><span class="c010">floating-attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">class-field-spec</span></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#floating-attribute"><span class="c010">floating-attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#class-field"><span class="c010">class-field</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#floating-attribute"><span class="c010">floating-attribute</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>(Note: contrary to what the grammar above describes, <span class="c010">item-attributes</span>
cannot be attached to these floating attributes in <a class="syntax" href="#class-field-spec"><span class="c010">class-field-spec</span></a>
and <a class="syntax" href="#class-field"><span class="c010">class-field</span></a>.)</p><p>It is also possible to specify attributes using an infix syntax. For instance:</p><pre>let[@foo] x = 2 in x + 1          === (let x = 2 [@@foo] in x + 1)
begin[@foo][@bar x] ... end       === (begin ... end)[@foo][@bar x]
module[@foo] M = ...              === module M = ... [@@foo]
type[@foo] t = T                  === type t = T [@@foo]
method[@foo] m = ...              === method m = ... [@@foo]
</pre><p>
For <span class="c003">let</span>, the attributes are applied to each bindings:</p><pre>let[@foo] x = 2 and y = 3 in x + y === (let x = 2 [@@foo] and y = 3 in x + y)
let[@foo] x = 2
and[@bar] y = 3 in x + y           === (let x = 2 [@@foo] and y = 3 [@@bar] in x + y)
</pre>
<!--TOC subsection id="ss:builtin-attributes" 8.12.1  Built-in attributes-->
<h3 class="subsection" id="ss:builtin-attributes"><a class="section-anchor" href="#ss:builtin-attributes" aria-hidden="true"></a>8.12.1  Built-in attributes</h3><!--SEC END --><p>Some attributes are understood by the type-checker:
</p><ul class="itemize"><li class="li-itemize">
“ocaml.warning” or “warning”, with a string literal payload.
This can be used as floating attributes in a
signature/structure/object/object type. The string is parsed and has
the same effect as the <span class="c003">-w</span> command-line option, in the scope between
the attribute and the end of the current
signature/structure/object/object type. The attribute can also be
attached to any kind of syntactic item which support attributes
(such as an expression, or a type expression)
in which case its scope is limited to that item.
Note that it is not well-defined which scope is used for a specific
warning. This is implementation dependent and can change between versions.
Some warnings are even completely outside the control of “ocaml.warning”
(for instance, warnings 1, 2, 14, 29 and 50).</li><li class="li-itemize">“ocaml.warnerror” or “warnerror”, with a string literal payload.
Same as “ocaml.warning”, for the <span class="c003">-warn-error</span> command-line option.</li><li class="li-itemize">“ocaml.alert” or “alert”: see section <a href="#s%3Aalerts">8.21</a>.</li><li class="li-itemize">“ocaml.deprecated” or “deprecated”: alias for the
“deprecated” alert, see section <a href="#s%3Aalerts">8.21</a>.
</li><li class="li-itemize">“ocaml.deprecated_mutable” or “deprecated_mutable”.
Can be applied to a mutable record label. If the label is later
used to modify the field (with “expr.l &lt;- expr”), the “deprecated” alert
will be triggered. If the payload of the attribute is a string literal,
the alert message includes this text.
</li><li class="li-itemize">“ocaml.ppwarning” or “ppwarning”, in any context, with
a string literal payload. The text is reported as warning (22)
by the compiler (currently, the warning location is the location
of the string payload). This is mostly useful for preprocessors which
need to communicate warnings to the user. This could also be used
to mark explicitly some code location for further inspection.
</li><li class="li-itemize">“ocaml.warn_on_literal_pattern” or “warn_on_literal_pattern” annotate
constructors in type definition. A warning (52) is then emitted when this
constructor is pattern matched with a constant literal as argument. This
attribute denotes constructors whose argument is purely informative and
may change in the future. Therefore, pattern matching on this argument
with a constant literal is unreliable. For instance, all built-in exception
constructors are marked as “warn_on_literal_pattern”.
Note that, due to an implementation limitation, this warning (52) is only
triggered for single argument constructor.
</li><li class="li-itemize">“ocaml.tailcall” or “tailcall” can be applied to function
application in order to check that the call is tailcall optimized.
If it it not the case, a warning (51) is emitted.
</li><li class="li-itemize">“ocaml.inline” or “inline” take either “never”, “always”
or nothing as payload on a function or functor definition. If no payload
is provided, the default value is “always”. This payload controls when
applications of the annotated functions should be inlined.
</li><li class="li-itemize">“ocaml.inlined” or “inlined” can be applied to any function or functor
application to check that the call is inlined by the compiler. If the call
is not inlined, a warning (55) is emitted.
</li><li class="li-itemize">“ocaml.noalloc”, “ocaml.unboxed”and “ocaml.untagged” or
“noalloc”, “unboxed” and “untagged” can be used on external
definitions to obtain finer control over the C-to-OCaml interface. See
<a href="#s%3AC-cheaper-call">20.11</a> for more details.
</li><li class="li-itemize">“ocaml.immediate” or “immediate” applied on an abstract type mark the type as
having a non-pointer implementation (e.g. “int”, “bool”, “char” or
enumerated types). Mutation of these immediate types does not activate the
garbage collector’s write barrier, which can significantly boost performance in
programs relying heavily on mutable state.
</li><li class="li-itemize">“ocaml.immediate64” or “immediate64” applied on an abstract type mark the
type as having a non-pointer implementation on 64 bit platforms. No assumption
is made on other platforms. In order to produce a type with the
“immediate64“ attribute, one must use “Sys.Immediate64.Make“ functor.
</li><li class="li-itemize"><span class="c003">ocaml.unboxed</span> or <span class="c003">unboxed</span> can be used on a type definition if the
type is a single-field record or a concrete type with a single
constructor that has a single argument. It tells the compiler to
optimize the representation of the type by removing the block that
represents the record or the constructor (i.e. a value of this type
is physically equal to its argument). In the case of GADTs, an
additional restriction applies: the argument must not be an
existential variable, represented by an existential type variable,
or an abstract type constructor applied to an existential type
variable.
</li><li class="li-itemize"><span class="c003">ocaml.boxed</span> or <span class="c003">boxed</span> can be used on type definitions to mean
the opposite of <span class="c003">ocaml.unboxed</span>: keep the unoptimized
representation of the type. When there is no annotation, the
default is currently <span class="c003">boxed</span> but it may change in the future.
</li><li class="li-itemize"><span class="c003">ocaml.local</span> or <span class="c003">local</span> take either <span class="c003">never</span>, <span class="c003">always</span>, <span class="c003">maybe</span> or
nothing as payload on a function definition. If no payload is
provided, the default is <span class="c003">always</span>. The attribute controls an
optimization which consists in compiling a function into a static
continuation. Contrary to inlining, this optimization does not
duplicate the function’s body. This is possible when all
references to the function are full applications, all sharing the
same continuation (for instance, the returned value of several
branches of a pattern matching). <span class="c003">never</span> disables the optimization,
<span class="c003">always</span> asserts that the optimization applies (otherwise a warning
55 is emitted) and <span class="c003">maybe</span> lets the optimization apply when
possible (this is the default behavior when the attribute is not
specified). The optimization is implicitly disabled when using the
bytecode compiler in debug mode (-g), and for functions marked with
an <span class="c003">ocaml.inline always</span> or <span class="c003">ocaml.unrolled</span> attribute which
supersede <span class="c003">ocaml.local</span>.
</li></ul><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> X = <span class="ocamlkeyword">struct</span>
   [@@@warning <span class="ocamlstring">"+9"</span>]  <span class="ocamlcomment">(* locally enable warning 9 in this structure *)</span>
   …
 <span class="ocamlkeyword">end</span>
 [@@deprecated <span class="ocamlstring">"Please use module 'Y' instead."</span>]

 <span class="ocamlkeyword">let</span> x = <span class="ocamlkeyword">begin</span>[@warning <span class="ocamlstring">"+9"</span>] […] <span class="ocamlkeyword">end</span>

 <span class="ocamlkeyword">type</span> t = A | B
   [@@deprecated <span class="ocamlstring">"Please use type 's' instead."</span>]</div></div>

</div><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> fires_warning_22 x =
   <span class="ocamlkeyword">assert</span> (x &gt;= 0) [@ppwarning <span class="ocamlhighlight">"TODO: remove this later"</span>]</div>



<div class="pre caml-output warn"><span class="ocamlwarning">Warning</span> 22: TODO: remove this later</div></div>

</div><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> is_a_tail_call = <span class="ocamlkeyword">function</span>
   | [] -&gt; ()
   | _ :: q -&gt; (is_a_tail_call[@tailcall]) q

 <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> not_a_tail_call = <span class="ocamlkeyword">function</span>
   | [] -&gt; []
   | x :: q -&gt; x :: <span class="ocamlhighlight">(not_a_tail_call[@tailcall]) q</span></div>



<div class="pre caml-output warn"><span class="ocamlwarning">Warning</span> 51: expected tailcall</div></div>

</div><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> f x = x [@@inline]

 <span class="ocamlkeyword">let</span> () = (f[@inlined]) ()</div></div>

</div><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> fragile =
   | Int <span class="ocamlkeyword">of</span> int [@warn_on_literal_pattern]
   | String <span class="ocamlkeyword">of</span> string [@warn_on_literal_pattern]</div></div>

</div><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> fragile_match_1 = <span class="ocamlkeyword">function</span>
 | Int <span class="ocamlhighlight">0</span> -&gt; ()
 | _ -&gt; ()</div>



<div class="pre caml-output warn"><span class="ocamlwarning">Warning</span> 52: Code should not depend on the actual values of
this constructor's arguments. They are only for information
and may change in future versions. (See manual section 9.5)
val fragile_match_1 : fragile -&gt; unit = &lt;fun&gt;</div></div>

</div><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> fragile_match_2 = <span class="ocamlkeyword">function</span>
 | String <span class="ocamlhighlight">"constant"</span> -&gt; ()
 | _ -&gt; ()</div>



<div class="pre caml-output warn"><span class="ocamlwarning">Warning</span> 52: Code should not depend on the actual values of
this constructor's arguments. They are only for information
and may change in future versions. (See manual section 9.5)
val fragile_match_2 : fragile -&gt; unit = &lt;fun&gt;</div></div>

</div><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Immediate: <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> t [@@immediate]
   <span class="ocamlkeyword">val</span> x: t <span class="ocamlkeyword">ref</span>
 <span class="ocamlkeyword">end</span> = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">type</span> t = A | B
   <span class="ocamlkeyword">let</span> x = <span class="ocamlkeyword">ref</span> A
 <span class="ocamlkeyword">end</span></div></div>

</div><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Int_or_int64 : <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> t [@@immediate64]
   <span class="ocamlkeyword">val</span> zero : t
   <span class="ocamlkeyword">val</span> one : t
   <span class="ocamlkeyword">val</span> add : t -&gt; t -&gt; t
 <span class="ocamlkeyword">end</span> = <span class="ocamlkeyword">struct</span>

   <span class="ocamlkeyword">include</span> Sys.Immediate64.Make(Int)(Int64)

   <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> S = <span class="ocamlkeyword">sig</span>
     <span class="ocamlkeyword">val</span> zero : t
     <span class="ocamlkeyword">val</span> one : t
     <span class="ocamlkeyword">val</span> add : t -&gt; t -&gt; t
   <span class="ocamlkeyword">end</span>

   <span class="ocamlkeyword">let</span> impl : (<span class="ocamlkeyword">module</span> S) =
     <span class="ocamlkeyword">match</span> repr <span class="ocamlkeyword">with</span>
     | Immediate -&gt;
         (<span class="ocamlkeyword">module</span> Int : S)
     | Non_immediate -&gt;
         (<span class="ocamlkeyword">module</span> Int64 : S)

   <span class="ocamlkeyword">include</span> (<span class="ocamlkeyword">val</span> impl : S)
 <span class="ocamlkeyword">end</span></div></div>

</div>
<!--TOC section id="s:extension-nodes" 8.13  Extension nodes-->
<h2 class="section" id="s:extension-nodes"><a class="section-anchor" href="#s:extension-nodes" aria-hidden="true"></a>8.13  Extension nodes</h2><!--SEC END --><!--NAME extensionnodes.html-->
<p>(Introduced in OCaml 4.02,
infix notations for constructs other than expressions added in 4.03,
infix notation (e1 ;%ext e2) added in 4.04.
)</p><p>Extension nodes are generic placeholders in the syntax tree. They are
rejected by the type-checker and are intended to be “expanded” by external
tools such as <span class="c003">-ppx</span> rewriters.</p><p>Extension nodes share the same notion of identifier and payload as
attributes <a href="#s%3Aattributes">8.12</a>.</p><p>The first form of extension node is used for “algebraic” categories:</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="extension"><span class="c010">extension</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">[%</span> <a class="syntax" href="#attr-id"><span class="c010">attr-id</span></a>  <a class="syntax" href="#attr-payload"><span class="c010">attr-payload</span></a> <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#extension"><span class="c010">extension</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#extension"><span class="c010">extension</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#pattern"><span class="c010">pattern</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#extension"><span class="c010">extension</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#extension"><span class="c010">extension</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#module-type"><span class="c010">module-type</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#extension"><span class="c010">extension</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">class-expr</span></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#extension"><span class="c010">extension</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">class-type</span></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#extension"><span class="c010">extension</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>A second form of extension node can be used in structures and
signatures, both in the module and object languages:</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="item-extension"><span class="c010">item-extension</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">[%%</span> <a class="syntax" href="#attr-id"><span class="c010">attr-id</span></a>  <a class="syntax" href="#attr-payload"><span class="c010">attr-payload</span></a> <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#definition"><span class="c010">definition</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#item-extension"><span class="c010">item-extension</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#specification"><span class="c010">specification</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#item-extension"><span class="c010">item-extension</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">class-field-spec</span></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#item-extension"><span class="c010">item-extension</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#class-field"><span class="c010">class-field</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#item-extension"><span class="c010">item-extension</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>An infix form is available for extension nodes when
the payload is of the same kind
(expression with expression, pattern with pattern ...).</p><p>Examples:</p><pre>let%foo x = 2 in x + 1     === [%foo let x = 2 in x + 1]
begin%foo ... end          === [%foo begin ... end]
x ;%foo 2                  === [%foo x; 2]
module%foo M = ..          === [%%foo module M = ... ]
val%foo x : t              === [%%foo: val x : t]
</pre><p>
When this form is used together with the infix syntax for attributes,
the attributes are considered to apply to the payload:</p><pre>fun%foo[@bar] x -&gt; x + 1 === [%foo (fun x -&gt; x + 1)[@bar ] ];
</pre><p>
Furthermore, quoted strings <span class="c003">{|...|}</span> can be combined with extension nodes
to embed foreign syntax fragments. Those fragments can be interpreted
by a preprocessor and turned into OCaml code without requiring escaping
quotes. A syntax shortcut is available for them:</p><pre>{%%foo|...|}               === [%%foo{|...|}]
let x = {%foo|...|}        === let x = [%foo{|...|}]
let y = {%foo bar|...|bar} === let y = [%foo{bar|...|bar}]
</pre><p>
For instance, you can use <span class="c003">{%sql|...|}</span> to
represent arbitrary SQL statements – assuming you have a ppx-rewriter
that recognizes the <span class="c003">%sql</span> extension.</p><p>Note that the word-delimited form, for example <span class="c003">{sql|...|sql}</span>, should
not be used for signaling that an extension is in use.
Indeed, the user cannot see from the code whether this string literal has
different semantics than they expect. Moreover, giving semantics to a
specific delimiter limits the freedom to change the delimiter to avoid
escaping issues.</p>
<!--TOC subsection id="ss:builtin-extension-nodes" 8.13.1  Built-in extension nodes-->
<h3 class="subsection" id="ss:builtin-extension-nodes"><a class="section-anchor" href="#ss:builtin-extension-nodes" aria-hidden="true"></a>8.13.1  Built-in extension nodes</h3><!--SEC END --><p>(Introduced in OCaml 4.03)</p><p>Some extension nodes are understood by the compiler itself:
</p><ul class="itemize"><li class="li-itemize">
“ocaml.extension_constructor” or “extension_constructor”
take as payload a constructor from an extensible variant type
(see <a href="#s%3Aextensible-variants">8.14</a>) and return its extension
constructor slot.
</li></ul><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = ..
 <span class="ocamlkeyword">type</span> t += X <span class="ocamlkeyword">of</span> int | Y <span class="ocamlkeyword">of</span> string
 <span class="ocamlkeyword">let</span> x = [%extension_constructor X]
 <span class="ocamlkeyword">let</span> y = [%extension_constructor Y]</div></div>

</div><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input">  x &lt;&gt; y;;</div>



<div class="pre caml-output ok">- : bool = <span class="ocamlkeyword">true</span></div></div>

</div>
<!--TOC section id="s:extensible-variants" 8.14  Extensible variant types-->
<h2 class="section" id="s:extensible-variants"><a class="section-anchor" href="#s:extensible-variants" aria-hidden="true"></a>8.14  Extensible variant types</h2><!--SEC END --><!--NAME extensiblevariants.html-->
<p>(Introduced in OCaml 4.02)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#type-representation"><span class="c010">type-representation</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">=</span> <span class="c004">..</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#specification"><span class="c010">specification</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">type</span> [<a class="syntax" href="#type-params"><span class="c010">type-params</span></a>]  <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>  <a class="syntax" href="#type-extension-spec"><span class="c010">type-extension-spec</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#definition"><span class="c010">definition</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">type</span> [<a class="syntax" href="#type-params"><span class="c010">type-params</span></a>]  <a class="syntax" href="#typeconstr"><span class="c010">typeconstr</span></a>  <a class="syntax" href="#type-extension-def"><span class="c010">type-extension-def</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="type-extension-spec"><span class="c010">type-extension-spec</span></a></td><td class="c015">::=</td><td class="c017"> <span class="c004">+=</span> [<span class="c004">private</span>] [<span class="c004">|</span>] <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a>  { <span class="c004">|</span> <a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="type-extension-def"><span class="c010">type-extension-def</span></a></td><td class="c015">::=</td><td class="c017"> <span class="c004">+=</span> [<span class="c004">private</span>] [<span class="c004">|</span>] <a class="syntax" href="#constr-def"><span class="c010">constr-def</span></a>  { <span class="c004">|</span> <a class="syntax" href="#constr-def"><span class="c010">constr-def</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="constr-def"><span class="c010">constr-def</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#constr-decl"><span class="c010">constr-decl</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#constr-name"><span class="c010">constr-name</span></a> <span class="c004">=</span>  <a class="syntax" href="#constr"><span class="c010">constr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>Extensible variant types are variant types which can be extended with
new variant constructors. Extensible variant types are defined using
<span class="c003">..</span>. New variant constructors are added using <span class="c003">+=</span>.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Expr = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">type</span> attr = ..

   <span class="ocamlkeyword">type</span> attr += Str <span class="ocamlkeyword">of</span> string

   <span class="ocamlkeyword">type</span> attr +=
     | Int <span class="ocamlkeyword">of</span> int
     | Float <span class="ocamlkeyword">of</span> float
 <span class="ocamlkeyword">end</span></div></div>

</div><p>Pattern matching on an extensible variant type requires a default case
to handle unknown variant constructors:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> to_string = <span class="ocamlkeyword">function</span>
   | Expr.Str s -&gt; s
   | Expr.Int i -&gt; Int.to_string i
   | Expr.Float f -&gt; string_of_float f
   | _ -&gt; <span class="ocamlstring">"?"</span></div></div>

</div><p>A preexisting example of an extensible variant type is the built-in
<span class="c003">exn</span> type used for exceptions. Indeed, exception constructors can be
declared using the type extension syntax:


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> exn += Exc <span class="ocamlkeyword">of</span> int</div></div>

</div><p>Extensible variant constructors can be rebound to a different name. This
allows exporting variants from another module.


</p><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> not_in_scope = <span class="ocamlhighlight">Str</span> <span class="ocamlstring">"Foo"</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: Unbound constructor Str</div></div>

</div><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> Expr.attr += Str = Expr.Str</div></div>

</div><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> now_works = Str <span class="ocamlstring">"foo"</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> now_works : Expr.attr = Expr.Str <span class="ocamlstring">"foo"</span></div></div>

</div><p>Extensible variant constructors can be declared <span class="c003">private</span>. As with
regular variants, this prevents them from being constructed directly by
constructor application while still allowing them to be de-structured in
pattern-matching.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> B : <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> Expr.attr += <span class="ocamlkeyword">private</span> Bool <span class="ocamlkeyword">of</span> int
   <span class="ocamlkeyword">val</span> bool : bool -&gt; Expr.attr
 <span class="ocamlkeyword">end</span> = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">type</span> Expr.attr += Bool <span class="ocamlkeyword">of</span> int
   <span class="ocamlkeyword">let</span> bool p = <span class="ocamlkeyword">if</span> p <span class="ocamlkeyword">then</span> Bool 1 <span class="ocamlkeyword">else</span> Bool 0
 <span class="ocamlkeyword">end</span></div></div>

</div><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> inspection_works = <span class="ocamlkeyword">function</span>
   | B.Bool p -&gt; (p = 1)
   | _ -&gt; <span class="ocamlkeyword">true</span>;;</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> inspection_works : Expr.attr -&gt; bool = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> construction_is_forbidden = <span class="ocamlhighlight">B.Bool 1</span>;;</div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: Cannot use private constructor Bool to create values of type Expr.attr</div></div>

</div>
<!--TOC subsection id="ss:private-extensible" 8.14.1  Private extensible variant types-->
<h3 class="subsection" id="ss:private-extensible"><a class="section-anchor" href="#ss:private-extensible" aria-hidden="true"></a>8.14.1  Private extensible variant types</h3><!--SEC END --><p>(Introduced in OCaml 4.06)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#type-representation"><span class="c010">type-representation</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">=</span> <span class="c004">private</span> <span class="c004">..</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>Extensible variant types can be declared <span class="c003">private</span>. This prevents new
constructors from being declared directly, but allows extension
constructors to be referred to in interfaces.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Msg : <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> t = <span class="ocamlkeyword">private</span> ..
   <span class="ocamlkeyword">module</span> MkConstr (X : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> t <span class="ocamlkeyword">end</span>) : <span class="ocamlkeyword">sig</span>
     <span class="ocamlkeyword">type</span> t += C <span class="ocamlkeyword">of</span> X.t
   <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">end</span> = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">type</span> t = ..
   <span class="ocamlkeyword">module</span> MkConstr (X : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> t <span class="ocamlkeyword">end</span>) = <span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">type</span> t += C <span class="ocamlkeyword">of</span> X.t
   <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">end</span></div></div>

</div>
<!--TOC section id="s:generative-functors" 8.15  Generative functors-->
<h2 class="section" id="s:generative-functors"><a class="section-anchor" href="#s:generative-functors" aria-hidden="true"></a>8.15  Generative functors</h2><!--SEC END --><!--NAME generativefunctors.html-->
<p>(Introduced in OCaml 4.02)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">functor</span> <span class="c004">()</span> <span class="c004">-&gt;</span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">()</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#definition"><span class="c010">definition</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a>  { <span class="c004">(</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span> ∣  <span class="c004">()</span> }
[ <span class="c004">:</span> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> ]  <span class="c004">=</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#module-type"><span class="c010">module-type</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">functor</span> <span class="c004">()</span> <span class="c004">-&gt;</span> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#specification"><span class="c010">specification</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">module</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a>  { <span class="c004">(</span> <a class="syntax" href="#module-name"><span class="c010">module-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#module-type"><span class="c010">module-type</span></a> <span class="c004">)</span> ∣  <span class="c004">()</span> }
<span class="c004">:</span> <a class="syntax" href="#module-type"><span class="c010">module-type</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>A generative functor takes a unit <span class="c003">()</span> argument.
In order to use it, one must necessarily apply it to this unit argument,
ensuring that all type components in the result of the functor behave
in a generative way, <em>i.e.</em> they are different from types obtained
by other applications of the same functor.
This is equivalent to taking an argument of signature <span class="c003">sig end</span>, and always
applying to <span class="c003">struct end</span>, but not to some defined module (in the
latter case, applying twice to the same module would return identical
types).</p><p>As a side-effect of this generativity, one is allowed to unpack
first-class modules in the body of generative functors.</p>
<!--TOC section id="s:extension-syntax" 8.16  Extension-only syntax-->
<h2 class="section" id="s:extension-syntax"><a class="section-anchor" href="#s:extension-syntax" aria-hidden="true"></a>8.16  Extension-only syntax</h2><!--SEC END --><!--NAME extensionsyntax.html-->
<p>
(Introduced in OCaml 4.02.2, extended in 4.03)</p><p>Some syntactic constructions are accepted during parsing and rejected
during type checking. These syntactic constructions can therefore not
be used directly in vanilla OCaml. However, <span class="c003">-ppx</span> rewriters and other
external tools can exploit this parser leniency to extend the language
with these new syntactic constructions by rewriting them to
vanilla constructions.
</p>
<!--TOC subsection id="ss:extension-operators" 8.16.1  Extension operators-->
<h3 class="subsection" id="ss:extension-operators"><a class="section-anchor" href="#ss:extension-operators" aria-hidden="true"></a>8.16.1  Extension operators</h3><!--SEC END --><p> <a id="s:ext-ops"></a>
(Introduced in OCaml 4.02.2)
</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<span class="c010">infix-symbol</span></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">#</span> {<span class="c010">operator-chars</span>} <span class="c004">#</span>   {<a class="syntax" href="#operator-char"><span class="c010">operator-char</span></a> <span class="c004">|</span> <span class="c004">#</span>}
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>Operator names starting with a <span class="c003">#</span> character and containing more than
one <span class="c003">#</span> character are reserved for extensions.</p>
<!--TOC subsection id="ss:extension-literals" 8.16.2  Extension literals-->
<h3 class="subsection" id="ss:extension-literals"><a class="section-anchor" href="#ss:extension-literals" aria-hidden="true"></a>8.16.2  Extension literals</h3><!--SEC END --><p>
(Introduced in OCaml 4.03)
</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<span class="c010">float-literal</span></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [<span class="c004">-</span>] (<span class="c004">0</span>…<span class="c004">9</span>) { <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">_</span> } [<span class="c004">.</span> { <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">_</span> }]
[(<span class="c004">e</span>∣ <span class="c004">E</span>) [<span class="c004">+</span>∣ <span class="c004">-</span>] (<span class="c004">0</span>…<span class="c004">9</span>) { <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">_</span> }]
[<span class="c004">g</span>…<span class="c004">z</span>∣ <span class="c004">G</span>…<span class="c004">Z</span>]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [<span class="c004">-</span>] (<span class="c004">0x</span>∣ <span class="c004">0X</span>)
(<span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span>)
{ <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span>∣ <span class="c004">_</span> }
[<span class="c004">.</span> { <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span>∣ <span class="c004">_</span> }]
[(<span class="c004">p</span>∣ <span class="c004">P</span>) [<span class="c004">+</span>∣ <span class="c004">-</span>] (<span class="c004">0</span>…<span class="c004">9</span>) { <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">_</span> }]
[<span class="c004">g</span>…<span class="c004">z</span>∣ <span class="c004">G</span>…<span class="c004">Z</span>]
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="int-literal"><span class="c010">int-literal</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [<span class="c004">-</span>] (<span class="c004">0</span>…<span class="c004">9</span>) { <span class="c004">0</span>…<span class="c004">9</span> ∣  <span class="c004">_</span> }[<span class="c004">g</span>…<span class="c004">z</span>∣ <span class="c004">G</span>…<span class="c004">Z</span>]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [<span class="c004">-</span>] (<span class="c004">0x</span>∣ <span class="c004">0X</span>) (<span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span>)
{ <span class="c004">0</span>…<span class="c004">9</span>∣ <span class="c004">A</span>…<span class="c004">F</span>∣ <span class="c004">a</span>…<span class="c004">f</span>∣ <span class="c004">_</span> }
[<span class="c004">g</span>…<span class="c004">z</span>∣ <span class="c004">G</span>…<span class="c004">Z</span>]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [<span class="c004">-</span>] (<span class="c004">0o</span>∣ <span class="c004">0O</span>) (<span class="c004">0</span>…<span class="c004">7</span>) { <span class="c004">0</span>…<span class="c004">7</span>∣ <span class="c004">_</span> }
[<span class="c004">g</span>…<span class="c004">z</span>∣ <span class="c004">G</span>…<span class="c004">Z</span>]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> [<span class="c004">-</span>] (<span class="c004">0b</span>∣ <span class="c004">0B</span>) (<span class="c004">0</span>…<span class="c004">1</span>) { <span class="c004">0</span>…<span class="c004">1</span>∣ <span class="c004">_</span> }
[<span class="c004">g</span>…<span class="c004">z</span>∣ <span class="c004">G</span>…<span class="c004">Z</span>]
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>
Int and float literals followed by an one-letter identifier in the
range [<span class="c004">g</span>..<span class="c004">z</span>∣ <span class="c004">G</span>..<span class="c004">Z</span>] are extension-only literals.</p>
<!--TOC section id="s:inline-records" 8.17  Inline records-->
<h2 class="section" id="s:inline-records"><a class="section-anchor" href="#s:inline-records" aria-hidden="true"></a>8.17  Inline records</h2><!--SEC END --><!--NAME inlinerecords.html-->
<p>
(Introduced in OCaml 4.03)
</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<span class="c010">constr-args</span></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#record-decl"><span class="c010">record-decl</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>The arguments of sum-type constructors can now be defined using the
same syntax as records. Mutable and polymorphic fields are allowed.
GADT syntax is supported. Attributes can be specified on individual
fields.</p><p>Syntactically, building or matching constructors with such an inline
record argument is similar to working with a unary constructor whose
unique argument is a declared record type. A pattern can bind
the inline record as a pseudo-value, but the record cannot escape the
scope of the binding and can only be used with the dot-notation to
extract or modify fields or to build new constructor values.</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t =
   | Point <span class="ocamlkeyword">of</span> {width: int; <span class="ocamlkeyword">mutable</span> x: float; <span class="ocamlkeyword">mutable</span> y: float}
   | Other

 <span class="ocamlkeyword">let</span> v = Point {width = 10; x = 0.; y = 0.}

 <span class="ocamlkeyword">let</span> scale l = <span class="ocamlkeyword">function</span>
   | Point p -&gt; Point {p <span class="ocamlkeyword">with</span> x = l *. p.x; y = l *. p.y}
   | Other -&gt; Other

 <span class="ocamlkeyword">let</span> print = <span class="ocamlkeyword">function</span>
   | Point {x; y; _} -&gt; Printf.printf <span class="ocamlstring">"%f/%f"</span> x y
   | Other -&gt; ()

 <span class="ocamlkeyword">let</span> reset = <span class="ocamlkeyword">function</span>
   | Point p -&gt; p.x &lt;- 0.; p.y &lt;- 0.
   | Other -&gt; ()</div></div>

</div><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> invalid = <span class="ocamlkeyword">function</span>
   | Point p -&gt; <span class="ocamlhighlight">p</span></div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: This form is not allowed as the type of the inlined record could escape.</div></div>

</div>
<!--TOC section id="s:doc-comments" 8.18  Documentation comments-->
<h2 class="section" id="s:doc-comments"><a class="section-anchor" href="#s:doc-comments" aria-hidden="true"></a>8.18  Documentation comments</h2><!--SEC END --><!--NAME doccomments.html-->
<p>
(Introduced in OCaml 4.03)</p><p>Comments which start with <span class="c003">**</span> are treated specially by the
compiler. They are automatically converted during parsing into
attributes (see <a href="#s%3Aattributes">8.12</a>) to allow tools to process them as
documentation.</p><p>Such comments can take three forms: <em>floating comments</em>, <em>item
comments</em> and <em>label comments</em>. Any comment starting with <span class="c003">**</span> which
does not match one of these forms will cause the compiler to emit
warning 50.</p><p>Comments which start with <span class="c003">**</span> are also used by the ocamldoc
documentation generator (see <a href="#c%3Aocamldoc">16</a>). The three comment forms
recognised by the compiler are a subset of the forms accepted by
ocamldoc (see <a href="#s%3Aocamldoc-comments">16.2</a>).</p>
<!--TOC subsection id="ss:floating-comments" 8.18.1  Floating comments-->
<h3 class="subsection" id="ss:floating-comments"><a class="section-anchor" href="#ss:floating-comments" aria-hidden="true"></a>8.18.1  Floating comments</h3><!--SEC END --><p>Comments surrounded by blank lines that appear within structures,
signatures, classes or class types are converted into
<a class="syntax" href="#floating-attribute"><span class="c010">floating-attribute</span></a>s. For example:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T

 <span class="ocamlcomment">(** Now some definitions for [t] *)</span>

 <span class="ocamlkeyword">let</span> mkT = T</div></div>

</div><p>will be converted to:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T

 [@@@ocaml.text <span class="ocamlstring">" Now some definitions for [t] "</span>]

 <span class="ocamlkeyword">let</span> mkT = T</div></div>

</div>
<!--TOC subsection id="ss:item-comments" 8.18.2  Item comments-->
<h3 class="subsection" id="ss:item-comments"><a class="section-anchor" href="#ss:item-comments" aria-hidden="true"></a>8.18.2  Item comments</h3><!--SEC END --><p>Comments which appear <em>immediately before</em> or <em>immediately
after</em> a structure item, signature item, class item or class type item
are converted into <a class="syntax" href="#item-attribute"><span class="c010">item-attribute</span></a>s. Immediately before or immediately
after means that there must be no blank lines, <span class="c003">;;</span>, or other
documentation comments between them. For example:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T
 <span class="ocamlcomment">(** A description of [t] *)</span></div></div>

</div><p>or</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlcomment">(** A description of [t] *)</span>
 <span class="ocamlkeyword">type</span> t = T</div></div>

</div><p>will be converted to:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T
 [@@ocaml.doc <span class="ocamlstring">" A description of [t] "</span>]</div></div>

</div><p>Note that, if a comment appears immediately next to multiple items,
as in:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T
 <span class="ocamlcomment">(** An ambiguous comment *)</span>
 <span class="ocamlkeyword">type</span> s = S</div></div>

</div><p>then it will be attached to both items:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T
 [@@ocaml.doc <span class="ocamlstring">" An ambiguous comment "</span>]
 <span class="ocamlkeyword">type</span> s = S
 [@@ocaml.doc <span class="ocamlstring">" An ambiguous comment "</span>]</div></div>

</div><p>and the compiler will emit warning 50.</p>
<!--TOC subsection id="ss:label-comments" 8.18.3  Label comments-->
<h3 class="subsection" id="ss:label-comments"><a class="section-anchor" href="#ss:label-comments" aria-hidden="true"></a>8.18.3  Label comments</h3><!--SEC END --><p>Comments which appear <em>immediately after</em> a labelled argument,
record field, variant constructor, object method or polymorphic variant
constructor are are converted into <a class="syntax" href="#attribute"><span class="c010">attribute</span></a>s. Immediately
after means that there must be no blank lines or other documentation
comments between them. For example:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t1 = lbl:int <span class="ocamlcomment">(** Labelled argument *)</span> -&gt; unit

 <span class="ocamlkeyword">type</span> t2 = {
   fld: int; <span class="ocamlcomment">(** Record field *)</span>
   fld2: float;
 }

 <span class="ocamlkeyword">type</span> t3 =
   | Cstr <span class="ocamlkeyword">of</span> string <span class="ocamlcomment">(** Variant constructor *)</span>
   | Cstr2 <span class="ocamlkeyword">of</span> string

 <span class="ocamlkeyword">type</span> t4 = &lt; meth: int * int; <span class="ocamlcomment">(** Object method *)</span> &gt;

 <span class="ocamlkeyword">type</span> t5 = [
   `PCstr <span class="ocamlcomment">(** Polymorphic variant constructor *)</span>
 ]</div></div>

</div><p>will be converted to:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t1 = lbl:(int [@ocaml.doc <span class="ocamlstring">" Labelled argument "</span>]) -&gt; unit

 <span class="ocamlkeyword">type</span> t2 = {
   fld: int [@ocaml.doc <span class="ocamlstring">" Record field "</span>];
   fld2: float;
 }

 <span class="ocamlkeyword">type</span> t3 =
   | Cstr <span class="ocamlkeyword">of</span> string [@ocaml.doc <span class="ocamlstring">" Variant constructor "</span>]
   | Cstr2 <span class="ocamlkeyword">of</span> string

 <span class="ocamlkeyword">type</span> t4 = &lt; meth : int * int [@ocaml.doc <span class="ocamlstring">" Object method "</span>] &gt;

 <span class="ocamlkeyword">type</span> t5 = [
   `PCstr [@ocaml.doc <span class="ocamlstring">" Polymorphic variant constructor "</span>]
 ]</div></div>

</div><p>Note that label comments take precedence over item comments, so:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T <span class="ocamlkeyword">of</span> string
 <span class="ocamlcomment">(** Attaches to T not t *)</span></div></div>

</div><p>will be converted to:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t =  T <span class="ocamlkeyword">of</span> string [@ocaml.doc <span class="ocamlstring">" Attaches to T not t "</span>]</div></div>

</div><p>whilst:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T <span class="ocamlkeyword">of</span> string
 <span class="ocamlcomment">(** Attaches to T not t *)</span>
 <span class="ocamlcomment">(** Attaches to t *)</span></div></div>

</div><p>will be converted to:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t =  T <span class="ocamlkeyword">of</span> string [@ocaml.doc <span class="ocamlstring">" Attaches to T not t "</span>]
 [@@ocaml.doc <span class="ocamlstring">" Attaches to t "</span>]</div></div>

</div><p>In the absence of meaningful comment on the last constructor of
a type, an empty comment <span class="c003">(**)</span> can be used instead:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = T <span class="ocamlkeyword">of</span> string
 <span class="ocamlcomment">(**)</span>
 <span class="ocamlcomment">(** Attaches to t *)</span></div></div>

</div><p>will be converted directly to</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t =  T <span class="ocamlkeyword">of</span> string
 [@@ocaml.doc <span class="ocamlstring">" Attaches to t "</span>]</div></div>

</div>
<!--TOC section id="s:index-operators" 8.19  Extended indexing operators -->
<h2 class="section" id="s:index-operators"><a class="section-anchor" href="#s:index-operators" aria-hidden="true"></a>8.19  Extended indexing operators </h2><!--SEC END --><!--NAME indexops.html-->
<p>
(Introduced in 4.06)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018"><a class="syntax" id="dot-ext"><span class="c010">dot-ext</span></a></td><td class="c015">::=</td><td class="c017">
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#dot-operator-char"><span class="c010">dot-operator-char</span></a>  { <a class="syntax" href="#operator-char"><span class="c010">operator-char</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="dot-operator-char"><span class="c010">dot-operator-char</span></a></td><td class="c015">::=</td><td class="c017">
<span class="c004">!</span> ∣   <span class="c004">?</span> ∣  <a class="syntax" href="#core-operator-char"><span class="c010">core-operator-char</span></a> ∣  <span class="c004">%</span> ∣  <span class="c004">:</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.</span>  [<a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span>]  <a class="syntax" href="#dot-ext"><span class="c010">dot-ext</span></a>  ( <span class="c004">(</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">)</span> ∣  <span class="c004">[</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">]</span> ∣  <span class="c004">{</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">}</span> )  [ <span class="c004">&lt;-</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> ]
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">operator-name</span></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">.</span> <a class="syntax" href="#dot-ext"><span class="c010">dot-ext</span></a>  (<span class="c004">()</span> ∣  <span class="c004">[]</span> ∣  <span class="c004">{}</span>) [<span class="c004">&lt;-</span>]
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>This extension provides syntactic sugar for getting and setting elements
for user-defined indexed types. For instance, we can define python-like
dictionaries with


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> Dict = <span class="ocamlkeyword">struct</span>
 <span class="ocamlkeyword">include</span> Hashtbl
 <span class="ocamlkeyword">let</span> ( .%{} ) tabl index = find tabl index
 <span class="ocamlkeyword">let</span> ( .%{}&lt;- ) tabl index value = add tabl index value
 <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">let</span> dict =
   <span class="ocamlkeyword">let</span> dict = Dict.create 10 <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">let</span> () =
     dict.Dict.%{<span class="ocamlstring">"one"</span>} &lt;- 1;
     <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">open</span> Dict <span class="ocamlkeyword">in</span>
     dict.%{<span class="ocamlstring">"two"</span>} &lt;- 2 <span class="ocamlkeyword">in</span>
   dict</div></div>

</div><div class="caml-example toplevel">

<div class="ocaml">



<div class="pre caml-input"> dict.Dict.%{<span class="ocamlstring">"one"</span>};;</div>



<div class="pre caml-output ok">- : int = 1</div></div>
<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">open</span> Dict <span class="ocamlkeyword">in</span> dict.%{<span class="ocamlstring">"two"</span>};;</div>



<div class="pre caml-output ok">- : int = 2</div></div>

</div>
<!--TOC subsection id="ss:multiindexing" 8.19.1  Multi-index notation-->
<h3 class="subsection" id="ss:multiindexing"><a class="section-anchor" href="#ss:multiindexing" aria-hidden="true"></a>8.19.1  Multi-index notation</h3><!--SEC END --><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.</span>  [<a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span>]  <a class="syntax" href="#dot-ext"><span class="c010">dot-ext</span></a> <span class="c004">(</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>  {<span class="c004">;</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> }<sup>+</sup> <span class="c004">)</span>  [ <span class="c004">&lt;-</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> ]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.</span>  [<a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span>]  <a class="syntax" href="#dot-ext"><span class="c010">dot-ext</span></a> <span class="c004">[</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>  {<span class="c004">;</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> }<sup>+</sup> <span class="c004">]</span>  [ <span class="c004">&lt;-</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> ]
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">.</span>  [<a class="syntax" href="#module-path"><span class="c010">module-path</span></a> <span class="c004">.</span>]  <a class="syntax" href="#dot-ext"><span class="c010">dot-ext</span></a> <span class="c004">{</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>  {<span class="c004">;</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> }<sup>+</sup> <span class="c004">}</span>  [ <span class="c004">&lt;-</span> <a class="syntax" href="#expr"><span class="c010">expr</span></a> ]
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">operator-name</span></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">.</span> <a class="syntax" href="#dot-ext"><span class="c010">dot-ext</span></a>  (<span class="c004">(;..)</span> ∣  <span class="c004">[;..]</span> ∣  <span class="c004">{;..}</span>) [<span class="c004">&lt;-</span>]
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>Multi-index are also supported through a second variant of indexing operators</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> (.%[;..]) = Bigarray.Genarray.get
 <span class="ocamlkeyword">let</span> (.%{;..}) = Bigarray.Genarray.get
 <span class="ocamlkeyword">let</span> (.%(;..)) = Bigarray.Genarray.get</div></div>

</div><p>which is called when an index literals contain a semicolon separated list
of expressions with two and more elements:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> sum x y = x.%[1;2;3] + y.%[1;2]
 <span class="ocamlcomment">(* is equivalent to *)</span>
 <span class="ocamlkeyword">let</span> sum x y = (.%[;..]) x [|1;2;3|] + (.%[;..]) y [|1;2|]</div></div>

</div><p>In particular this multi-index notation makes it possible to uniformly handle
indexing Genarray and other implementations of multidimensional arrays.</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> A = Bigarray.Genarray
 <span class="ocamlkeyword">let</span> (.%{;..}) = A.get
 <span class="ocamlkeyword">let</span> (.%{;..}&lt;- ) = A.set
 <span class="ocamlkeyword">let</span> (.%{ }) a k = A.get a [|k|]
 <span class="ocamlkeyword">let</span> (.%{ }&lt;-) a k x = A.set a [|k|] x
 <span class="ocamlkeyword">let</span> syntax_compare vec mat t3 t4 =
           vec.%{0} = A.get vec [|0|]
    &amp;&amp;   mat.%{0;0} = A.get mat [|0;0|]
    &amp;&amp;   t3.%{0;0;0} = A.get t3 [|0;0;0|]
    &amp;&amp; t4.%{0;0;0;0} = t4.{0,0,0,0}</div></div>

</div>
<!--TOC section id="s:empty-variants" 8.20  Empty variant types-->
<h2 class="section" id="s:empty-variants"><a class="section-anchor" href="#s:empty-variants" aria-hidden="true"></a>8.20  Empty variant types</h2><!--SEC END --><!--NAME emptyvariants.html-->
<p>
(Introduced in 4.07.0)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#type-representation"><span class="c010">type-representation</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">=</span> <span class="c004">|</span>
</td></tr>
</table></td></tr>
</table></div><p>
This extension allows user to define empty variants.
Empty variant type can be eliminated by refutation case of pattern matching.


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">type</span> t = |
 <span class="ocamlkeyword">let</span> f (x: t) = <span class="ocamlkeyword">match</span> x <span class="ocamlkeyword">with</span> _ -&gt; .</div></div>

</div>
<!--TOC section id="s:alerts" 8.21  Alerts-->
<h2 class="section" id="s:alerts"><a class="section-anchor" href="#s:alerts" aria-hidden="true"></a>8.21  Alerts</h2><!--SEC END --><!--NAME alerts.html-->
<p>
(Introduced in 4.08)</p><p>Since OCaml 4.08, it is possible to mark components (such as value or
type declarations) in signatures with “alerts” that will be reported
when those components are referenced. This generalizes the notion of
“deprecated” components which were previously reported as warning 3.
Those alerts can be used for instance to report usage of unsafe
features, or of features which are only available on some platforms,
etc.</p><p>Alert categories are identified by a symbolic identifier (a lowercase
identifier, following the usual lexical rules) and an optional
message. The identifier is used to control which alerts are enabled,
and which ones are turned into fatal errors. The message is reported
to the user when the alert is triggered (i.e. when the marked
component is referenced).</p><p>The <span class="c003">ocaml.alert</span> or <span class="c003">alert</span> attribute serves two purposes: (i) to
mark component with an alert to be triggered when the component is
referenced, and (ii) to control which alert names are enabled. In the
first form, the attribute takes an identifier possibly
followed by a message. Here is an example of a value declaration marked
with an alert:</p><pre>module U: sig
  val fork: unit -&gt; bool
    [@@alert unix "This function is only available under Unix."]
end
</pre><p>
Here <span class="c003">unix</span> is the identifier for the alert. If this alert category
is enabled, any reference to <span class="c003">U.fork</span> will produce a message at
compile time, which can be turned or not into a fatal error.</p><p>And here is another example as a floating attribute on top
of an “.mli” file (i.e. before any other non-attribute item)
or on top of an “.ml” file without a corresponding interface file,
so that any reference to that unit will trigger the alert:</p><pre>[@@@alert unsafe "This module is unsafe!"]
</pre><p>Controlling which alerts are enabled and whether they are turned into
fatal errors is done either through the compiler’s command-line option
<span class="c003">-alert &lt;spec&gt;</span> or locally in the code through the <span class="c003">alert</span> or
<span class="c003">ocaml.alert</span> attribute taking a single string payload <span class="c003">&lt;spec&gt;</span>. In
both cases, the syntax for <span class="c003">&lt;spec&gt;</span> is a concatenation of items of the
form:</p><ul class="itemize"><li class="li-itemize">
<span class="c003">+id</span> enables alert <span class="c003">id</span>.
</li><li class="li-itemize"><span class="c003">-id</span> disables alert <span class="c003">id</span>.
</li><li class="li-itemize"><span class="c003">++id</span> turns alert <span class="c003">id</span> into a fatal error.
</li><li class="li-itemize"><span class="c003">--id</span> turns alert <span class="c003">id</span> into non-fatal mode.
</li><li class="li-itemize"><span class="c003">@id</span> equivalent to <span class="c003">++id+id</span> (enables <span class="c003">id</span> and turns it into a fatal-error)
</li></ul><p>As a special case, if <span class="c003">id</span> is <span class="c003">all</span>, it stands for all alerts.</p><p>Here are some examples:</p><pre>
(* Disable all alerts, reenables just unix (as a soft alert) and window
   (as a fatal-error), for the rest of the current structure *)

[@@@alert "-all--all+unix@window"]
 ...

let x =
  (* Locally disable the window alert *)
  begin[@alert "-window"]
      ...
  end
</pre><p>
Before OCaml 4.08, there was support for a single kind of deprecation
alert. It is now known as the <span class="c003">deprecated</span> alert, but legacy
attributes to trigger it and the legacy ways to control it as warning
3 are still supported. For instance, passing <span class="c003">-w +3</span> on the
command-line is equivant to <span class="c003">-alert +deprecated</span>, and:</p><pre>val x: int
  [@@@ocaml.deprecated "Please do something else"]
</pre><p>
is equivalent to:</p><pre>val x: int
  [@@@ocaml.alert deprecated "Please do something else"]
</pre>
<!--TOC section id="s:generalized-open" 8.22  Generalized open statements-->
<h2 class="section" id="s:generalized-open"><a class="section-anchor" href="#s:generalized-open" aria-hidden="true"></a>8.22  Generalized open statements</h2><!--SEC END --><!--NAME generalizedopens.html-->
<p>(Introduced in 4.08)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#definition"><span class="c010">definition</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">open</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">open!</span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#specification"><span class="c010">specification</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">open</span>  <a class="syntax" href="#extended-module-path"><span class="c010">extended-module-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017">  <span class="c004">open!</span> <a class="syntax" href="#extended-module-path"><span class="c010">extended-module-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">let</span> <span class="c004">open</span>  <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">let</span> <span class="c004">open!</span> <a class="syntax" href="#module-expr"><span class="c010">module-expr</span></a> <span class="c004">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>This extension makes it possible to open any module expression in
module structures and expressions. A similar mechanism is also available
inside module types, but only for extended module paths (e.g. <span class="c003">F(X).G(Y)</span>).</p><p>For instance, a module can be constrained when opened with</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> M = <span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">let</span> x = 0 <span class="ocamlkeyword">let</span> hidden = 1 <span class="ocamlkeyword">end</span>
 <span class="ocamlkeyword">open</span> (M:<span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">val</span> x: int <span class="ocamlkeyword">end</span>)
 <span class="ocamlkeyword">let</span> y = <span class="ocamlhighlight">hidden</span></div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: Unbound value hidden</div></div>

</div><p>Another possibility is to immediately open the result of a functor application</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input">   <span class="ocamlkeyword">let</span> sort (<span class="ocamlkeyword">type</span> x) (x:x list) =
     <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">open</span> Set.Make(<span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">type</span> t = x <span class="ocamlkeyword">let</span> compare=compare <span class="ocamlkeyword">end</span>) <span class="ocamlkeyword">in</span>
     elements (of_list x)</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> sort : 'x list -&gt; 'x list = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>Going further, this construction can introduce local components inside a
structure,</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> M = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">let</span> x = 0
   <span class="ocamlkeyword">open</span>! <span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">let</span> x = 0
     <span class="ocamlkeyword">let</span> y = 1
   <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">let</span> w = x + y
 <span class="ocamlkeyword">end</span></div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> M : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">val</span> x : int <span class="ocamlkeyword">val</span> w : int <span class="ocamlkeyword">end</span></div></div>

</div><p>One important restriction is that types introduced by <span class="c002"><span class="c003">open</span> <span class="c003">struct</span></span> ...
<span class="c004">end</span> cannot appear in the signature of the enclosing structure, unless they
are defined equal to some non-local type.
So:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> M = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">open</span> <span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">type</span> 'a t = 'a option = None | Some <span class="ocamlkeyword">of</span> 'a <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">let</span> x : int t = Some 1
 <span class="ocamlkeyword">end</span></div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> M : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">val</span> x : int option <span class="ocamlkeyword">end</span></div></div>

</div><p>


is OK, but:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> M = <span class="ocamlkeyword">struct</span>
   <span class="ocamlhighlight">open struct type t = A end</span>
   <span class="ocamlkeyword">let</span> x = A
 <span class="ocamlkeyword">end</span></div>



<div class="pre caml-output error"><span class="ocamlerror">Error</span>: The type t/4502 introduced by this open appears in the signature
       File "exten.etex", line 3, characters 6-7:
         The value x has no valid type if t/4502 is hidden</div></div>

</div><p>


is not because <span class="c003">x</span> cannot be given any type other than <span class="c003">t</span>, which only exists
locally. Although the above would be OK if <span class="c003">x</span> too was local:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> M: <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">end</span> = <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">open</span> <span class="ocamlkeyword">struct</span>
   <span class="ocamlkeyword">type</span> t = A
   <span class="ocamlkeyword">end</span>
   …
   <span class="ocamlkeyword">open</span> <span class="ocamlkeyword">struct</span> <span class="ocamlkeyword">let</span> x = A <span class="ocamlkeyword">end</span>
   …
 <span class="ocamlkeyword">end</span></div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> M : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">end</span></div></div>

</div><p>Inside signatures, extended opens are limited to extended module paths,


</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> S = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">module</span> F: <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">end</span> -&gt; <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> t <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">module</span> X: <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">open</span> F(X)
   <span class="ocamlkeyword">val</span> f: t
 <span class="ocamlkeyword">end</span></div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> S =
  <span class="ocamlkeyword">sig</span>
    <span class="ocamlkeyword">module</span> F : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">end</span> -&gt; <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">type</span> t <span class="ocamlkeyword">end</span>
    <span class="ocamlkeyword">module</span> X : <span class="ocamlkeyword">sig</span> <span class="ocamlkeyword">end</span>
    <span class="ocamlkeyword">val</span> f : F(X).t
  <span class="ocamlkeyword">end</span></div></div>

</div><p>and not</p><pre>  open struct type t = int end
</pre><p>
In those situations, local substitutions(see <a href="#ss%3Alocal-substitution">8.7.2</a>)
can be used instead.</p><p>Beware that this extension is not available inside class definitions:</p><pre>class c =
  let open Set.Make(Int) in
  ...
</pre>
<!--TOC section id="s:binding-operators" 8.23  Binding operators-->
<h2 class="section" id="s:binding-operators"><a class="section-anchor" href="#s:binding-operators" aria-hidden="true"></a>8.23  Binding operators</h2><!--SEC END --><!--NAME bindingops.html-->
<p>
(Introduced in 4.08.0)</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="let-operator"><span class="c010">let-operator</span></a></td><td class="c015">::=</td><td class="c017">
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">let</span> (<a class="syntax" href="#core-operator-char"><span class="c010">core-operator-char</span></a> ∣  <span class="c004">&lt;</span>) { <a class="syntax" href="#dot-operator-char"><span class="c010">dot-operator-char</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="and-operator"><span class="c010">and-operator</span></a></td><td class="c015">::=</td><td class="c017">
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">and</span> (<a class="syntax" href="#core-operator-char"><span class="c010">core-operator-char</span></a> ∣  <span class="c004">&lt;</span>) { <a class="syntax" href="#dot-operator-char"><span class="c010">dot-operator-char</span></a> }
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<span class="c010">operator-name</span> </td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#let-operator"><span class="c010">let-operator</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#and-operator"><span class="c010">and-operator</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" href="#expr"><span class="c010">expr</span></a></td><td class="c015">::=</td><td class="c017">
...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#let-operator"><span class="c010">let-operator</span></a>  <a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a>  { <a class="syntax" href="#and-operator"><span class="c010">and-operator</span></a>  <a class="syntax" href="#let-binding"><span class="c010">let-binding</span></a> }  <span class="c010">in</span>  <a class="syntax" href="#expr"><span class="c010">expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><p>Users can define <em>let operators</em>:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> ( <span class="ocamlkeyword">let</span>* ) o f =
   <span class="ocamlkeyword">match</span> o <span class="ocamlkeyword">with</span>
   | None -&gt; None
   | Some x -&gt; f x

 <span class="ocamlkeyword">let</span> return x = Some x</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> ( <span class="ocamlkeyword">let</span>* ) : 'a option -&gt; ('a -&gt; 'b option) -&gt; 'b option = &lt;<span class="ocamlkeyword">fun</span>&gt;
<span class="ocamlkeyword">val</span> return : 'a -&gt; 'a option = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>and then apply them using this convenient syntax:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> find_and_sum tbl k1 k2 =
   <span class="ocamlkeyword">let</span>* x1 = Hashtbl.find_opt tbl k1 <span class="ocamlkeyword">in</span>
   <span class="ocamlkeyword">let</span>* x2 = Hashtbl.find_opt tbl k2 <span class="ocamlkeyword">in</span>
     return (x1 + x2)</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> find_and_sum : ('a, int) Hashtbl.t -&gt; 'a -&gt; 'a -&gt; int option = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>which is equivalent to this expanded form:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">let</span> find_and_sum tbl k1 k2 =
   ( <span class="ocamlkeyword">let</span>* ) (Hashtbl.find_opt tbl k1)
     (<span class="ocamlkeyword">fun</span> x1 -&gt;
        ( <span class="ocamlkeyword">let</span>* ) (Hashtbl.find_opt tbl k2)
          (<span class="ocamlkeyword">fun</span> x2 -&gt; return (x1 + x2)))</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> find_and_sum : ('a, int) Hashtbl.t -&gt; 'a -&gt; 'a -&gt; int option = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>Users can also define <em>and operators</em>:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> ZipSeq = <span class="ocamlkeyword">struct</span>

   <span class="ocamlkeyword">type</span> 'a t = 'a Seq.t

   <span class="ocamlkeyword">open</span> Seq

   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> return x =
     <span class="ocamlkeyword">fun</span> () -&gt; Cons(x, return x)

   <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> prod a b =
     <span class="ocamlkeyword">fun</span> () -&gt;
       <span class="ocamlkeyword">match</span> a (), b () <span class="ocamlkeyword">with</span>
       | Nil, _ | _, Nil -&gt; Nil
       | Cons(x, a), Cons(y, b) -&gt; Cons((x, y), prod a b)

   <span class="ocamlkeyword">let</span> ( <span class="ocamlkeyword">let</span>+ ) f s = map s f
   <span class="ocamlkeyword">let</span> ( <span class="ocamlkeyword">and</span>+ ) a b = prod a b

 <span class="ocamlkeyword">end</span></div>



<div class="pre caml-output ok"><span class="ocamlkeyword">module</span> ZipSeq :
  <span class="ocamlkeyword">sig</span>
    <span class="ocamlkeyword">type</span> 'a t = 'a Seq.t
    <span class="ocamlkeyword">val</span> return : 'a -&gt; 'a Seq.t
    <span class="ocamlkeyword">val</span> prod : 'a Seq.t -&gt; 'b Seq.t -&gt; ('a * 'b) Seq.t
    <span class="ocamlkeyword">val</span> ( <span class="ocamlkeyword">let</span>+ ) : 'a Seq.t -&gt; ('a -&gt; 'b) -&gt; 'b Seq.t
    <span class="ocamlkeyword">val</span> ( <span class="ocamlkeyword">and</span>+ ) : 'a Seq.t -&gt; 'b Seq.t -&gt; ('a * 'b) Seq.t
  <span class="ocamlkeyword">end</span></div></div>

</div><p>to support the syntax:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">open</span> ZipSeq
 <span class="ocamlkeyword">let</span> sum3 z1 z2 z3 =
   <span class="ocamlkeyword">let</span>+ x1 = z1
   <span class="ocamlkeyword">and</span>+ x2 = z2
   <span class="ocamlkeyword">and</span>+ x3 = z3 <span class="ocamlkeyword">in</span>
     x1 + x2 + x3</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> sum3 : int Seq.t -&gt; int Seq.t -&gt; int Seq.t -&gt; int Seq.t = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div><p>which is equivalent to this expanded form:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">open</span> ZipSeq
 <span class="ocamlkeyword">let</span> sum3 z1 z2 z3 =
   ( <span class="ocamlkeyword">let</span>+ ) (( <span class="ocamlkeyword">and</span>+ ) (( <span class="ocamlkeyword">and</span>+ ) z1 z2) z3)
     (<span class="ocamlkeyword">fun</span> ((x1, x2), x3) -&gt; x1 + x2 + x3)</div>



<div class="pre caml-output ok"><span class="ocamlkeyword">val</span> sum3 : int Seq.t -&gt; int Seq.t -&gt; int Seq.t -&gt; int Seq.t = &lt;<span class="ocamlkeyword">fun</span>&gt;</div></div>

</div>
<!--TOC subsection id="ss:letops-rationale" 8.23.1  Rationale-->
<h3 class="subsection" id="ss:letops-rationale"><a class="section-anchor" href="#ss:letops-rationale" aria-hidden="true"></a>8.23.1  Rationale</h3><!--SEC END --><p>This extension is intended to provide a convenient syntax for working
with monads and applicatives.</p><p>An applicative should provide a module implementing the following
interface:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> Applicative_syntax = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">type</span> 'a t
   <span class="ocamlkeyword">val</span> ( <span class="ocamlkeyword">let</span>+ ) : 'a t -&gt; ('a -&gt; 'b) -&gt; 'b t
   <span class="ocamlkeyword">val</span> ( <span class="ocamlkeyword">and</span>+ ): 'a t -&gt; 'b t -&gt; ('a * 'b) t
 <span class="ocamlkeyword">end</span></div></div>

</div><p>where <span class="c003">(let+)</span> is bound to the <span class="c003">map</span> operation and <span class="c003">(and+)</span> is bound to
the monoidal product operation.</p><p>A monad should provide a module implementing the following interface:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> Monad_syntax = <span class="ocamlkeyword">sig</span>
   <span class="ocamlkeyword">include</span> Applicative_syntax
   <span class="ocamlkeyword">val</span> ( <span class="ocamlkeyword">let</span>* ) : 'a t -&gt; ('a -&gt; 'b t) -&gt; 'b t
   <span class="ocamlkeyword">val</span> ( <span class="ocamlkeyword">and</span>* ): 'a t -&gt; 'b t -&gt; ('a * 'b) t
 <span class="ocamlkeyword">end</span></div></div>

</div><p>where <span class="c003">(let*)</span> is bound to the <span class="c003">bind</span> operation, and <span class="c003">(and*)</span> is also
bound to the monoidal product operation.</p><!--CUT END -->

<!--TOC part id="sec286" Part III  The OCaml tools-->
<table class="center"><tr><td><h1 class="part" id="sec286">Part III<br>
The OCaml tools</h1></td></tr>
</table><!--SEC END --><p>
<a id="p:commands"></a></p>
<!--TOC chapter id="sec287" Chapter 9  Batch compilation (ocamlc)-->
<h1 class="chapter" id="sec287">Chapter 9  Batch compilation (ocamlc)</h1><!--SEC END --><p> <a id="c:camlc"></a>
</p><!--NAME comp.html-->
<p>This chapter describes the OCaml batch compiler <span class="c003">ocamlc</span>,
which compiles OCaml source files to bytecode object files and links
these object files to produce standalone bytecode executable files.
These executable files are then run by the bytecode interpreter
<span class="c003">ocamlrun</span>.</p>
<!--TOC section id="s:comp-overview" 9.1  Overview of the compiler-->
<h2 class="section" id="s:comp-overview"><a class="section-anchor" href="#s:comp-overview" aria-hidden="true"></a>9.1  Overview of the compiler</h2><!--SEC END --><p>The <span class="c003">ocamlc</span> command has a command-line interface similar to the one of
most C compilers. It accepts several types of arguments and processes them
sequentially, after all options have been processed:</p><ul class="itemize"><li class="li-itemize">
Arguments ending in <span class="c003">.mli</span> are taken to be source files for
compilation unit interfaces. Interfaces specify the names exported by
compilation units: they declare value names with their types, define
public data types, declare abstract data types, and so on. From the
file <span class="c009">x</span><span class="c003">.mli</span>, the <span class="c003">ocamlc</span> compiler produces a compiled interface
in the file <span class="c009">x</span><span class="c003">.cmi</span>.</li><li class="li-itemize">Arguments ending in <span class="c003">.ml</span> are taken to be source files for compilation
unit implementations. Implementations provide definitions for the
names exported by the unit, and also contain expressions to be
evaluated for their side-effects. From the file <span class="c009">x</span><span class="c003">.ml</span>, the <span class="c003">ocamlc</span>
compiler produces compiled object bytecode in the file <span class="c009">x</span><span class="c003">.cmo</span>.<p>If the interface file <span class="c009">x</span><span class="c003">.mli</span> exists, the implementation
<span class="c009">x</span><span class="c003">.ml</span> is checked against the corresponding compiled interface
<span class="c009">x</span><span class="c003">.cmi</span>, which is assumed to exist. If no interface
<span class="c009">x</span><span class="c003">.mli</span> is provided, the compilation of <span class="c009">x</span><span class="c003">.ml</span> produces a
compiled interface file <span class="c009">x</span><span class="c003">.cmi</span> in addition to the compiled
object code file <span class="c009">x</span><span class="c003">.cmo</span>. The file <span class="c009">x</span><span class="c003">.cmi</span> produced
corresponds to an interface that exports everything that is defined in
the implementation <span class="c009">x</span><span class="c003">.ml</span>.</p></li><li class="li-itemize">Arguments ending in <span class="c003">.cmo</span> are taken to be compiled object bytecode. These
files are linked together, along with the object files obtained
by compiling <span class="c003">.ml</span> arguments (if any), and the OCaml standard
library, to produce a standalone executable program. The order in
which <span class="c003">.cmo</span> and <span class="c003">.ml</span> arguments are presented on the command line is
relevant: compilation units are initialized in that order at
run-time, and it is a link-time error to use a component of a unit
before having initialized it. Hence, a given <span class="c009">x</span><span class="c003">.cmo</span> file must come
before all <span class="c003">.cmo</span> files that refer to the unit <span class="c009">x</span>.</li><li class="li-itemize">Arguments ending in <span class="c003">.cma</span> are taken to be libraries of object bytecode.
A library of object bytecode packs in a single file a set of object
bytecode files (<span class="c003">.cmo</span> files). Libraries are built with <span class="c003">ocamlc -a</span>
(see the description of the <span class="c003">-a</span> option below). The object files
contained in the library are linked as regular <span class="c003">.cmo</span> files (see
above), in the order specified when the <span class="c003">.cma</span> file was built. The
only difference is that if an object file contained in a library is
not referenced anywhere in the program, then it is not linked in.</li><li class="li-itemize">Arguments ending in <span class="c003">.c</span> are passed to the C compiler, which generates
a <span class="c003">.o</span> object file (<span class="c003">.obj</span> under Windows). This object file is linked
with the program if the <span class="c003">-custom</span> flag is set (see the description of
<span class="c003">-custom</span> below).</li><li class="li-itemize">Arguments ending in <span class="c003">.o</span> or <span class="c003">.a</span> (<span class="c003">.obj</span> or <span class="c003">.lib</span> under Windows)
are assumed to be C object files and libraries. They are passed to the
C linker when linking in <span class="c003">-custom</span> mode (see the description of
<span class="c003">-custom</span> below).</li><li class="li-itemize">Arguments ending in <span class="c003">.so</span> (<span class="c003">.dll</span> under Windows)
are assumed to be C shared libraries (DLLs). During linking, they are
searched for external C functions referenced from the OCaml code,
and their names are written in the generated bytecode executable.
The run-time system <span class="c003">ocamlrun</span> then loads them dynamically at program
start-up time.</li></ul><p>The output of the linking phase is a file containing compiled bytecode
that can be executed by the OCaml bytecode interpreter:
the command named <span class="c003">ocamlrun</span>. If <span class="c003">a.out</span> is the name of the file
produced by the linking phase, the command
</p><pre>
        ocamlrun a.out <span class="c009">arg</span><sub>1</sub> <span class="c009">arg</span><sub>2</sub> … <span class="c009">arg</span><sub><span class="c009">n</span></sub>
</pre><p>
executes the compiled code contained in <span class="c003">a.out</span>, passing it as
arguments the character strings <span class="c009">arg</span><sub>1</sub> to <span class="c009">arg</span><sub><span class="c009">n</span></sub>.
(See chapter <a href="#c%3Aruntime">11</a> for more details.)</p><p>On most systems, the file produced by the linking
phase can be run directly, as in:
</p><pre>
        ./a.out <span class="c009">arg</span><sub>1</sub> <span class="c009">arg</span><sub>2</sub> … <span class="c009">arg</span><sub><span class="c009">n</span></sub>
</pre><p>
The produced file has the executable bit set, and it manages to launch
the bytecode interpreter by itself.</p><p>The compiler is able to emit some information on its internal stages.
It can output <span class="c003">.cmt</span> files for the implementation of the compilation unit
and <span class="c003">.cmti</span> for signatures if the option <span class="c003">-bin-annot</span> is passed to it (see the
description of <span class="c003">-bin-annot</span> below).
Each such file contains a typed abstract syntax tree (AST), that is produced
during the type checking procedure. This tree contains all available information
about the location and the specific type of each term in the source file.
The AST is partial if type checking was unsuccessful.</p><p>These <span class="c003">.cmt</span> and <span class="c003">.cmti</span> files are typically useful for code inspection tools.</p>
<!--TOC section id="s:comp-options" 9.2  Options-->
<h2 class="section" id="s:comp-options"><a class="section-anchor" href="#s:comp-options" aria-hidden="true"></a>9.2  Options</h2><!--SEC END --><p>The following command-line options are recognized by <span class="c003">ocamlc</span>.
The options <span class="c003">-pack</span>, <span class="c003">-a</span>, <span class="c003">-c</span> and <span class="c003">-output-obj</span> are mutually exclusive.
</p><dl class="description"><dt class="dt-description">
<span class="c006">-a</span></dt><dd class="dd-description">
Build a library(<span class="c003">.cma</span> file)
with the object files ( <span class="c003">.cmo</span> files)
given on the command line, instead of linking them into an executable file.
The name of the library must be set with the <span class="c003">-o</span> option.<p>If <span class="c003">-custom</span>, <span class="c003">-cclib</span> or <span class="c003">-ccopt</span> options are passed on the command
line, these options are stored in the resulting <span class="c003">.cma</span>library. Then,
linking with this library automatically adds back the <span class="c003">-custom</span>, 
<span class="c003">-cclib</span> and <span class="c003">-ccopt</span> options as if they had been provided on the
command line, unless the <span class="c003">-noautolink</span> option is given.
</p></dd><dt class="dt-description"><span class="c006">-absname</span></dt><dd class="dd-description">
Force error messages to show absolute paths for file names.</dd><dt class="dt-description"><span class="c006">-annot</span></dt><dd class="dd-description">
Deprecated since OCaml 4.11. Please use <span class="c003">-bin-annot</span> instead.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-args</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Read additional newline-terminated command line arguments from <span class="c009">filename</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-args0</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Read additional null character terminated command line arguments from
<span class="c009">filename</span>.
</dd><dt class="dt-description"><span class="c006">-bin-annot</span></dt><dd class="dd-description">
Dump detailed information about the compilation (types, bindings,
tail-calls, etc) in binary format. The information for file <span class="c009">src</span><span class="c003">.ml</span>
(resp. <span class="c009">src</span><span class="c003">.mli</span>) is put into file <span class="c009">src</span><span class="c003">.cmt</span>
(resp. <span class="c009">src</span><span class="c003">.cmti</span>). In case of a type error, dump
all the information inferred by the type-checker before the error.
The <span class="c003">*.cmt</span> and <span class="c003">*.cmti</span> files produced by <span class="c003">-bin-annot</span> contain
more information and are much more compact than the files produced by
<span class="c003">-annot</span>.
</dd><dt class="dt-description"><span class="c006">-c</span></dt><dd class="dd-description">
Compile only. Suppress the linking phase of the
compilation. Source code files are turned into compiled files, but no
executable file is produced. This option is useful to
compile modules separately.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-cc</span> <span class="c009">ccomp</span></span></dt><dd class="dd-description">
Use <span class="c009">ccomp</span> as the C linker 
when linking in “custom runtime” mode (see the <span class="c003">-custom</span> option)
and as the C compiler for compiling <span class="c003">.c</span> source files.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-cclib</span> <span class="c003">-l</span><span class="c009">libname</span></span></dt><dd class="dd-description">
Pass the <span class="c003">-l</span><span class="c009">libname</span> option to the C linker
when linking in “custom runtime” mode (see the <span class="c003">-custom</span> option).
This causes the given C library to be linked with the program.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-ccopt</span> <span class="c009">option</span></span></dt><dd class="dd-description">
Pass the given option to the C compiler and linker.
When linking in “custom runtime” mode, for instance<span class="c003">-ccopt -L</span><span class="c009">dir</span> causes the C linker to search for C libraries in
directory <span class="c009">dir</span>.(See the <span class="c003">-custom</span> option.)
</dd><dt class="dt-description"><span class="c013"><span class="c003">-color</span> <span class="c009">mode</span></span></dt><dd class="dd-description">
Enable or disable colors in compiler messages (especially warnings and errors).
The following modes are supported:
<dl class="description"><dt class="dt-description">
<span class="c006">auto</span></dt><dd class="dd-description"> use heuristics to enable colors only if the output supports them
(an ANSI-compatible tty terminal);
</dd><dt class="dt-description"><span class="c006">always</span></dt><dd class="dd-description"> enable colors unconditionally;
</dd><dt class="dt-description"><span class="c006">never</span></dt><dd class="dd-description"> disable color output.
</dd></dl>
The default setting is ’auto’, and the current heuristic
checks that the <span class="c003">TERM</span> environment variable exists and is
not empty or <span class="c003">dumb</span>, and that ’isatty(stderr)’ holds.<p>The environment variable <span class="c003">OCAML_COLOR</span> is considered if <span class="c003">-color</span> is not
provided. Its values are auto/always/never as above.
</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-error-style</span> <span class="c009">mode</span></span></dt><dd class="dd-description">
Control the way error messages and warnings are printed.
The following modes are supported:
<dl class="description"><dt class="dt-description">
<span class="c006">short</span></dt><dd class="dd-description"> only print the error and its location;
</dd><dt class="dt-description"><span class="c006">contextual</span></dt><dd class="dd-description"> like <span class="c003">short</span>, but also display the source code snippet
corresponding to the location of the error.
</dd></dl>
The default setting is <span class="c003">contextual</span>.<p>The environment variable <span class="c003">OCAML_ERROR_STYLE</span> is considered if <span class="c003">-error-style</span> is
not provided. Its values are short/contextual as above.
</p></dd><dt class="dt-description"><span class="c006">-compat-32</span></dt><dd class="dd-description">
Check that the generated bytecode executable can run on 32-bit
platforms and signal an error if it cannot. This is useful when
compiling bytecode on a 64-bit machine.
</dd><dt class="dt-description"><span class="c006">-config</span></dt><dd class="dd-description">
Print the version number of <span class="c003">ocamlc</span> and a detailed
summary of its configuration, then exit.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-config-var</span> <span class="c009">var</span></span></dt><dd class="dd-description">
Print the value of a specific configuration variable from the
<span class="c003">-config</span> output, then exit. If the variable does not exist, the exit
code is non-zero. This option is only available since OCaml 4.08,
so script authors should have a fallback for older versions.
</dd><dt class="dt-description"><span class="c006">-custom</span></dt><dd class="dd-description">
Link in “custom runtime” mode. In the default linking mode, the
linker produces bytecode that is intended to be executed with the
shared runtime system, <span class="c003">ocamlrun</span>. In the custom runtime mode, the
linker produces an output file that contains both the runtime system
and the bytecode for the program. The resulting file is larger, but it
can be executed directly, even if the <span class="c003">ocamlrun</span> command is not
installed. Moreover, the “custom runtime” mode enables static
linking of OCaml code with user-defined C functions, as described in
chapter <a href="#c%3Aintf-c">20</a>.
<blockquote class="quote"><span class="c007">Unix:</span>  
Never use the <span class="c003">strip</span> command on executables produced by <span class="c003">ocamlc -custom</span>,
this would remove the bytecode part of the executable.
</blockquote>
<blockquote class="quote"><span class="c007">Unix:</span>  
Security warning: never set the “setuid” or “setgid” bits on executables
produced by <span class="c003">ocamlc -custom</span>, this would make them vulnerable to attacks.
</blockquote>
</dd><dt class="dt-description"><span class="c013"><span class="c003">-depend</span> <span class="c009">ocamldep-args</span></span></dt><dd class="dd-description">
Compute dependencies, as the <span class="c003">ocamldep</span> command would do. The remaining
arguments are interpreted as if they were given to the <span class="c003">ocamldep</span> command.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-dllib</span> <span class="c003">-l</span><span class="c009">libname</span></span></dt><dd class="dd-description">
Arrange for the C shared library <span class="c003">dll</span><span class="c009">libname</span><span class="c003">.so</span>
(<span class="c003">dll</span><span class="c009">libname</span><span class="c003">.dll</span> under Windows) to be loaded dynamically
by the run-time system <span class="c003">ocamlrun</span> at program start-up time.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-dllpath</span> <span class="c009">dir</span></span></dt><dd class="dd-description">
Adds the directory <span class="c009">dir</span> to the run-time search path for shared
C libraries. At link-time, shared libraries are searched in the
standard search path (the one corresponding to the <span class="c003">-I</span> option).
The <span class="c003">-dllpath</span> option simply stores <span class="c009">dir</span> in the produced
executable file, where <span class="c003">ocamlrun</span> can find it and use it as
described in section <a href="#s%3Aocamlrun-dllpath">11.3</a>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-for-pack</span> <span class="c009">module-path</span></span></dt><dd class="dd-description">
Generate an object file (<span class="c003">.cmo</span>)
that can later be included
as a sub-module (with the given access path) of a compilation unit
constructed with <span class="c003">-pack</span>. For instance,
<span class="c003">ocamlc -for-pack P -c A.ml</span>
will generate <span class="c003">a..cmo</span> that can
later be used with <span class="c003">ocamlc -pack -o P.cmo a.cmo</span>.
Note: you can still pack a module that was compiled without
<span class="c003">-for-pack</span> but in this case exceptions will be printed with the wrong
names.
</dd><dt class="dt-description"><span class="c006">-g</span></dt><dd class="dd-description">
Add debugging information while compiling and linking. This option is
required in order to be able to debug the program with <span class="c003">ocamldebug</span>
(see chapter <a href="#c%3Adebugger">17</a>), and to produce stack backtraces when
the program terminates on an uncaught exception (see
section <a href="#s%3Aocamlrun-options">11.2</a>).
</dd><dt class="dt-description"><span class="c006">-i</span></dt><dd class="dd-description">
Cause the compiler to print all defined names (with their inferred
types or their definitions) when compiling an implementation (<span class="c003">.ml</span>
file). No compiled files (<span class="c003">.cmo</span> and <span class="c003">.cmi</span> files) are produced.
This can be useful to check the types inferred by the
compiler. Also, since the output follows the syntax of interfaces, it
can help in writing an explicit interface (<span class="c003">.mli</span> file) for a file:
just redirect the standard output of the compiler to a <span class="c003">.mli</span> file,
and edit that file to remove all declarations of unexported names.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-I</span> <span class="c009">directory</span></span></dt><dd class="dd-description">
Add the given directory to the list of directories searched for

compiled interface files (<span class="c003">.cmi</span>), compiled object code files <span class="c003">.cmo</span>,
libraries (<span class="c003">.cma</span>) and C libraries specified with <span class="c003">-cclib -lxxx</span>.

By default, the current directory is searched first, then the standard
library directory. Directories added with <span class="c003">-I</span> are searched after the
current directory, in the order in which they were given on the command line,
but before the standard library directory. See also option <span class="c003">-nostdlib</span>.<p>If the given directory starts with <span class="c003">+</span>, it is taken relative to the
standard library directory. For instance, <span class="c003">-I +unix</span> adds the
subdirectory <span class="c003">unix</span> of the standard library to the search path.</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-impl</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Compile the file <span class="c009">filename</span> as an implementation file, even if its
extension is not <span class="c003">.ml</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-intf</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Compile the file <span class="c009">filename</span> as an interface file, even if its
extension is not <span class="c003">.mli</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-intf-suffix</span> <span class="c009">string</span></span></dt><dd class="dd-description">
Recognize file names ending with <span class="c009">string</span> as interface files
(instead of the default <span class="c003">.mli</span>).
</dd><dt class="dt-description"><span class="c006">-labels</span></dt><dd class="dd-description">
Labels are not ignored in types, labels may be used in applications,
and labelled parameters can be given in any order. This is the default.</dd><dt class="dt-description"><span class="c006">-linkall</span></dt><dd class="dd-description">
Force all modules contained in libraries to be linked in. If this
flag is not given, unreferenced modules are not linked in. When
building a library (option <span class="c003">-a</span>), setting the <span class="c003">-linkall</span> option forces all
subsequent links of programs involving that library to link all the
modules contained in the library. When compiling a module (option
<span class="c003">-c</span>), setting the <span class="c003">-linkall</span> option ensures that this module will
always be linked if it is put in a library and this library is linked.
</dd><dt class="dt-description"><span class="c006">-make-runtime</span></dt><dd class="dd-description">
Build a custom runtime system (in the file specified by option <span class="c003">-o</span>)
incorporating the C object files and libraries given on the command
line. This custom runtime system can be used later to execute
bytecode executables produced with the
<span class="c003">ocamlc -use-runtime</span> <span class="c009">runtime-name</span> option.
See section <a href="#ss%3Acustom-runtime">20.1.6</a> for more information.
</dd><dt class="dt-description"><span class="c006">-match-context-rows</span></dt><dd class="dd-description">
Set the number of rows of context used for optimization during
pattern matching compilation. The default value is 32. Lower values
cause faster compilation, but less optimized code. This advanced
option is meant for use in the event that a pattern-match-heavy
program leads to significant increases in compilation time.
</dd><dt class="dt-description"><span class="c006">-no-alias-deps</span></dt><dd class="dd-description">
Do not record dependencies for module aliases. See
section <a href="#s%3Amodule-alias">8.8</a> for more information.
</dd><dt class="dt-description"><span class="c006">-no-app-funct</span></dt><dd class="dd-description">
Deactivates the applicative behaviour of functors. With this option,
each functor application generates new types in its result and
applying the same functor twice to the same argument yields two
incompatible structures.</dd><dt class="dt-description"><span class="c006">-noassert</span></dt><dd class="dd-description">
Do not compile assertion checks. Note that the special form
<span class="c003">assert false</span> is always compiled because it is typed specially.
This flag has no effect when linking already-compiled files.</dd><dt class="dt-description"><span class="c006">-noautolink</span></dt><dd class="dd-description">
When linking <span class="c003">.cma</span>libraries, ignore <span class="c003">-custom</span>, <span class="c003">-cclib</span> and <span class="c003">-ccopt</span>
options potentially contained in the libraries (if these options were
given when building the libraries). This can be useful if a library
contains incorrect specifications of C libraries or C options; in this
case, during linking, set <span class="c003">-noautolink</span> and pass the correct C
libraries and options on the command line.
</dd><dt class="dt-description"><span class="c006">-nolabels</span></dt><dd class="dd-description">
Ignore non-optional labels in types. Labels cannot be used in
applications, and parameter order becomes strict.</dd><dt class="dt-description"><span class="c006">-nostdlib</span></dt><dd class="dd-description">
Do not include the standard library directory in the list of
directories searched for
compiled interface files (<span class="c003">.cmi</span>), compiled object code files
(<span class="c003">.cmo</span>), libraries (<span class="c003">.cma</span>), and C libraries specified with
<span class="c003">-cclib -lxxx</span>. See also option <span class="c003">-I</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-o</span> <span class="c009">exec-file</span></span></dt><dd class="dd-description">
Specify the name of the output file produced by the
compiler. The
default output name is <span class="c003">a.out</span> under Unix and <span class="c003">camlprog.exe</span> under
Windows. If the <span class="c003">-a</span> option is given, specify the name of the library
produced. If the <span class="c003">-pack</span> option is given, specify the name of the
packed object file produced. If the <span class="c003">-output-obj</span> option is given,
specify the name of the output file produced.

If the <span class="c003">-c</span> option is given, specify the name of the object
file produced for the <em>next</em> source file that appears on the
command line.
</dd><dt class="dt-description"><span class="c006">-opaque</span></dt><dd class="dd-description">
When the native compiler compiles an implementation, by default it
produces a <span class="c003">.cmx</span> file containing information for cross-module
optimization. It also expects <span class="c003">.cmx</span> files to be present for the
dependencies of the currently compiled source, and uses them for
optimization. Since OCaml 4.03, the compiler will emit a warning if it
is unable to locate the <span class="c003">.cmx</span> file of one of those dependencies.<p>The <span class="c003">-opaque</span> option, available since 4.04, disables cross-module
optimization information for the currently compiled unit. When
compiling <span class="c003">.mli</span> interface, using <span class="c003">-opaque</span> marks the compiled <span class="c003">.cmi</span>
interface so that subsequent compilations of modules that depend on it
will not rely on the corresponding <span class="c003">.cmx</span> file, nor warn if it is
absent. When the native compiler compiles a <span class="c003">.ml</span> implementation,
using <span class="c003">-opaque</span> generates a <span class="c003">.cmx</span> that does not contain any
cross-module optimization information.</p><p>Using this option may degrade the quality of generated code, but it
reduces compilation time, both on clean and incremental
builds. Indeed, with the native compiler, when the implementation of
a compilation unit changes, all the units that depend on it may need
to be recompiled – because the cross-module information may have
changed. If the compilation unit whose implementation changed was
compiled with <span class="c003">-opaque</span>, no such recompilation needs to occur. This
option can thus be used, for example, to get faster edit-compile-test
feedback loops.
</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-open</span> <span class="c009">Module</span></span></dt><dd class="dd-description">
Opens the given module before processing the interface or
implementation files. If several <span class="c003">-open</span> options are given,
they are processed in order, just as if
the statements <span class="c003">open!</span> <span class="c009">Module1</span><span class="c003">;;</span> <span class="c003">...</span> <span class="c003">open!</span> <span class="c009">ModuleN</span><span class="c003">;;</span>
were added at the top of each file.
</dd><dt class="dt-description"><span class="c006">-output-obj</span></dt><dd class="dd-description">
Cause the linker to produce a C object file instead of
a bytecode executable file.
This is useful to wrap OCaml code as a C library,
callable from any C program. See chapter <a href="#c%3Aintf-c">20</a>,
section <a href="#ss%3Ac-embedded-code">20.7.5</a>. The name of the output object file
must be set with the <span class="c003">-o</span> option.
This option can also be used to produce a C source file (<span class="c003">.c</span> extension)
or a compiled shared/dynamic library (<span class="c003">.so</span> extension, <span class="c003">.dll</span> under Windows).
</dd><dt class="dt-description"><span class="c006">-output-complete-exe</span></dt><dd class="dd-description">
Build a self-contained executable by linking a C object file containing the
bytecode program, the OCaml runtime system and any other static C code given to
<span class="c003">ocamlc</span>. The resulting effect is similar to <span class="c003">-custom</span>, except that the bytecode
is embedded in the C code so it is no longer accessible to tools such as
<span class="c003">ocamldebug</span>. On the other hand, the resulting binary is resistant to <span class="c003">strip</span>.
</dd><dt class="dt-description"><span class="c006">-pack</span></dt><dd class="dd-description">
Build a bytecode object file (<span class="c003">.cmo</span> file) and its associated compiled
interface (<span class="c003">.cmi</span>) that combines the object
files given on the command line, making them appear as sub-modules of
the output <span class="c003">.cmo</span> file. The name of the output <span class="c003">.cmo</span> file must be
given with the <span class="c003">-o</span> option. For instance,
<pre>        ocamlc -pack -o p.cmo a.cmo b.cmo c.cmo
</pre>generates compiled files <span class="c003">p.cmo</span> and <span class="c003">p.cmi</span> describing a compilation
unit having three sub-modules <span class="c003">A</span>, <span class="c003">B</span> and <span class="c003">C</span>, corresponding to the
contents of the object files <span class="c003">a.cmo</span>, <span class="c003">b.cmo</span> and <span class="c003">c.cmo</span>. These
contents can be referenced as <span class="c003">P.A</span>, <span class="c003">P.B</span> and <span class="c003">P.C</span> in the remainder
of the program.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-pp</span> <span class="c009">command</span></span></dt><dd class="dd-description">
Cause the compiler to call the given <span class="c009">command</span> as a preprocessor
for each source file. The output of <span class="c009">command</span> is redirected to
an intermediate file, which is compiled. If there are no compilation
errors, the intermediate file is deleted afterwards.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-ppx</span> <span class="c009">command</span></span></dt><dd class="dd-description">
After parsing, pipe the abstract syntax tree through the preprocessor
<span class="c009">command</span>. The module <span class="c003">Ast_mapper</span>, described in
chapter <a href="#c%3Aparsinglib">27</a>:
<a href="compilerlibref/Ast_mapper.html"> <span class="c003">Ast_mapper</span> </a>
,
implements the external interface of a preprocessor.</dd><dt class="dt-description"><span class="c006">-principal</span></dt><dd class="dd-description">
Check information path during type-checking, to make sure that all
types are derived in a principal way. When using labelled arguments
and/or polymorphic methods, this flag is required to ensure future
versions of the compiler will be able to infer types correctly, even
if internal algorithms change.
All programs accepted in <span class="c003">-principal</span> mode are also accepted in the
default mode with equivalent types, but different binary signatures,
and this may slow down type checking; yet it is a good idea to
use it once before publishing source code.</dd><dt class="dt-description"><span class="c006">-rectypes</span></dt><dd class="dd-description">
Allow arbitrary recursive types during type-checking. By default,
only recursive types where the recursion goes through an object type
are supported.Note that once you have created an interface using this
flag, you must use it again for all dependencies.</dd><dt class="dt-description"><span class="c013"><span class="c003">-runtime-variant</span> <span class="c009">suffix</span></span></dt><dd class="dd-description">
Add the <span class="c009">suffix</span> string to the name of the runtime library used by
the program. Currently, only one such suffix is supported: <span class="c003">d</span>, and
only if the OCaml compiler was configured with option
<span class="c003">-with-debug-runtime</span>. This suffix gives the debug version of the
runtime, which is useful for debugging pointer problems in low-level
code such as C stubs.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-stop-after</span> <span class="c009">pass</span></span></dt><dd class="dd-description">
Stop compilation after the given compilation pass. The currently
supported passes are: <span class="c003">parsing</span>, <span class="c003">typing</span>.
</dd><dt class="dt-description"><span class="c006">-safe-string</span></dt><dd class="dd-description">
Enforce the separation between types <span class="c003">string</span> and <span class="c003">bytes</span>,
thereby making strings read-only. This is the default.</dd><dt class="dt-description"><span class="c006">-short-paths</span></dt><dd class="dd-description">
When a type is visible under several module-paths, use the shortest
one when printing the type’s name in inferred interfaces and error and
warning messages. Identifier names starting with an underscore <span class="c003">_</span> or
containing double underscores <span class="c003">__</span> incur a penalty of +10 when computing
their length.</dd><dt class="dt-description"><span class="c006">-strict-sequence</span></dt><dd class="dd-description">
Force the left-hand part of each sequence to have type unit.</dd><dt class="dt-description"><span class="c006">-strict-formats</span></dt><dd class="dd-description">
Reject invalid formats that were accepted in legacy format
implementations. You should use this flag to detect and fix such
invalid formats, as they will be rejected by future OCaml versions.</dd><dt class="dt-description"><span class="c006">-unboxed-types</span></dt><dd class="dd-description">
When a type is unboxable (i.e. a record with a single argument or a
concrete datatype with a single constructor of one argument) it will
be unboxed unless annotated with <span class="c003">[@@ocaml.boxed]</span>.
</dd><dt class="dt-description"><span class="c006">-no-unboxed-types</span></dt><dd class="dd-description">
When a type is unboxable it will be boxed unless annotated with
<span class="c003">[@@ocaml.unboxed]</span>. This is the default.
</dd><dt class="dt-description"><span class="c006">-unsafe</span></dt><dd class="dd-description">
Turn bound checking off for array and string accesses (the <span class="c003">v.(i)</span> and
<span class="c003">s.[i]</span> constructs). Programs compiled with <span class="c003">-unsafe</span> are therefore
slightly faster, but unsafe: anything can happen if the program
accesses an array or string outside of its bounds.
Additionally, turn off the check for zero divisor in integer division
and modulus operations. With <span class="c003">-unsafe</span>, an integer division
(or modulus) by zero can halt the program or continue with an
unspecified result instead of raising a <span class="c003">Division_by_zero</span> exception.
</dd><dt class="dt-description"><span class="c006">-unsafe-string</span></dt><dd class="dd-description">
Identify the types <span class="c003">string</span> and <span class="c003">bytes</span>, thereby making strings writable.
This is intended for compatibility with old source code and should not
be used with new software.</dd><dt class="dt-description"><span class="c013"><span class="c003">-use-runtime</span> <span class="c009">runtime-name</span></span></dt><dd class="dd-description">
Generate a bytecode executable file that can be executed on the custom
runtime system <span class="c009">runtime-name</span>, built earlier with
<span class="c003">ocamlc -make-runtime</span> <span class="c009">runtime-name</span>.
See section <a href="#ss%3Acustom-runtime">20.1.6</a> for more information.
</dd><dt class="dt-description"><span class="c006">-v</span></dt><dd class="dd-description">
Print the version number of the compiler and the location of the
standard library directory, then exit.</dd><dt class="dt-description"><span class="c006">-verbose</span></dt><dd class="dd-description">
Print all external commands before they are executed,

in particular invocations of the C compiler and linker in <span class="c003">-custom</span> mode.
Useful to debug C library problems.</dd><dt class="dt-description"><span class="c013"><span class="c003">-version</span> or <span class="c003">-vnum</span></span></dt><dd class="dd-description">
Print the version number of the compiler in short form (e.g. <span class="c003">3.11.0</span>),
then exit.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-w</span> <span class="c009">warning-list</span></span></dt><dd class="dd-description">
Enable, disable, or mark as fatal the warnings specified by the argument
<span class="c009">warning-list</span>.
Each warning can be <em>enabled</em> or <em>disabled</em>, and each warning
can be <em>fatal</em> or <em>non-fatal</em>.
If a warning is disabled, it isn’t displayed and doesn’t affect
compilation in any way (even if it is fatal). If a warning is
enabled, it is displayed normally by the compiler whenever the source
code triggers it. If it is enabled and fatal, the compiler will also
stop with an error after displaying it.<p>The <span class="c009">warning-list</span> argument is a sequence of warning specifiers,
with no separators between them. A warning specifier is one of the
following:</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">+</span><span class="c009">num</span></span></dt><dd class="dd-description"> Enable warning number <span class="c009">num</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-</span><span class="c009">num</span></span></dt><dd class="dd-description"> Disable warning number <span class="c009">num</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">@</span><span class="c009">num</span></span></dt><dd class="dd-description"> Enable and mark as fatal warning number <span class="c009">num</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">+</span><span class="c009">num1</span>..<span class="c009">num2</span></span></dt><dd class="dd-description"> Enable warnings in the given range.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-</span><span class="c009">num1</span>..<span class="c009">num2</span></span></dt><dd class="dd-description"> Disable warnings in the given range.
</dd><dt class="dt-description"><span class="c013"><span class="c003">@</span><span class="c009">num1</span>..<span class="c009">num2</span></span></dt><dd class="dd-description"> Enable and mark as fatal warnings in
the given range.
</dd><dt class="dt-description"><span class="c013"><span class="c003">+</span><span class="c009">letter</span></span></dt><dd class="dd-description"> Enable the set of warnings corresponding to
<span class="c009">letter</span>. The letter may be uppercase or lowercase.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-</span><span class="c009">letter</span></span></dt><dd class="dd-description"> Disable the set of warnings corresponding to
<span class="c009">letter</span>. The letter may be uppercase or lowercase.
</dd><dt class="dt-description"><span class="c013"><span class="c003">@</span><span class="c009">letter</span></span></dt><dd class="dd-description"> Enable and mark as fatal the set of warnings
corresponding to <span class="c009">letter</span>. The letter may be uppercase or
lowercase.
</dd><dt class="dt-description"><span class="c011">uppercase-letter</span></dt><dd class="dd-description"> Enable the set of warnings corresponding
to <span class="c009">uppercase-letter</span>.
</dd><dt class="dt-description"><span class="c011">lowercase-letter</span></dt><dd class="dd-description"> Disable the set of warnings corresponding
to <span class="c009">lowercase-letter</span>.
</dd></dl><p>Warning numbers and letters which are out of the range of warnings
that are currently defined are ignored. The warnings are as follows.
</p><dl class="description"><dt class="dt-description">
<span class="c013">1</span></dt><dd class="dd-description"> Suspicious-looking start-of-comment mark.
</dd><dt class="dt-description"><span class="c013">2</span></dt><dd class="dd-description"> Suspicious-looking end-of-comment mark.
</dd><dt class="dt-description"><span class="c013">3</span></dt><dd class="dd-description"> Deprecated synonym for the ’deprecated’ alert.
</dd><dt class="dt-description"><span class="c013">4</span></dt><dd class="dd-description"> Fragile pattern matching: matching that will remain complete even
if additional constructors are added to one of the variant types
matched.
</dd><dt class="dt-description"><span class="c013">5</span></dt><dd class="dd-description"> Partially applied function: expression whose result has function
type and is ignored.
</dd><dt class="dt-description"><span class="c013">6</span></dt><dd class="dd-description"> Label omitted in function application.
</dd><dt class="dt-description"><span class="c013">7</span></dt><dd class="dd-description"> Method overridden.
</dd><dt class="dt-description"><span class="c013">8</span></dt><dd class="dd-description"> Partial match: missing cases in pattern-matching.
</dd><dt class="dt-description"><span class="c013">9</span></dt><dd class="dd-description"> Missing fields in a record pattern.
</dd><dt class="dt-description"><span class="c013">10</span></dt><dd class="dd-description"> Expression on the left-hand side of a sequence that doesn’t have type
<span class="c003">unit</span> (and that is not a function, see warning number 5).
</dd><dt class="dt-description"><span class="c013">11</span></dt><dd class="dd-description"> Redundant case in a pattern matching (unused match case).
</dd><dt class="dt-description"><span class="c013">12</span></dt><dd class="dd-description"> Redundant sub-pattern in a pattern-matching.
</dd><dt class="dt-description"><span class="c013">13</span></dt><dd class="dd-description"> Instance variable overridden.
</dd><dt class="dt-description"><span class="c013">14</span></dt><dd class="dd-description"> Illegal backslash escape in a string constant.
</dd><dt class="dt-description"><span class="c013">15</span></dt><dd class="dd-description"> Private method made public implicitly.
</dd><dt class="dt-description"><span class="c013">16</span></dt><dd class="dd-description"> Unerasable optional argument.
</dd><dt class="dt-description"><span class="c013">17</span></dt><dd class="dd-description"> Undeclared virtual method.
</dd><dt class="dt-description"><span class="c013">18</span></dt><dd class="dd-description"> Non-principal type.
</dd><dt class="dt-description"><span class="c013">19</span></dt><dd class="dd-description"> Type without principality.
</dd><dt class="dt-description"><span class="c013">20</span></dt><dd class="dd-description"> Unused function argument.
</dd><dt class="dt-description"><span class="c013">21</span></dt><dd class="dd-description"> Non-returning statement.
</dd><dt class="dt-description"><span class="c013">22</span></dt><dd class="dd-description"> Preprocessor warning.
</dd><dt class="dt-description"><span class="c013">23</span></dt><dd class="dd-description"> Useless record <span class="c003">with</span> clause.
</dd><dt class="dt-description"><span class="c013">24</span></dt><dd class="dd-description"> Bad module name: the source file name is not a valid OCaml module name.
</dd><dt class="dt-description"><span class="c013">25</span></dt><dd class="dd-description"> Deprecated: now part of warning 8.
</dd><dt class="dt-description"><span class="c013">26</span></dt><dd class="dd-description"> Suspicious unused variable: unused variable that is bound
with <span class="c003">let</span> or <span class="c003">as</span>, and doesn’t start with an underscore (<span class="c003">_</span>)
character.
</dd><dt class="dt-description"><span class="c013">27</span></dt><dd class="dd-description"> Innocuous unused variable: unused variable that is not bound with
<span class="c003">let</span> nor <span class="c003">as</span>, and doesn’t start with an underscore (<span class="c003">_</span>)
character.
</dd><dt class="dt-description"><span class="c013">28</span></dt><dd class="dd-description"> Wildcard pattern given as argument to a constant constructor.
</dd><dt class="dt-description"><span class="c013">29</span></dt><dd class="dd-description"> Unescaped end-of-line in a string constant (non-portable code).
</dd><dt class="dt-description"><span class="c013">30</span></dt><dd class="dd-description"> Two labels or constructors of the same name are defined in two
mutually recursive types.
</dd><dt class="dt-description"><span class="c013">31</span></dt><dd class="dd-description"> A module is linked twice in the same executable.
</dd><dt class="dt-description"><span class="c013">32</span></dt><dd class="dd-description"> Unused value declaration.
</dd><dt class="dt-description"><span class="c013">33</span></dt><dd class="dd-description"> Unused open statement.
</dd><dt class="dt-description"><span class="c013">34</span></dt><dd class="dd-description"> Unused type declaration.
</dd><dt class="dt-description"><span class="c013">35</span></dt><dd class="dd-description"> Unused for-loop index.
</dd><dt class="dt-description"><span class="c013">36</span></dt><dd class="dd-description"> Unused ancestor variable.
</dd><dt class="dt-description"><span class="c013">37</span></dt><dd class="dd-description"> Unused constructor.
</dd><dt class="dt-description"><span class="c013">38</span></dt><dd class="dd-description"> Unused extension constructor.
</dd><dt class="dt-description"><span class="c013">39</span></dt><dd class="dd-description"> Unused rec flag.
</dd><dt class="dt-description"><span class="c013">40</span></dt><dd class="dd-description"> Constructor or label name used out of scope.
</dd><dt class="dt-description"><span class="c013">41</span></dt><dd class="dd-description"> Ambiguous constructor or label name.
</dd><dt class="dt-description"><span class="c013">42</span></dt><dd class="dd-description"> Disambiguated constructor or label name (compatibility warning).
</dd><dt class="dt-description"><span class="c013">43</span></dt><dd class="dd-description"> Nonoptional label applied as optional.
</dd><dt class="dt-description"><span class="c013">44</span></dt><dd class="dd-description"> Open statement shadows an already defined identifier.
</dd><dt class="dt-description"><span class="c013">45</span></dt><dd class="dd-description"> Open statement shadows an already defined label or constructor.
</dd><dt class="dt-description"><span class="c013">46</span></dt><dd class="dd-description"> Error in environment variable.
</dd><dt class="dt-description"><span class="c013">47</span></dt><dd class="dd-description"> Illegal attribute payload.
</dd><dt class="dt-description"><span class="c013">48</span></dt><dd class="dd-description"> Implicit elimination of optional arguments.
</dd><dt class="dt-description"><span class="c013">49</span></dt><dd class="dd-description"> Absent cmi file when looking up module alias.
</dd><dt class="dt-description"><span class="c013">50</span></dt><dd class="dd-description"> Unexpected documentation comment.
</dd><dt class="dt-description"><span class="c013">51</span></dt><dd class="dd-description"> Warning on non-tail calls if @tailcall present.
</dd><dt class="dt-description"><span class="c013">52 (see </span><a href="#ss%3Awarn52"><span class="c013">9.5.2</span></a><span class="c013">)</span></dt><dd class="dd-description"> Fragile constant pattern.
</dd><dt class="dt-description"><span class="c013">53</span></dt><dd class="dd-description"> Attribute cannot appear in this context.
</dd><dt class="dt-description"><span class="c013">54</span></dt><dd class="dd-description"> Attribute used more than once on an expression.
</dd><dt class="dt-description"><span class="c013">55</span></dt><dd class="dd-description"> Inlining impossible.
</dd><dt class="dt-description"><span class="c013">56</span></dt><dd class="dd-description"> Unreachable case in a pattern-matching (based on type information).
</dd><dt class="dt-description"><span class="c013">57 (see </span><a href="#ss%3Awarn57"><span class="c013">9.5.3</span></a><span class="c013">)</span></dt><dd class="dd-description"> Ambiguous or-pattern variables under guard.
</dd><dt class="dt-description"><span class="c013">58</span></dt><dd class="dd-description"> Missing cmx file.
</dd><dt class="dt-description"><span class="c013">59</span></dt><dd class="dd-description"> Assignment to non-mutable value.
</dd><dt class="dt-description"><span class="c013">60</span></dt><dd class="dd-description"> Unused module declaration.
</dd><dt class="dt-description"><span class="c013">61</span></dt><dd class="dd-description"> Unboxable type in primitive declaration.
</dd><dt class="dt-description"><span class="c013">62</span></dt><dd class="dd-description"> Type constraint on GADT type declaration.
</dd><dt class="dt-description"><span class="c013">63</span></dt><dd class="dd-description"> Erroneous printed signature.
</dd><dt class="dt-description"><span class="c013">64</span></dt><dd class="dd-description"> -unsafe used with a preprocessor returning a syntax tree.
</dd><dt class="dt-description"><span class="c013">65</span></dt><dd class="dd-description"> Type declaration defining a new ’()’ constructor.
</dd><dt class="dt-description"><span class="c013">66</span></dt><dd class="dd-description"> Unused open! statement.
</dd><dt class="dt-description"><span class="c013">67</span></dt><dd class="dd-description"> Unused functor parameter.
</dd><dt class="dt-description"><span class="c013">A</span></dt><dd class="dd-description"> all warnings
</dd><dt class="dt-description"><span class="c013">C</span></dt><dd class="dd-description"> warnings 1, 2.
</dd><dt class="dt-description"><span class="c013">D</span></dt><dd class="dd-description"> Alias for warning 3.
</dd><dt class="dt-description"><span class="c013">E</span></dt><dd class="dd-description"> Alias for warning 4.
</dd><dt class="dt-description"><span class="c013">F</span></dt><dd class="dd-description"> Alias for warning 5.
</dd><dt class="dt-description"><span class="c013">K</span></dt><dd class="dd-description"> warnings 32, 33, 34, 35, 36, 37, 38, 39.
</dd><dt class="dt-description"><span class="c013">L</span></dt><dd class="dd-description"> Alias for warning 6.
</dd><dt class="dt-description"><span class="c013">M</span></dt><dd class="dd-description"> Alias for warning 7.
</dd><dt class="dt-description"><span class="c013">P</span></dt><dd class="dd-description"> Alias for warning 8.
</dd><dt class="dt-description"><span class="c013">R</span></dt><dd class="dd-description"> Alias for warning 9.
</dd><dt class="dt-description"><span class="c013">S</span></dt><dd class="dd-description"> Alias for warning 10.
</dd><dt class="dt-description"><span class="c013">U</span></dt><dd class="dd-description"> warnings 11, 12.
</dd><dt class="dt-description"><span class="c013">V</span></dt><dd class="dd-description"> Alias for warning 13.
</dd><dt class="dt-description"><span class="c013">X</span></dt><dd class="dd-description"> warnings 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 30.
</dd><dt class="dt-description"><span class="c013">Y</span></dt><dd class="dd-description"> Alias for warning 26.
</dd><dt class="dt-description"><span class="c013">Z</span></dt><dd class="dd-description"> Alias for warning 27.

</dd></dl><p>The default setting is <span class="c003">-w +a-4-6-7-9-27-29-32..42-44-45-48-50-60</span>.
It is displayed by <span class="c003">ocamlc -help</span>.
Note that warnings 5 and 10 are not always triggered, depending on
the internals of the type checker.</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-warn-error</span> <span class="c009">warning-list</span></span></dt><dd class="dd-description">
Mark as fatal the warnings specified in the argument <span class="c009">warning-list</span>.
The compiler will stop with an error when one of these warnings is
emitted. The <span class="c009">warning-list</span> has the same meaning as for
the <span class="c003">-w</span> option: a <span class="c003">+</span> sign (or an uppercase letter) marks the
corresponding warnings as fatal, a <span class="c003">-</span>
sign (or a lowercase letter) turns them back into non-fatal warnings,
and a <span class="c003">@</span> sign both enables and marks as fatal the corresponding
warnings.<p>Note: it is not recommended to use warning sets (i.e. letters) as
arguments to <span class="c003">-warn-error</span>
in production code, because this can break your build when future versions
of OCaml add some new warnings.</p><p>The default setting is <span class="c003">-warn-error -a+31</span> (only warning 31 is fatal).</p></dd><dt class="dt-description"><span class="c006">-warn-help</span></dt><dd class="dd-description">
Show the description of all available warning numbers.</dd><dt class="dt-description"><span class="c006">-where</span></dt><dd class="dd-description">
Print the location of the standard library, then exit.
</dd><dt class="dt-description"><span class="c006">-with-runtime</span></dt><dd class="dd-description">
Include the runtime system in the generated program. This is the default.
</dd><dt class="dt-description"><span class="c006">-without-runtime</span></dt><dd class="dd-description">
The compiler does not include the runtime system (nor a reference to it) in the
generated program; it must be supplied separately.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Process <span class="c009">file</span> as a file name, even if it starts with a dash (<span class="c003">-</span>)
character.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-help</span> or <span class="c003">--help</span></span></dt><dd class="dd-description">
Display a short usage summary and exit.</dd></dl>
<!--TOC paragraph id="sec290" contextual-cli-control-->
<h5 class="paragraph" id="sec290"><a class="section-anchor" href="#sec290" aria-hidden="true"></a>contextual-cli-control</h5><!--SEC END --><p>Contextual control of command-line options</p><p>The compiler command line can be modified “from the outside”
with the following mechanisms. These are experimental
and subject to change. They should be used only for experimental and
development work, not in released packages.</p><dl class="description"><dt class="dt-description">
<span class="c006">OCAMLPARAM</span> (environment variable)</dt><dd class="dd-description">
A set of arguments that will be inserted before or after the arguments from
the command line. Arguments are specified in a comma-separated list
of <span class="c003">name=value</span> pairs. A <span class="c003">_</span> is used to specify the position of
the command line arguments, i.e. <span class="c003">a=x,_,b=y</span> means that <span class="c003">a=x</span> should be
executed before parsing the arguments, and <span class="c003">b=y</span> after. Finally,
an alternative separator can be specified as the
first character of the string, within the set <span class="c003">:|; ,</span>.
</dd><dt class="dt-description"><span class="c006">ocaml_compiler_internal_params</span> (file in the stdlib directory)</dt><dd class="dd-description">
A mapping of file names to lists of arguments that
will be added to the command line (and <span class="c003">OCAMLPARAM</span>) arguments.
</dd><dt class="dt-description"><span class="c006">OCAML_FLEXLINK</span> (environment variable)</dt><dd class="dd-description">
Alternative executable to use on native
Windows for <span class="c003">flexlink</span> instead of the
configured value. Primarily used for bootstrapping.
</dd></dl>
<!--TOC section id="s:modules-file-system" 9.3  Modules and the file system-->
<h2 class="section" id="s:modules-file-system"><a class="section-anchor" href="#s:modules-file-system" aria-hidden="true"></a>9.3  Modules and the file system</h2><!--SEC END --><p>This short section is intended to clarify the relationship between the
names of the modules corresponding to compilation units and the names
of the files that contain their compiled interface and compiled
implementation.</p><p>The compiler always derives the module name by taking the capitalized
base name of the source file (<span class="c003">.ml</span> or <span class="c003">.mli</span> file). That is, it
strips the leading directory name, if any, as well as the <span class="c003">.ml</span> or
<span class="c003">.mli</span> suffix; then, it set the first letter to uppercase, in order to
comply with the requirement that module names must be capitalized.
For instance, compiling the file <span class="c003">mylib/misc.ml</span> provides an
implementation for the module named <span class="c003">Misc</span>. Other compilation units
may refer to components defined in <span class="c003">mylib/misc.ml</span> under the names
<span class="c003">Misc.</span><span class="c009">name</span>; they can also do <span class="c003">open Misc</span>, then use unqualified
names <span class="c009">name</span>.</p><p>The <span class="c003">.cmi</span> and <span class="c003">.cmo</span> files produced by the compiler have the same
base name as the source file. Hence, the compiled files always have
their base name equal (modulo capitalization of the first letter) to
the name of the module they describe (for <span class="c003">.cmi</span> files) or implement
(for <span class="c003">.cmo</span> files).</p><p>When the compiler encounters a reference to a free module identifier
<span class="c003">Mod</span>, it looks in the search path for a file named <span class="c003">Mod.cmi</span> or <span class="c003">mod.cmi</span>
and loads the compiled interface
contained in that file. As a consequence, renaming <span class="c003">.cmi</span> files is not
advised: the name of a <span class="c003">.cmi</span> file must always correspond to the name
of the compilation unit it implements. It is admissible to move them
to another directory, if their base name is preserved, and the correct
<span class="c003">-I</span> options are given to the compiler. The compiler will flag an
error if it loads a <span class="c003">.cmi</span> file that has been renamed.</p><p>Compiled bytecode files (<span class="c003">.cmo</span> files), on the other hand, can be
freely renamed once created. That’s because the linker never attempts
to find by itself the <span class="c003">.cmo</span> file that implements a module with a
given name: it relies instead on the user providing the list of <span class="c003">.cmo</span>
files by hand.</p>
<!--TOC section id="s:comp-errors" 9.4  Common errors-->
<h2 class="section" id="s:comp-errors"><a class="section-anchor" href="#s:comp-errors" aria-hidden="true"></a>9.4  Common errors</h2><!--SEC END --><p>This section describes and explains the most frequently encountered
error messages.</p><dl class="description"><dt class="dt-description"><span class="c013">Cannot find file <span class="c009">filename</span></span></dt><dd class="dd-description">
The named file could not be found in the current directory, nor in the
directories of the search path. The <span class="c009">filename</span> is either a
compiled interface file (<span class="c003">.cmi</span> file), or a compiled bytecode file
(<span class="c003">.cmo</span> file). If <span class="c009">filename</span> has the format <span class="c009">mod</span><span class="c003">.cmi</span>, this
means you are trying to compile a file that references identifiers
from module <span class="c009">mod</span>, but you have not yet compiled an interface for
module <span class="c009">mod</span>. Fix: compile <span class="c009">mod</span><span class="c003">.mli</span> or <span class="c009">mod</span><span class="c003">.ml</span>
first, to create the compiled interface <span class="c009">mod</span><span class="c003">.cmi</span>.<p>If <span class="c009">filename</span> has the format <span class="c009">mod</span><span class="c003">.cmo</span>, this
means you are trying to link a bytecode object file that does not
exist yet. Fix: compile <span class="c009">mod</span><span class="c003">.ml</span> first.</p><p>If your program spans several directories, this error can also appear
because you haven’t specified the directories to look into. Fix: add
the correct <span class="c003">-I</span> options to the command line.</p></dd><dt class="dt-description"><span class="c013">Corrupted compiled interface <span class="c009">filename</span></span></dt><dd class="dd-description">
The compiler produces this error when it tries to read a compiled
interface file (<span class="c003">.cmi</span> file) that has the wrong structure. This means
something went wrong when this <span class="c003">.cmi</span> file was written: the disk was
full, the compiler was interrupted in the middle of the file creation,
and so on. This error can also appear if a <span class="c003">.cmi</span> file is modified after
its creation by the compiler. Fix: remove the corrupted <span class="c003">.cmi</span> file,
and rebuild it.</dd><dt class="dt-description"><span class="c013">This expression has type </span><span class="c009">t</span><sub>1</sub><span class="c013">, but is used with type </span><span class="c009">t</span><sub>2</sub></dt><dd class="dd-description">
This is by far the most common type error in programs. Type <span class="c009">t</span><sub>1</sub> is
the type inferred for the expression (the part of the program that is
displayed in the error message), by looking at the expression itself.
Type <span class="c009">t</span><sub>2</sub> is the type expected by the context of the expression; it
is deduced by looking at how the value of this expression is used in
the rest of the program. If the two types <span class="c009">t</span><sub>1</sub> and <span class="c009">t</span><sub>2</sub> are not
compatible, then the error above is produced.<p>In some cases, it is hard to understand why the two types <span class="c009">t</span><sub>1</sub> and
<span class="c009">t</span><sub>2</sub> are incompatible. For instance, the compiler can report that
“expression of type <span class="c003">foo</span> cannot be used with type <span class="c003">foo</span>”, and it
really seems that the two types <span class="c003">foo</span> are compatible. This is not
always true. Two type constructors can have the same name, but
actually represent different types. This can happen if a type
constructor is redefined. Example:
</p><pre>        type foo = A | B
        let f = function A -&gt; 0 | B -&gt; 1
        type foo = C | D
        f C
</pre><p>This result in the error message “expression <span class="c003">C</span> of type <span class="c003">foo</span> cannot
be used with type <span class="c003">foo</span>”.</p></dd><dt class="dt-description"><span class="c013">The type of this expression, <span class="c009">t</span>, contains type variables
that cannot be generalized</span></dt><dd class="dd-description">
Type variables (<span class="c003">'a</span>, <span class="c003">'b</span>, …) in a type <span class="c009">t</span> can be in either
of two states: generalized (which means that the type <span class="c009">t</span> is valid
for all possible instantiations of the variables) and not generalized
(which means that the type <span class="c009">t</span> is valid only for one instantiation
of the variables). In a <span class="c003">let</span> binding <span class="c003">let </span><span class="c009">name</span><span class="c003"> = </span><span class="c009">expr</span>,
the type-checker normally generalizes as many type variables as
possible in the type of <span class="c009">expr</span>. However, this leads to unsoundness
(a well-typed program can crash) in conjunction with polymorphic
mutable data structures. To avoid this, generalization is performed at
<span class="c003">let</span> bindings only if the bound expression <span class="c009">expr</span> belongs to the
class of “syntactic values”, which includes constants, identifiers,
functions, tuples of syntactic values, etc. In all other cases (for
instance, <span class="c009">expr</span> is a function application), a polymorphic mutable
could have been created and generalization is therefore turned off for
all variables occurring in contravariant or non-variant branches of the
type. For instance, if the type of a non-value is <span class="c003">'a list</span> the
variable is generalizable (<span class="c003">list</span> is a covariant type constructor),
but not in <span class="c003">'a list -&gt; 'a list</span> (the left branch of <span class="c003">-&gt;</span> is
contravariant) or <span class="c003">'a ref</span> (<span class="c003">ref</span> is non-variant).<p>Non-generalized type variables in a type cause no difficulties inside
a given structure or compilation unit (the contents of a <span class="c003">.ml</span> file,
or an interactive session), but they cannot be allowed inside
signatures nor in compiled interfaces (<span class="c003">.cmi</span> file), because they
could be used inconsistently later. Therefore, the compiler
flags an error when a structure or compilation unit defines a value
<span class="c009">name</span> whose type contains non-generalized type variables. There
are two ways to fix this error:
</p><ul class="itemize"><li class="li-itemize">
Add a type constraint or a <span class="c003">.mli</span> file to give a monomorphic
type (without type variables) to <span class="c009">name</span>. For instance, instead of
writing
<pre>    let sort_int_list = List.sort Stdlib.compare
    (* inferred type 'a list -&gt; 'a list, with 'a not generalized *)
</pre>write
<pre>    let sort_int_list = (List.sort Stdlib.compare : int list -&gt; int list);;
</pre></li><li class="li-itemize">If you really need <span class="c009">name</span> to have a polymorphic type, turn
its defining expression into a function by adding an extra parameter.
For instance, instead of writing
<pre>    let map_length = List.map Array.length
    (* inferred type 'a array list -&gt; int list, with 'a not generalized *)
</pre>write
<pre>    let map_length lv = List.map Array.length lv
</pre></li></ul></dd><dt class="dt-description"><span class="c013">Reference to undefined global <span class="c009">mod</span></span></dt><dd class="dd-description">
This error appears when trying to link an incomplete or incorrectly
ordered set of files. Either you have forgotten to provide an
implementation for the compilation unit named <span class="c009">mod</span> on the command line
(typically, the file named <span class="c009">mod</span><span class="c003">.cmo</span>, or a library containing
that file). Fix: add the missing <span class="c003">.ml</span> or <span class="c003">.cmo</span> file to the command
line. Or, you have provided an implementation for the module named
<span class="c009">mod</span>, but it comes too late on the command line: the
implementation of <span class="c009">mod</span> must come before all bytecode object files
that reference <span class="c009">mod</span>. Fix: change the order of <span class="c003">.ml</span> and <span class="c003">.cmo</span>
files on the command line.<p>Of course, you will always encounter this error if you have mutually
recursive functions across modules. That is, function <span class="c003">Mod1.f</span> calls
function <span class="c003">Mod2.g</span>, and function <span class="c003">Mod2.g</span> calls function <span class="c003">Mod1.f</span>.
In this case, no matter what permutations you perform on the command
line, the program will be rejected at link-time. Fixes:
</p><ul class="itemize"><li class="li-itemize">
Put <span class="c003">f</span> and <span class="c003">g</span> in the same module.
</li><li class="li-itemize">Parameterize one function by the other.
That is, instead of having
<pre>mod1.ml:    let f x = ... Mod2.g ...
mod2.ml:    let g y = ... Mod1.f ...
</pre>define
<pre>mod1.ml:    let f g x = ... g ...
mod2.ml:    let rec g y = ... Mod1.f g ...
</pre>and link <span class="c003">mod1.cmo</span> before <span class="c003">mod2.cmo</span>.
</li><li class="li-itemize">Use a reference to hold one of the two functions, as in :
<pre>mod1.ml:    let forward_g =
                ref((fun x -&gt; failwith "forward_g") : &lt;type&gt;)
            let f x = ... !forward_g ...
mod2.ml:    let g y = ... Mod1.f ...
            let _ = Mod1.forward_g := g
</pre></li></ul></dd><dt class="dt-description"><span class="c013">The external function <span class="c009">f</span> is not available</span></dt><dd class="dd-description">
This error appears when trying to link code that calls external
functions written in C. As explained in
chapter <a href="#c%3Aintf-c">20</a>, such code must be linked with C libraries that
implement the required <span class="c009">f</span> C function. If the C libraries in
question are not shared libraries (DLLs), the code must be linked in
“custom runtime” mode. Fix: add the required C libraries to the
command line, and possibly the <span class="c003">-custom</span> option.</dd></dl>
<!--TOC section id="s:comp-warnings" 9.5  Warning reference-->
<h2 class="section" id="s:comp-warnings"><a class="section-anchor" href="#s:comp-warnings" aria-hidden="true"></a>9.5  Warning reference</h2><!--SEC END --><p>This section describes and explains in detail some warnings:</p>
<!--TOC subsection id="ss:warn9" 9.5.1  Warning 9: missing fields in a record pattern-->
<h3 class="subsection" id="ss:warn9"><a class="section-anchor" href="#ss:warn9" aria-hidden="true"></a>9.5.1  Warning 9: missing fields in a record pattern</h3><!--SEC END --><p>When pattern matching on records, it can be useful to match only few
fields of a record. Eliding fields can be done either implicitly
or explicitly by ending the record pattern with <span class="c003">; _</span>.
However, implicit field elision is at odd with pattern matching
exhaustiveness checks.
Enabling warning 9 prioritizes exhaustiveness checks over the
convenience of implicit field elision and will warn on implicit
field elision in record patterns. In particular, this warning can
help to spot exhaustive record pattern that may need to be updated
after the addition of new fields to a record type.</p><pre>type 'a point = {x : 'a; y : 'a}
let dx { x } = x (* implicit field elision: trigger warning 9 *)
let dy { y; _ } = y (* explicit field elision: do not trigger warning 9 *)
</pre>
<!--TOC subsection id="ss:warn52" 9.5.2  Warning 52: fragile constant pattern-->
<h3 class="subsection" id="ss:warn52"><a class="section-anchor" href="#ss:warn52" aria-hidden="true"></a>9.5.2  Warning 52: fragile constant pattern</h3><!--SEC END --><p>Some constructors, such as the exception constructors <span class="c003">Failure</span> and
<span class="c003">Invalid_argument</span>, take as parameter a <span class="c003">string</span> value holding
a text message intended for the user.</p><p>These text messages are usually not stable over time: call sites
building these constructors may refine the message in a future
version to make it more explicit, etc. Therefore, it is dangerous to
match over the precise value of the message. For example, until
OCaml 4.02, <span class="c003">Array.iter2</span> would raise the exception
</p><pre>  Invalid_argument "arrays must have the same length"
</pre><p> Since 4.03 it raises the more helpful message
</p><pre>  Invalid_argument "Array.iter2: arrays must have the same length"
</pre><p> but this means that any code of the form
</p><pre>  try ...
  with Invalid_argument "arrays must have the same length" -&gt; ...
</pre><p> is now broken and may suffer from uncaught exceptions.</p><p>Warning 52 is there to prevent users from writing such fragile code
in the first place. It does not occur on every matching on a literal
string, but only in the case in which library authors expressed
their intent to possibly change the constructor parameter value in
the future, by using the attribute <span class="c003">ocaml.warn_on_literal_pattern</span>
(see the manual section on builtin attributes in
<a href="#ss%3Abuiltin-attributes">8.12.1</a>):
</p><pre>  type t =
    | Foo of string [@ocaml.warn_on_literal_pattern]
    | Bar of string

  let no_warning = function
    | Bar "specific value" -&gt; 0
    | _ -&gt; 1

  let warning = function
    | Foo "specific value" -&gt; 0
    | _ -&gt; 1

&gt;    | Foo "specific value" -&gt; 0
&gt;          ^^^^^^^^^^^^^^^^
&gt; Warning 52: Code should not depend on the actual values of
&gt; this constructor's arguments. They are only for information
&gt; and may change in future versions. (See manual section 8.5)
</pre><p>
In particular, all built-in exceptions with a string argument have
this attribute set: <span class="c003">Invalid_argument</span>, <span class="c003">Failure</span>, <span class="c003">Sys_error</span> will
all raise this warning if you match for a specific string argument.</p><p>Additionally, built-in exceptions with a structured argument that
includes a string also have the attribute set: <span class="c003">Assert_failure</span> and
<span class="c003">Match_failure</span> will raise the warning for a pattern that uses a
literal string to match the first element of their tuple argument.</p><p>If your code raises this warning, you should <em>not</em> change the
way you test for the specific string to avoid the warning (for
example using a string equality inside the right-hand-side instead
of a literal pattern), as your code would remain fragile. You should
instead enlarge the scope of the pattern by matching on all possible
values.</p><pre>
let warning = function
  | Foo _ -&gt; 0
  | _ -&gt; 1
</pre><p>
This may require some care: if the scrutinee may return several
different cases of the same pattern, or raise distinct instances of
the same exception, you may need to modify your code to separate
those several cases.</p><p>For example,
</p><pre>try (int_of_string count_str, bool_of_string choice_str) with
  | Failure "int_of_string" -&gt; (0, true)
  | Failure "bool_of_string" -&gt; (-1, false)
</pre><p> should be rewritten into more atomic tests. For example,
using the <span class="c003">exception</span> patterns documented in Section <a href="#sss%3Aexception-match">7.6</a>,
one can write:
</p><pre>match int_of_string count_str with
  | exception (Failure _) -&gt; (0, true)
  | count -&gt;
    begin match bool_of_string choice_str with
    | exception (Failure _) -&gt; (-1, false)
    | choice -&gt; (count, choice)
    end
</pre><p>
The only case where that transformation is not possible is if a given
function call may raise distinct exceptions with the same constructor
but different string values. In this case, you will have to check for
specific string values. This is dangerous API design and it should be
discouraged: it’s better to define more precise exception constructors
than store useful information in strings.</p>
<!--TOC subsection id="ss:warn57" 9.5.3  Warning 57: Ambiguous or-pattern variables under guard-->
<h3 class="subsection" id="ss:warn57"><a class="section-anchor" href="#ss:warn57" aria-hidden="true"></a>9.5.3  Warning 57: Ambiguous or-pattern variables under guard</h3><!--SEC END --><p>The semantics of or-patterns in OCaml is specified with
a left-to-right bias: a value <span class="c009">v</span> matches the pattern <span class="c009">p</span> <span class="c003">|</span> <span class="c009">q</span>
if it matches <span class="c009">p</span> or <span class="c009">q</span>, but if it matches both,
the environment captured by the match is the environment captured by
<span class="c009">p</span>, never the one captured by <span class="c009">q</span>.</p><p>While this property is generally intuitive, there is at least one specific
case where a different semantics might be expected.
Consider a pattern followed by a when-guard:
<span class="c003">|</span> <span class="c009">p</span> <span class="c003">when</span> <span class="c009">g</span> <span class="c003">-&gt;</span> <span class="c009">e</span>, for example:
</p><pre>     | ((Const x, _) | (_, Const x)) when is_neutral x -&gt; branch
</pre><p> The semantics is clear:
match the scrutinee against the pattern, if it matches, test the guard,
and if the guard passes, take the branch.
In particular, consider the input <span class="c003">(Const</span> <span class="c009">a</span><span class="c003">, Const</span> <span class="c009">b</span><span class="c003">)</span>, where
<span class="c009">a</span> fails the test <span class="c003">is_neutral</span> <span class="c009">a</span>, while <span class="c009">b</span> passes the test
<span class="c003">is_neutral</span> <span class="c009">b</span>. With the left-to-right semantics, the clause above is
<em>not</em> taken by its input: matching <span class="c003">(Const</span> <span class="c009">a</span><span class="c003">, Const</span> <span class="c009">b</span><span class="c003">)</span>
against the or-pattern succeeds in the left branch, it returns the
environment <span class="c009">x</span> <span class="c003">-&gt;</span> <span class="c009">a</span>, and then the guard
<span class="c003">is_neutral</span> <span class="c009">a</span> is tested and fails, the branch is not taken.</p><p>However, another semantics may be considered more natural here:
any pair that has one side passing the test will take the branch. With this
semantics the previous code fragment would be equivalent to
</p><pre>     | (Const x, _) when is_neutral x -&gt; branch
     | (_, Const x) when is_neutral x -&gt; branch
</pre><p> This is <em>not</em> the semantics adopted by OCaml.</p><p>Warning 57 is dedicated to these confusing cases where the
specified left-to-right semantics is not equivalent to a non-deterministic
semantics (any branch can be taken) relatively to a specific guard.
More precisely, it warns when guard uses “ambiguous” variables, that are bound
to different parts of the scrutinees by different sides of a or-pattern.

</p>
<!--TOC chapter id="sec297" Chapter 10  The toplevel system or REPL (ocaml)-->
<h1 class="chapter" id="sec297">Chapter 10  The toplevel system or REPL (ocaml)</h1><!--SEC END --><p> <a id="c:camllight"></a>
</p><!--NAME toplevel.html-->
<p>This chapter describes the toplevel system for OCaml, that permits
interactive use of the OCaml system
through a read-eval-print loop (REPL). In this mode, the system repeatedly
reads OCaml phrases from the input, then typechecks, compile and
evaluate them, then prints the inferred type and result value, if
any. The system prints a <span class="c003">#</span> (sharp) prompt before reading each
phrase.</p><p>Input to the toplevel can span several lines. It is terminated by <span class="c004">;;</span> (a
double-semicolon). The toplevel input consists in one or several
toplevel phrases, with the following syntax:</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="toplevel-input"><span class="c010">toplevel-input</span></a></td><td class="c015">::=</td><td class="c017">
{ <a class="syntax" href="#definition"><span class="c010">definition</span></a> }<sup>+</sup> <span class="c004">;;</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#expr"><span class="c010">expr</span></a> <span class="c004">;;</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">#</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a>  [ <a class="syntax" href="#directive-argument"><span class="c010">directive-argument</span></a> ] <span class="c004">;;</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="directive-argument"><span class="c010">directive-argument</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#string-literal"><span class="c010">string-literal</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#integer-literal"><span class="c010">integer-literal</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#value-path"><span class="c010">value-path</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">true</span> ∣  <span class="c004">false</span>
</td></tr>
</table></td></tr>
</table></div><p>A phrase can consist of a definition, like those found in
implementations of compilation units or in <span class="c004">struct</span> … <span class="c004">end</span>
module expressions. The definition can bind value names, type names,
an exception, a module name, or a module type name. The toplevel
system performs the bindings, then prints the types and values (if
any) for the names thus defined.</p><p>A phrase may also consist in a value expression
(section <a href="#s%3Avalue-expr">7.7</a>). It is simply evaluated
without performing any bindings, and its value is
printed.</p><p>Finally, a phrase can also consist in a toplevel directive,
starting with <span class="c004">#</span> (the sharp sign). These directives control the
behavior of the toplevel; they are listed below in
section <a href="#s%3Atoplevel-directives">10.2</a>.</p><blockquote class="quote"><span class="c007">Unix:</span>  
The toplevel system is started by the command <span class="c003">ocaml</span>, as follows:
<pre>
        ocaml <span class="c009">options objects</span>                # interactive mode
        ocaml <span class="c009">options objects scriptfile</span>        # script mode
</pre>
<span class="c009">options</span> are described below.
<span class="c009">objects</span> are filenames ending in <span class="c003">.cmo</span> or <span class="c003">.cma</span>; they are
loaded into the interpreter immediately after <span class="c009">options</span> are set.
<span class="c009">scriptfile</span> is any file name not ending in <span class="c003">.cmo</span> or <span class="c003">.cma</span>.<p>If no <span class="c009">scriptfile</span> is given on the command line, the toplevel system
enters interactive mode: phrases are read on standard input, results
are printed on standard output, errors on standard error. End-of-file
on standard input terminates <span class="c003">ocaml</span> (see also the <span class="c003">#quit</span> directive
in section <a href="#s%3Atoplevel-directives">10.2</a>).</p><p>On start-up (before the first phrase is read), if the file
<span class="c003">.ocamlinit</span> exists in the current directory,
its contents are read as a sequence of OCaml phrases
and executed as per the <span class="c003">#use</span> directive
described in section <a href="#s%3Atoplevel-directives">10.2</a>.
The evaluation outcode for each phrase are not displayed.
If the current directory does not contain an <span class="c003">.ocamlinit</span> file,
the file <span class="c003">XDG_CONFIG_HOME/ocaml/init.ml</span> is looked up according
to the XDG base directory specification and used instead (on Windows
this is skipped). If that file doesn’t exist then an [.ocamlinit] file
in the users’ home directory (determined via environment variable <span class="c003">HOME</span>) is
used if existing.</p><p>The toplevel system does not perform line editing, but it can
easily be used in conjunction with an external line editor such as
<span class="c003">ledit</span>, or <span class="c003">rlwrap</span>. An improved toplevel, <span class="c003">utop</span>, is also available.
Another option is to use <span class="c003">ocaml</span> under Gnu Emacs, which gives the
full editing power of Emacs (command <span class="c003">run-caml</span> from library <span class="c003">inf-caml</span>).</p><p>At any point, the parsing, compilation or evaluation of the current
phrase can be interrupted by pressing <span class="c003">ctrl-C</span> (or, more precisely,
by sending the <span class="c003">INTR</span> signal to the <span class="c003">ocaml</span> process). The toplevel
then immediately returns to the <span class="c003">#</span> prompt.</p><p>If <span class="c009">scriptfile</span> is given on the command-line to <span class="c003">ocaml</span>, the toplevel
system enters script mode: the contents of the file are read as a
sequence of OCaml phrases and executed, as per the <span class="c003">#use</span>
directive (section <a href="#s%3Atoplevel-directives">10.2</a>). The outcome of the
evaluation is not printed. On reaching the end of file, the <span class="c003">ocaml</span>
command exits immediately. No commands are read from standard input.
<span class="c003">Sys.argv</span> is transformed, ignoring all OCaml parameters, and
starting with the script file name in <span class="c003">Sys.argv.(0)</span>.</p><p>In script mode, the first line of the script is ignored if it starts
with <span class="c003">#!</span>. Thus, it should be possible to make the script
itself executable and put as first line <span class="c003">#!/usr/local/bin/ocaml</span>,
thus calling the toplevel system automatically when the script is
run. However, <span class="c003">ocaml</span> itself is a <span class="c003">#!</span> script on most installations
of OCaml, and Unix kernels usually do not handle nested <span class="c003">#!</span>
scripts. A better solution is to put the following as the first line
of the script:
</p><pre>        #!/usr/local/bin/ocamlrun /usr/local/bin/ocaml
</pre></blockquote>
<!--TOC section id="s:toplevel-options" 10.1  Options-->
<h2 class="section" id="s:toplevel-options"><a class="section-anchor" href="#s:toplevel-options" aria-hidden="true"></a>10.1  Options</h2><!--SEC END --><p>The following command-line options are recognized by the <span class="c003">ocaml</span> command.
</p><dl class="description"><dt class="dt-description">
<span class="c006">-absname</span></dt><dd class="dd-description">
Force error messages to show absolute paths for file names.</dd><dt class="dt-description"><span class="c013"><span class="c003">-args</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Read additional newline-terminated command line arguments from <span class="c009">filename</span>.
It is not possible to pass a <span class="c009">scriptfile</span> via file to the toplevel.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-args0</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Read additional null character terminated command line arguments from
<span class="c009">filename</span>.
It is not possible to pass a <span class="c009">scriptfile</span> via file to the toplevel.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-I</span> <span class="c009">directory</span></span></dt><dd class="dd-description">
Add the given directory to the list of directories searched for


source and compiled files.
By default, the current directory is searched first, then the standard
library directory. Directories added with <span class="c003">-I</span> are searched after the
current directory, in the order in which they were given on the command line,
but before the standard library directory. See also option <span class="c003">-nostdlib</span>.<p>If the given directory starts with <span class="c003">+</span>, it is taken relative to the
standard library directory. For instance, <span class="c003">-I +unix</span> adds the
subdirectory <span class="c003">unix</span> of the standard library to the search path.</p><p>Directories can also be added to the list once
the toplevel is running with the <span class="c003">#directory</span> directive
(section <a href="#s%3Atoplevel-directives">10.2</a>).
</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-init</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Load the given file instead of the default initialization file.
The default file is <span class="c003">.ocamlinit</span> in the current directory if it
exists, otherwise <span class="c003">XDG_CONFIG_HOME/ocaml/init.ml</span> or
<span class="c003">.ocamlinit</span> in the user’s home directory.
</dd><dt class="dt-description"><span class="c006">-labels</span></dt><dd class="dd-description">
Labels are not ignored in types, labels may be used in applications,
and labelled parameters can be given in any order. This is the default.</dd><dt class="dt-description"><span class="c006">-no-app-funct</span></dt><dd class="dd-description">
Deactivates the applicative behaviour of functors. With this option,
each functor application generates new types in its result and
applying the same functor twice to the same argument yields two
incompatible structures.</dd><dt class="dt-description"><span class="c006">-noassert</span></dt><dd class="dd-description">
Do not compile assertion checks. Note that the special form
<span class="c003">assert false</span> is always compiled because it is typed specially.
</dd><dt class="dt-description"><span class="c006">-nolabels</span></dt><dd class="dd-description">
Ignore non-optional labels in types. Labels cannot be used in
applications, and parameter order becomes strict.</dd><dt class="dt-description"><span class="c006">-noprompt</span></dt><dd class="dd-description">
Do not display any prompt when waiting for input.
</dd><dt class="dt-description"><span class="c006">-nopromptcont</span></dt><dd class="dd-description">
Do not display the secondary prompt when waiting for continuation
lines in multi-line inputs. This should be used e.g. when running
<span class="c003">ocaml</span> in an <span class="c003">emacs</span> window.
</dd><dt class="dt-description"><span class="c006">-nostdlib</span></dt><dd class="dd-description">
Do not include the standard library directory in the list of
directories searched for source and compiled files.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-ppx</span> <span class="c009">command</span></span></dt><dd class="dd-description">
After parsing, pipe the abstract syntax tree through the preprocessor
<span class="c009">command</span>. The module <span class="c003">Ast_mapper</span>, described in
chapter <a href="#c%3Aparsinglib">27</a>:
<a href="compilerlibref/Ast_mapper.html"> <span class="c003">Ast_mapper</span> </a>
,
implements the external interface of a preprocessor.</dd><dt class="dt-description"><span class="c006">-principal</span></dt><dd class="dd-description">
Check information path during type-checking, to make sure that all
types are derived in a principal way. When using labelled arguments
and/or polymorphic methods, this flag is required to ensure future
versions of the compiler will be able to infer types correctly, even
if internal algorithms change.
All programs accepted in <span class="c003">-principal</span> mode are also accepted in the
default mode with equivalent types, but different binary signatures,
and this may slow down type checking; yet it is a good idea to
use it once before publishing source code.</dd><dt class="dt-description"><span class="c006">-rectypes</span></dt><dd class="dd-description">
Allow arbitrary recursive types during type-checking. By default,
only recursive types where the recursion goes through an object type
are supported.</dd><dt class="dt-description"><span class="c006">-safe-string</span></dt><dd class="dd-description">
Enforce the separation between types <span class="c003">string</span> and <span class="c003">bytes</span>,
thereby making strings read-only. This is the default.</dd><dt class="dt-description"><span class="c006">-short-paths</span></dt><dd class="dd-description">
When a type is visible under several module-paths, use the shortest
one when printing the type’s name in inferred interfaces and error and
warning messages. Identifier names starting with an underscore <span class="c003">_</span> or
containing double underscores <span class="c003">__</span> incur a penalty of +10 when computing
their length.</dd><dt class="dt-description"><span class="c006">-stdin</span></dt><dd class="dd-description">
Read the standard input as a script file rather than starting an
interactive session.
</dd><dt class="dt-description"><span class="c006">-strict-sequence</span></dt><dd class="dd-description">
Force the left-hand part of each sequence to have type unit.</dd><dt class="dt-description"><span class="c006">-strict-formats</span></dt><dd class="dd-description">
Reject invalid formats that were accepted in legacy format
implementations. You should use this flag to detect and fix such
invalid formats, as they will be rejected by future OCaml versions.</dd><dt class="dt-description"><span class="c006">-unsafe</span></dt><dd class="dd-description">
Turn bound checking off for array and string accesses (the <span class="c003">v.(i)</span> and
<span class="c003">s.[i]</span> constructs). Programs compiled with <span class="c003">-unsafe</span> are therefore
 faster, but unsafe: anything can happen if the program
accesses an array or string outside of its bounds.
</dd><dt class="dt-description"><span class="c006">-unsafe-string</span></dt><dd class="dd-description">
Identify the types <span class="c003">string</span> and <span class="c003">bytes</span>, thereby making strings writable.
This is intended for compatibility with old source code and should not
be used with new software.</dd><dt class="dt-description"><span class="c006">-v</span></dt><dd class="dd-description">
Print the version number of the compiler and the location of the
standard library directory, then exit.</dd><dt class="dt-description"><span class="c006">-verbose</span></dt><dd class="dd-description">
Print all external commands before they are executed,


Useful to debug C library problems.</dd><dt class="dt-description"><span class="c006">-version</span></dt><dd class="dd-description">
Print version string and exit.</dd><dt class="dt-description"><span class="c006">-vnum</span></dt><dd class="dd-description">
Print short version number and exit.</dd><dt class="dt-description"><span class="c006">-no-version</span></dt><dd class="dd-description">
Do not print the version banner at startup.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-w</span> <span class="c009">warning-list</span></span></dt><dd class="dd-description">
Enable, disable, or mark as fatal the warnings specified by the argument
<span class="c009">warning-list</span>.
Each warning can be <em>enabled</em> or <em>disabled</em>, and each warning
can be <em>fatal</em> or <em>non-fatal</em>.
If a warning is disabled, it isn’t displayed and doesn’t affect
compilation in any way (even if it is fatal). If a warning is
enabled, it is displayed normally by the compiler whenever the source
code triggers it. If it is enabled and fatal, the compiler will also
stop with an error after displaying it.<p>The <span class="c009">warning-list</span> argument is a sequence of warning specifiers,
with no separators between them. A warning specifier is one of the
following:</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">+</span><span class="c009">num</span></span></dt><dd class="dd-description"> Enable warning number <span class="c009">num</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-</span><span class="c009">num</span></span></dt><dd class="dd-description"> Disable warning number <span class="c009">num</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">@</span><span class="c009">num</span></span></dt><dd class="dd-description"> Enable and mark as fatal warning number <span class="c009">num</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">+</span><span class="c009">num1</span>..<span class="c009">num2</span></span></dt><dd class="dd-description"> Enable warnings in the given range.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-</span><span class="c009">num1</span>..<span class="c009">num2</span></span></dt><dd class="dd-description"> Disable warnings in the given range.
</dd><dt class="dt-description"><span class="c013"><span class="c003">@</span><span class="c009">num1</span>..<span class="c009">num2</span></span></dt><dd class="dd-description"> Enable and mark as fatal warnings in
the given range.
</dd><dt class="dt-description"><span class="c013"><span class="c003">+</span><span class="c009">letter</span></span></dt><dd class="dd-description"> Enable the set of warnings corresponding to
<span class="c009">letter</span>. The letter may be uppercase or lowercase.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-</span><span class="c009">letter</span></span></dt><dd class="dd-description"> Disable the set of warnings corresponding to
<span class="c009">letter</span>. The letter may be uppercase or lowercase.
</dd><dt class="dt-description"><span class="c013"><span class="c003">@</span><span class="c009">letter</span></span></dt><dd class="dd-description"> Enable and mark as fatal the set of warnings
corresponding to <span class="c009">letter</span>. The letter may be uppercase or
lowercase.
</dd><dt class="dt-description"><span class="c011">uppercase-letter</span></dt><dd class="dd-description"> Enable the set of warnings corresponding
to <span class="c009">uppercase-letter</span>.
</dd><dt class="dt-description"><span class="c011">lowercase-letter</span></dt><dd class="dd-description"> Disable the set of warnings corresponding
to <span class="c009">lowercase-letter</span>.
</dd></dl><p>Warning numbers and letters which are out of the range of warnings
that are currently defined are ignored. The warnings are as follows.
</p><dl class="description"><dt class="dt-description">
<span class="c013">1</span></dt><dd class="dd-description"> Suspicious-looking start-of-comment mark.
</dd><dt class="dt-description"><span class="c013">2</span></dt><dd class="dd-description"> Suspicious-looking end-of-comment mark.
</dd><dt class="dt-description"><span class="c013">3</span></dt><dd class="dd-description"> Deprecated synonym for the ’deprecated’ alert.
</dd><dt class="dt-description"><span class="c013">4</span></dt><dd class="dd-description"> Fragile pattern matching: matching that will remain complete even
if additional constructors are added to one of the variant types
matched.
</dd><dt class="dt-description"><span class="c013">5</span></dt><dd class="dd-description"> Partially applied function: expression whose result has function
type and is ignored.
</dd><dt class="dt-description"><span class="c013">6</span></dt><dd class="dd-description"> Label omitted in function application.
</dd><dt class="dt-description"><span class="c013">7</span></dt><dd class="dd-description"> Method overridden.
</dd><dt class="dt-description"><span class="c013">8</span></dt><dd class="dd-description"> Partial match: missing cases in pattern-matching.
</dd><dt class="dt-description"><span class="c013">9</span></dt><dd class="dd-description"> Missing fields in a record pattern.
</dd><dt class="dt-description"><span class="c013">10</span></dt><dd class="dd-description"> Expression on the left-hand side of a sequence that doesn’t have type
<span class="c003">unit</span> (and that is not a function, see warning number 5).
</dd><dt class="dt-description"><span class="c013">11</span></dt><dd class="dd-description"> Redundant case in a pattern matching (unused match case).
</dd><dt class="dt-description"><span class="c013">12</span></dt><dd class="dd-description"> Redundant sub-pattern in a pattern-matching.
</dd><dt class="dt-description"><span class="c013">13</span></dt><dd class="dd-description"> Instance variable overridden.
</dd><dt class="dt-description"><span class="c013">14</span></dt><dd class="dd-description"> Illegal backslash escape in a string constant.
</dd><dt class="dt-description"><span class="c013">15</span></dt><dd class="dd-description"> Private method made public implicitly.
</dd><dt class="dt-description"><span class="c013">16</span></dt><dd class="dd-description"> Unerasable optional argument.
</dd><dt class="dt-description"><span class="c013">17</span></dt><dd class="dd-description"> Undeclared virtual method.
</dd><dt class="dt-description"><span class="c013">18</span></dt><dd class="dd-description"> Non-principal type.
</dd><dt class="dt-description"><span class="c013">19</span></dt><dd class="dd-description"> Type without principality.
</dd><dt class="dt-description"><span class="c013">20</span></dt><dd class="dd-description"> Unused function argument.
</dd><dt class="dt-description"><span class="c013">21</span></dt><dd class="dd-description"> Non-returning statement.
</dd><dt class="dt-description"><span class="c013">22</span></dt><dd class="dd-description"> Preprocessor warning.
</dd><dt class="dt-description"><span class="c013">23</span></dt><dd class="dd-description"> Useless record <span class="c003">with</span> clause.
</dd><dt class="dt-description"><span class="c013">24</span></dt><dd class="dd-description"> Bad module name: the source file name is not a valid OCaml module name.
</dd><dt class="dt-description"><span class="c013">25</span></dt><dd class="dd-description"> Deprecated: now part of warning 8.
</dd><dt class="dt-description"><span class="c013">26</span></dt><dd class="dd-description"> Suspicious unused variable: unused variable that is bound
with <span class="c003">let</span> or <span class="c003">as</span>, and doesn’t start with an underscore (<span class="c003">_</span>)
character.
</dd><dt class="dt-description"><span class="c013">27</span></dt><dd class="dd-description"> Innocuous unused variable: unused variable that is not bound with
<span class="c003">let</span> nor <span class="c003">as</span>, and doesn’t start with an underscore (<span class="c003">_</span>)
character.
</dd><dt class="dt-description"><span class="c013">28</span></dt><dd class="dd-description"> Wildcard pattern given as argument to a constant constructor.
</dd><dt class="dt-description"><span class="c013">29</span></dt><dd class="dd-description"> Unescaped end-of-line in a string constant (non-portable code).
</dd><dt class="dt-description"><span class="c013">30</span></dt><dd class="dd-description"> Two labels or constructors of the same name are defined in two
mutually recursive types.
</dd><dt class="dt-description"><span class="c013">31</span></dt><dd class="dd-description"> A module is linked twice in the same executable.
</dd><dt class="dt-description"><span class="c013">32</span></dt><dd class="dd-description"> Unused value declaration.
</dd><dt class="dt-description"><span class="c013">33</span></dt><dd class="dd-description"> Unused open statement.
</dd><dt class="dt-description"><span class="c013">34</span></dt><dd class="dd-description"> Unused type declaration.
</dd><dt class="dt-description"><span class="c013">35</span></dt><dd class="dd-description"> Unused for-loop index.
</dd><dt class="dt-description"><span class="c013">36</span></dt><dd class="dd-description"> Unused ancestor variable.
</dd><dt class="dt-description"><span class="c013">37</span></dt><dd class="dd-description"> Unused constructor.
</dd><dt class="dt-description"><span class="c013">38</span></dt><dd class="dd-description"> Unused extension constructor.
</dd><dt class="dt-description"><span class="c013">39</span></dt><dd class="dd-description"> Unused rec flag.
</dd><dt class="dt-description"><span class="c013">40</span></dt><dd class="dd-description"> Constructor or label name used out of scope.
</dd><dt class="dt-description"><span class="c013">41</span></dt><dd class="dd-description"> Ambiguous constructor or label name.
</dd><dt class="dt-description"><span class="c013">42</span></dt><dd class="dd-description"> Disambiguated constructor or label name (compatibility warning).
</dd><dt class="dt-description"><span class="c013">43</span></dt><dd class="dd-description"> Nonoptional label applied as optional.
</dd><dt class="dt-description"><span class="c013">44</span></dt><dd class="dd-description"> Open statement shadows an already defined identifier.
</dd><dt class="dt-description"><span class="c013">45</span></dt><dd class="dd-description"> Open statement shadows an already defined label or constructor.
</dd><dt class="dt-description"><span class="c013">46</span></dt><dd class="dd-description"> Error in environment variable.
</dd><dt class="dt-description"><span class="c013">47</span></dt><dd class="dd-description"> Illegal attribute payload.
</dd><dt class="dt-description"><span class="c013">48</span></dt><dd class="dd-description"> Implicit elimination of optional arguments.
</dd><dt class="dt-description"><span class="c013">49</span></dt><dd class="dd-description"> Absent cmi file when looking up module alias.
</dd><dt class="dt-description"><span class="c013">50</span></dt><dd class="dd-description"> Unexpected documentation comment.
</dd><dt class="dt-description"><span class="c013">51</span></dt><dd class="dd-description"> Warning on non-tail calls if @tailcall present.
</dd><dt class="dt-description"><span class="c013">52 (see </span><a href="#ss%3Awarn52"><span class="c013">9.5.2</span></a><span class="c013">)</span></dt><dd class="dd-description"> Fragile constant pattern.
</dd><dt class="dt-description"><span class="c013">53</span></dt><dd class="dd-description"> Attribute cannot appear in this context.
</dd><dt class="dt-description"><span class="c013">54</span></dt><dd class="dd-description"> Attribute used more than once on an expression.
</dd><dt class="dt-description"><span class="c013">55</span></dt><dd class="dd-description"> Inlining impossible.
</dd><dt class="dt-description"><span class="c013">56</span></dt><dd class="dd-description"> Unreachable case in a pattern-matching (based on type information).
</dd><dt class="dt-description"><span class="c013">57 (see </span><a href="#ss%3Awarn57"><span class="c013">9.5.3</span></a><span class="c013">)</span></dt><dd class="dd-description"> Ambiguous or-pattern variables under guard.
</dd><dt class="dt-description"><span class="c013">58</span></dt><dd class="dd-description"> Missing cmx file.
</dd><dt class="dt-description"><span class="c013">59</span></dt><dd class="dd-description"> Assignment to non-mutable value.
</dd><dt class="dt-description"><span class="c013">60</span></dt><dd class="dd-description"> Unused module declaration.
</dd><dt class="dt-description"><span class="c013">61</span></dt><dd class="dd-description"> Unboxable type in primitive declaration.
</dd><dt class="dt-description"><span class="c013">62</span></dt><dd class="dd-description"> Type constraint on GADT type declaration.
</dd><dt class="dt-description"><span class="c013">63</span></dt><dd class="dd-description"> Erroneous printed signature.
</dd><dt class="dt-description"><span class="c013">64</span></dt><dd class="dd-description"> -unsafe used with a preprocessor returning a syntax tree.
</dd><dt class="dt-description"><span class="c013">65</span></dt><dd class="dd-description"> Type declaration defining a new ’()’ constructor.
</dd><dt class="dt-description"><span class="c013">66</span></dt><dd class="dd-description"> Unused open! statement.
</dd><dt class="dt-description"><span class="c013">67</span></dt><dd class="dd-description"> Unused functor parameter.
</dd><dt class="dt-description"><span class="c013">A</span></dt><dd class="dd-description"> all warnings
</dd><dt class="dt-description"><span class="c013">C</span></dt><dd class="dd-description"> warnings 1, 2.
</dd><dt class="dt-description"><span class="c013">D</span></dt><dd class="dd-description"> Alias for warning 3.
</dd><dt class="dt-description"><span class="c013">E</span></dt><dd class="dd-description"> Alias for warning 4.
</dd><dt class="dt-description"><span class="c013">F</span></dt><dd class="dd-description"> Alias for warning 5.
</dd><dt class="dt-description"><span class="c013">K</span></dt><dd class="dd-description"> warnings 32, 33, 34, 35, 36, 37, 38, 39.
</dd><dt class="dt-description"><span class="c013">L</span></dt><dd class="dd-description"> Alias for warning 6.
</dd><dt class="dt-description"><span class="c013">M</span></dt><dd class="dd-description"> Alias for warning 7.
</dd><dt class="dt-description"><span class="c013">P</span></dt><dd class="dd-description"> Alias for warning 8.
</dd><dt class="dt-description"><span class="c013">R</span></dt><dd class="dd-description"> Alias for warning 9.
</dd><dt class="dt-description"><span class="c013">S</span></dt><dd class="dd-description"> Alias for warning 10.
</dd><dt class="dt-description"><span class="c013">U</span></dt><dd class="dd-description"> warnings 11, 12.
</dd><dt class="dt-description"><span class="c013">V</span></dt><dd class="dd-description"> Alias for warning 13.
</dd><dt class="dt-description"><span class="c013">X</span></dt><dd class="dd-description"> warnings 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 30.
</dd><dt class="dt-description"><span class="c013">Y</span></dt><dd class="dd-description"> Alias for warning 26.
</dd><dt class="dt-description"><span class="c013">Z</span></dt><dd class="dd-description"> Alias for warning 27.

</dd></dl><p>The default setting is <span class="c003">-w +a-4-6-7-9-27-29-32..42-44-45-48-50-60</span>.
It is displayed by <span class="c003"> -help</span>.
Note that warnings 5 and 10 are not always triggered, depending on
the internals of the type checker.</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-warn-error</span> <span class="c009">warning-list</span></span></dt><dd class="dd-description">
Mark as fatal the warnings specified in the argument <span class="c009">warning-list</span>.
The compiler will stop with an error when one of these warnings is
emitted. The <span class="c009">warning-list</span> has the same meaning as for
the <span class="c003">-w</span> option: a <span class="c003">+</span> sign (or an uppercase letter) marks the
corresponding warnings as fatal, a <span class="c003">-</span>
sign (or a lowercase letter) turns them back into non-fatal warnings,
and a <span class="c003">@</span> sign both enables and marks as fatal the corresponding
warnings.<p>Note: it is not recommended to use warning sets (i.e. letters) as
arguments to <span class="c003">-warn-error</span>
in production code, because this can break your build when future versions
of OCaml add some new warnings.</p><p>The default setting is <span class="c003">-warn-error -a+31</span> (only warning 31 is fatal).</p></dd><dt class="dt-description"><span class="c006">-warn-help</span></dt><dd class="dd-description">
Show the description of all available warning numbers.</dd><dt class="dt-description"><span class="c013"><span class="c003">-</span> <span class="c009">file</span></span></dt><dd class="dd-description">

Use <span class="c009">file</span> as a script file name, even when it starts with a
hyphen (-).</dd><dt class="dt-description"><span class="c013"><span class="c003">-help</span> or <span class="c003">--help</span></span></dt><dd class="dd-description">
Display a short usage summary and exit.</dd></dl><blockquote class="quote"><span class="c007">Unix:</span>  
The following environment variables are also consulted:
<dl class="description"><dt class="dt-description">
<span class="c006">OCAMLTOP_INCLUDE_PATH</span></dt><dd class="dd-description"> Additional directories to search for compiled
object code files (<span class="c003">.cmi</span>, <span class="c003">.cmo</span> and <span class="c003">.cma</span>). The specified directories are
considered from left to right, after the include directories specified on the
command line via <span class="c003">-I</span> have been searched. Available since OCaml 4.08.</dd><dt class="dt-description"><span class="c006">OCAMLTOP_UTF_8</span></dt><dd class="dd-description"> When printing string values, non-ascii bytes
(  &gt; <span class="c003">\0<span class="c009">x</span>7<span class="c009">E</span></span> ) are printed as decimal escape sequence if <span class="c003">OCAMLTOP_UTF_8</span> is
set to false. Otherwise, they are printed unescaped.</dd><dt class="dt-description"><span class="c006">TERM</span></dt><dd class="dd-description"> When printing error messages, the toplevel system
attempts to underline visually the location of the error. It
consults the <span class="c003">TERM</span> variable to determines the type of output terminal
and look up its capabilities in the terminal database.</dd><dt class="dt-description"><span class="c013"><span class="c003">XDG_CONFIG_HOME</span>, <span class="c003">HOME</span></span></dt><dd class="dd-description">
<span class="c003">.ocamlinit</span> lookup procedure (see above).
</dd></dl>
</blockquote>
<!--TOC section id="s:toplevel-directives" 10.2  Toplevel directives-->
<h2 class="section" id="s:toplevel-directives"><a class="section-anchor" href="#s:toplevel-directives" aria-hidden="true"></a>10.2  Toplevel directives</h2><!--SEC END --><p>The following directives control the toplevel behavior, load files in
memory, and trace program execution.</p><p><span class="c013">Note:</span> all directives start with a <span class="c003">#</span> (sharp) symbol. This <span class="c003">#</span>
must be typed before the directive, and must not be confused with the
<span class="c003">#</span> prompt displayed by the interactive loop. For instance,
typing <span class="c003">#quit;;</span> will exit the toplevel loop, but typing <span class="c003">quit;;</span>
will result in an “unbound value <span class="c003">quit</span>” error.</p><dl class="description"><dt class="dt-description">
<span class="c013">General</span></dt><dd class="dd-description">
<dl class="description"><dt class="dt-description">
<span class="c006">#help;;</span></dt><dd class="dd-description">
Prints a list of all available directives, with corresponding argument type
if appropriate.
</dd><dt class="dt-description"><span class="c006">#quit;;</span></dt><dd class="dd-description">
Exit the toplevel loop and terminate the <span class="c003">ocaml</span> command.
</dd></dl></dd><dt class="dt-description"><span class="c013">Loading codes</span></dt><dd class="dd-description">
<dl class="description"><dt class="dt-description"><span class="c013"><span class="c003">#cd "</span><span class="c009">dir-name</span><span class="c003">";;</span></span></dt><dd class="dd-description">
Change the current working directory.</dd><dt class="dt-description"><span class="c013"><span class="c003">#directory "</span><span class="c009">dir-name</span><span class="c003">";;</span></span></dt><dd class="dd-description">
Add the given directory to the list of directories searched for
source and compiled files.</dd><dt class="dt-description"><span class="c013"><span class="c003">#remove_directory "</span><span class="c009">dir-name</span><span class="c003">";;</span></span></dt><dd class="dd-description">
Remove the given directory from the list of directories searched for
source and compiled files. Do nothing if the list does not contain
the given directory.</dd><dt class="dt-description"><span class="c013"><span class="c003">#load "</span><span class="c009">file-name</span><span class="c003">";;</span></span></dt><dd class="dd-description">
Load in memory a bytecode object file (<span class="c003">.cmo</span> file) or library file
(<span class="c003">.cma</span> file) produced by the batch compiler <span class="c003">ocamlc</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">#load_rec "</span><span class="c009">file-name</span><span class="c003">";;</span></span></dt><dd class="dd-description">
Load in memory a bytecode object file (<span class="c003">.cmo</span> file) or library file
(<span class="c003">.cma</span> file) produced by the batch compiler <span class="c003">ocamlc</span>.
When loading an object file that depends on other modules
which have not been loaded yet, the .cmo files for these modules
are searched and loaded as well, recursively. The loading order
is not specified.</dd><dt class="dt-description"><span class="c013"><span class="c003">#use "</span><span class="c009">file-name</span><span class="c003">";;</span></span></dt><dd class="dd-description">
Read, compile and execute source phrases from the given file.
This is textual inclusion: phrases are processed just as if
they were typed on standard input. The reading of the file stops at
the first error encountered.</dd><dt class="dt-description"><span class="c013"><span class="c003">#use_output "</span><span class="c009">command</span><span class="c003">";;</span></span></dt><dd class="dd-description">
Execute a command and evaluate its output as if it had been captured
to a file and passed to <span class="c003">#use</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">#mod_use "</span><span class="c009">file-name</span><span class="c003">";;</span></span></dt><dd class="dd-description">
Similar to <span class="c003">#use</span> but also wrap the code into a top-level module of the
same name as capitalized file name without extensions, following
semantics of the compiler.
</dd></dl><p>For directives that take file names as arguments, if the given file
name specifies no directory, the file is searched in the following
directories:
</p><ol class="enumerate" type=1><li class="li-enumerate">
In script mode, the directory containing the script currently
executing; in interactive mode, the current working directory.
</li><li class="li-enumerate">Directories added with the <span class="c003">#directory</span> directive.
</li><li class="li-enumerate">Directories given on the command line with <span class="c003">-I</span> options.
</li><li class="li-enumerate">The standard library directory.
</li></ol></dd><dt class="dt-description"><span class="c013">Environment queries</span></dt><dd class="dd-description">
<dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">#show_class </span><span class="c009">class-path</span><span class="c003">;;</span></span></dt><dd class="dd-description">
</dd><dt class="dt-description"><span class="c013"><span class="c003">#show_class_type </span><span class="c009">class-path</span><span class="c003">;;</span></span></dt><dd class="dd-description">
</dd><dt class="dt-description"><span class="c013"><span class="c003">#show_exception </span><span class="c009">ident</span><span class="c003">;;</span></span></dt><dd class="dd-description">
</dd><dt class="dt-description"><span class="c013"><span class="c003">#show_module </span><span class="c009">module-path</span><span class="c003">;;</span></span></dt><dd class="dd-description">
</dd><dt class="dt-description"><span class="c013"><span class="c003">#show_module_type </span><span class="c009">modtype-path</span><span class="c003">;;</span></span></dt><dd class="dd-description">
</dd><dt class="dt-description"><span class="c013"><span class="c003">#show_type </span><span class="c009">typeconstr</span><span class="c003">;;</span></span></dt><dd class="dd-description">
</dd><dt class="dt-description"><span class="c013"><span class="c003">#show_val </span><span class="c009">value-path</span><span class="c003">;;</span></span></dt><dd class="dd-description">
Print the signature of the corresponding component.</dd><dt class="dt-description"><span class="c013"><span class="c003">#show </span><span class="c009">ident</span><span class="c003">;;</span></span></dt><dd class="dd-description">
Print the signatures of components with name <span class="c009">ident</span> in all the
above categories.
</dd></dl></dd><dt class="dt-description"><span class="c013">Pretty-printing</span></dt><dd class="dd-description">
<dl class="description"><dt class="dt-description"><span class="c013"><span class="c003">#install_printer </span><span class="c009">printer-name</span><span class="c003">;;</span></span></dt><dd class="dd-description">
This directive registers the function named <span class="c009">printer-name</span> (a
value path) as a printer for values whose types match the argument
type of the function. That is, the toplevel loop will call
<span class="c009">printer-name</span> when it has such a value to print.<p>The printing function <span class="c009">printer-name</span> should have type
<span class="c002"><span class="c003">Format.formatter</span> <span class="c003">-&gt;</span> <span class="c010">t</span> <span class="c003">-&gt;</span> <span class="c003">unit</span></span>, where <span class="c010">t</span> is the
type for the values to be printed, and should output its textual
representation for the value of type <span class="c010">t</span> on the given formatter,
using the functions provided by the <span class="c003">Format</span> library. For backward
compatibility, <span class="c009">printer-name</span> can also have type
<span class="c010">t</span> <span class="c002"><span class="c003">-&gt;</span> <span class="c003">unit</span></span> and should then output on the standard
formatter, but this usage is deprecated.</p></dd><dt class="dt-description"><span class="c013"><span class="c003">#print_depth </span><span class="c009">n</span><span class="c003">;;</span></span></dt><dd class="dd-description">
Limit the printing of values to a maximal depth of <span class="c009">n</span>.
The parts of values whose depth exceeds <span class="c009">n</span> are printed as <span class="c003">...</span>
(ellipsis).</dd><dt class="dt-description"><span class="c013"><span class="c003">#print_length </span><span class="c009">n</span><span class="c003">;;</span></span></dt><dd class="dd-description">
Limit the number of value nodes printed to at most <span class="c009">n</span>.
Remaining parts of values are printed as <span class="c003">...</span> (ellipsis).</dd><dt class="dt-description"><span class="c013"><span class="c003">#remove_printer </span><span class="c009">printer-name</span><span class="c003">;;</span></span></dt><dd class="dd-description">
Remove the named function from the table of toplevel printers.
</dd></dl></dd><dt class="dt-description"><span class="c013">Tracing</span></dt><dd class="dd-description">
<dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">#trace </span><span class="c009">function-name</span><span class="c003">;;</span></span></dt><dd class="dd-description">
After executing this directive, all calls to the function named
<span class="c009">function-name</span> will be “traced”. That is, the argument and the
result are displayed for each call, as well as the exceptions escaping
out of the function, raised either by the function itself or by
another function it calls. If the function is curried, each argument
is printed as it is passed to the function.</dd><dt class="dt-description"><span class="c013"><span class="c003">#untrace </span><span class="c009">function-name</span><span class="c003">;;</span></span></dt><dd class="dd-description">
Stop tracing the given function.</dd><dt class="dt-description"><span class="c006">#untrace_all;;</span></dt><dd class="dd-description">
Stop tracing all functions traced so far.
</dd></dl></dd><dt class="dt-description"><span class="c013">Compiler options</span></dt><dd class="dd-description">
<dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">#labels </span><span class="c009">bool</span><span class="c003">;;</span></span></dt><dd class="dd-description">
Ignore labels in function types if argument is <span class="c003">false</span>, or switch back
to default behaviour (commuting style) if argument is <span class="c003">true</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">#ppx  "</span><span class="c009">file-name</span><span class="c003">";;</span></span></dt><dd class="dd-description">
After parsing, pipe the abstract syntax tree through the preprocessor
command.</dd><dt class="dt-description"><span class="c013"><span class="c003">#principal </span><span class="c009">bool</span><span class="c003">;;</span></span></dt><dd class="dd-description">
If the argument is <span class="c003">true</span>, check information paths during
type-checking, to make sure that all types are derived in a principal
way. If the argument is <span class="c003">false</span>, do not check information paths.</dd><dt class="dt-description"><span class="c006">#rectypes;;</span></dt><dd class="dd-description">
Allow arbitrary recursive types during type-checking. Note: once
enabled, this option cannot be disabled because that would lead to
unsoundness of the type system.</dd><dt class="dt-description"><span class="c013"><span class="c003">#warn_error "</span><span class="c009">warning-list</span><span class="c003">";;</span></span></dt><dd class="dd-description">
Treat as errors the warnings enabled by the argument and as normal
warnings the warnings disabled by the argument.</dd><dt class="dt-description"><span class="c013"><span class="c003">#warnings "</span><span class="c009">warning-list</span><span class="c003">";;</span></span></dt><dd class="dd-description">
Enable or disable warnings according to the argument.</dd></dl></dd></dl>
<!--TOC section id="s:toplevel-modules" 10.3  The toplevel and the module system-->
<h2 class="section" id="s:toplevel-modules"><a class="section-anchor" href="#s:toplevel-modules" aria-hidden="true"></a>10.3  The toplevel and the module system</h2><!--SEC END --><p>Toplevel phrases can refer to identifiers defined in compilation units
with the same mechanisms as for separately compiled units: either by
using qualified names (<span class="c003">Modulename.localname</span>), or by using
the <span class="c003">open</span> construct and unqualified names (see section <a href="#s%3Anames">7.3</a>).</p><p>However, before referencing another compilation unit, an
implementation of that unit must be present in memory.
At start-up, the toplevel system contains implementations for all the
modules in the the standard library. Implementations for user modules
can be entered with the <span class="c003">#load</span> directive described above. Referencing
a unit for which no implementation has been provided
results in the error <span class="c003">Reference to undefined global `...'</span>.</p><p>Note that entering <span class="c003">open </span><span class="c009">Mod</span> merely accesses the compiled
interface (<span class="c003">.cmi</span> file) for <span class="c009">Mod</span>, but does not load the
implementation of <span class="c009">Mod</span>, and does not cause any error if no
implementation of <span class="c009">Mod</span> has been loaded. The error
“reference to undefined global <span class="c009">Mod</span>” will occur only when
executing a value or module definition that refers to <span class="c009">Mod</span>.</p>
<!--TOC section id="s:toplevel-common-errors" 10.4  Common errors-->
<h2 class="section" id="s:toplevel-common-errors"><a class="section-anchor" href="#s:toplevel-common-errors" aria-hidden="true"></a>10.4  Common errors</h2><!--SEC END --><p>This section describes and explains the most frequently encountered
error messages.</p><dl class="description"><dt class="dt-description"><span class="c013">Cannot find file <span class="c009">filename</span></span></dt><dd class="dd-description">
The named file could not be found in the current directory, nor in the
directories of the search path.<p>If <span class="c009">filename</span> has the format <span class="c009">mod</span><span class="c003">.cmi</span>, this
means you have referenced the compilation unit <span class="c009">mod</span>, but its
compiled interface could not be found. Fix: compile <span class="c009">mod</span><span class="c003">.mli</span> or
<span class="c009">mod</span><span class="c003">.ml</span> first, to create the compiled interface <span class="c009">mod</span><span class="c003">.cmi</span>.</p><p>If <span class="c009">filename</span> has the format <span class="c009">mod</span><span class="c003">.cmo</span>, this
means you are trying to load with <span class="c003">#load</span> a bytecode object file that
does not exist yet. Fix: compile <span class="c009">mod</span><span class="c003">.ml</span> first.</p><p>If your program spans several directories, this error can also appear
because you haven’t specified the directories to look into. Fix: use
the <span class="c003">#directory</span> directive to add the correct directories to the
search path.</p></dd><dt class="dt-description"><span class="c013">This expression has type </span><span class="c009">t</span><sub>1</sub><span class="c013">, but is used with type </span><span class="c009">t</span><sub>2</sub></dt><dd class="dd-description">
See section <a href="#s%3Acomp-errors">9.4</a>.</dd><dt class="dt-description"><span class="c013">Reference to undefined global <span class="c009">mod</span></span></dt><dd class="dd-description">
You have neglected to load in memory an implementation for a module
with <span class="c003">#load</span>. See section <a href="#s%3Atoplevel-modules">10.3</a> above.</dd></dl>
<!--TOC section id="s:custom-toplevel" 10.5  Building custom toplevel systems: <span class="c003">ocamlmktop</span>-->
<h2 class="section" id="s:custom-toplevel"><a class="section-anchor" href="#s:custom-toplevel" aria-hidden="true"></a>10.5  Building custom toplevel systems: <span class="c003">ocamlmktop</span></h2><!--SEC END --><p>The <span class="c003">ocamlmktop</span> command builds OCaml toplevels that
contain user code preloaded at start-up.</p><p>The <span class="c003">ocamlmktop</span> command takes as argument a set of <span class="c003">.cmo</span> and <span class="c003">.cma</span>
files, and links them with the object files that implement the OCaml toplevel.
The typical use is:
</p><pre>        ocamlmktop -o mytoplevel foo.cmo bar.cmo gee.cmo
</pre><p>This creates the bytecode file <span class="c003">mytoplevel</span>, containing the OCaml toplevel
system, plus the code from the three <span class="c003">.cmo</span>
files. This toplevel is directly executable and is started by:
</p><pre>        ./mytoplevel
</pre><p>This enters a regular toplevel loop, except that the code from
<span class="c003">foo.cmo</span>, <span class="c003">bar.cmo</span> and <span class="c003">gee.cmo</span> is already loaded in memory, just as
if you had typed:
</p><pre>        #load "foo.cmo";;
        #load "bar.cmo";;
        #load "gee.cmo";;
</pre><p>on entrance to the toplevel. The modules <span class="c003">Foo</span>, <span class="c003">Bar</span> and <span class="c003">Gee</span> are
not opened, though; you still have to do
</p><pre>        open Foo;;
</pre><p>yourself, if this is what you wish.</p>
<!--TOC subsection id="ss:ocamlmktop-options" 10.5.1  Options-->
<h3 class="subsection" id="ss:ocamlmktop-options"><a class="section-anchor" href="#ss:ocamlmktop-options" aria-hidden="true"></a>10.5.1  Options</h3><!--SEC END --><p>The following command-line options are recognized by <span class="c003">ocamlmktop</span>.</p><dl class="description"><dt class="dt-description"><span class="c013"><span class="c003">-cclib</span> <span class="c009">libname</span></span></dt><dd class="dd-description">
Pass the <span class="c003">-l</span><span class="c009">libname</span> option to the C linker when linking in
“custom runtime” mode. See the corresponding option for
<span class="c003">ocamlc</span>, in chapter <a href="#c%3Acamlc">9</a>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-ccopt</span> <span class="c009">option</span></span></dt><dd class="dd-description">
Pass the given option to the C compiler and linker, when linking in
“custom runtime” mode. See the corresponding option for
<span class="c003">ocamlc</span>, in chapter <a href="#c%3Acamlc">9</a>.</dd><dt class="dt-description"><span class="c006">-custom</span></dt><dd class="dd-description">
Link in “custom runtime” mode. See the corresponding option for
<span class="c003">ocamlc</span>, in chapter <a href="#c%3Acamlc">9</a>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-I</span> <span class="c009">directory</span></span></dt><dd class="dd-description">
Add the given directory to the list of directories searched for
compiled object code files (<span class="c003">.cmo</span> and <span class="c003">.cma</span>).</dd><dt class="dt-description"><span class="c013"><span class="c003">-o</span> <span class="c009">exec-file</span></span></dt><dd class="dd-description">
Specify the name of the toplevel file produced by the linker.
The default is <span class="c003">a.out</span>.</dd></dl>
<!--TOC section id="s:ocamlnat" 10.6  The native toplevel: <span class="c003">ocamlnat</span> (experimental)-->
<h2 class="section" id="s:ocamlnat"><a class="section-anchor" href="#s:ocamlnat" aria-hidden="true"></a>10.6  The native toplevel: <span class="c003">ocamlnat</span> (experimental)</h2><!--SEC END --><p><span class="c013">This section describes a tool that is not yet officially supported but may be found useful.</span></p><p>OCaml code executing in the traditional toplevel system uses the bytecode
interpreter. When increased performance is required, or for testing
programs that will only execute correctly when compiled to native code,
the <em>native toplevel</em> may be used instead.</p><p>For the majority of installations the native toplevel will not have been
installed along with the rest of the OCaml toolchain. In such circumstances
it will be necessary to build the OCaml distribution from source.
From the built source tree of the distribution you may use
<span class="c003">make natruntop</span> to build and execute a native toplevel. (Alternatively
<span class="c003">make ocamlnat</span> can be used, which just performs the build step.)</p><p>If the <span class="c003">make install</span> command is run after having built the native
toplevel then the <span class="c003">ocamlnat</span> program (either from the source or the
installation directory) may be invoked directly rather than using
<span class="c003">make natruntop</span>.

</p>
<!--TOC chapter id="sec305" Chapter 11  The runtime system (ocamlrun)-->
<h1 class="chapter" id="sec305">Chapter 11  The runtime system (ocamlrun)</h1><!--SEC END --><p> <a id="c:runtime"></a>
</p><!--NAME runtime.html-->
<p>The <span class="c003">ocamlrun</span> command executes bytecode files produced by the
linking phase of the <span class="c003">ocamlc</span> command.</p>
<!--TOC section id="s:ocamlrun-overview" 11.1  Overview-->
<h2 class="section" id="s:ocamlrun-overview"><a class="section-anchor" href="#s:ocamlrun-overview" aria-hidden="true"></a>11.1  Overview</h2><!--SEC END --><p>The <span class="c003">ocamlrun</span> command comprises three main parts: the bytecode
interpreter, that actually executes bytecode files; the memory
allocator and garbage collector; and a set of C functions that
implement primitive operations such as input/output.</p><p>The usage for <span class="c003">ocamlrun</span> is:
</p><pre>
        ocamlrun <span class="c009">options bytecode-executable arg</span><sub>1</sub> ... <span class="c009">arg</span><sub><span class="c009">n</span></sub>
</pre><p>
The first non-option argument is taken to be the name of the file
containing the executable bytecode. (That file is searched in the
executable path as well as in the current directory.) The remaining
arguments are passed to the OCaml program, in the string array
<span class="c003">Sys.argv</span>. Element 0 of this array is the name of the
bytecode executable file; elements 1 to <span class="c009">n</span> are the remaining
arguments <span class="c009">arg</span><sub>1</sub> to <span class="c009">arg</span><sub><span class="c009">n</span></sub>.</p><p>As mentioned in chapter <a href="#c%3Acamlc">9</a>, the bytecode executable files
produced by the <span class="c003">ocamlc</span> command are self-executable, and manage to
launch the <span class="c003">ocamlrun</span> command on themselves automatically. That is,
assuming <span class="c003">a.out</span> is a bytecode executable file,
</p><pre>
        a.out <span class="c009">arg</span><sub>1</sub> ... <span class="c009">arg</span><sub><span class="c009">n</span></sub>
</pre><p>
works exactly as
</p><pre>
        ocamlrun a.out <span class="c009">arg</span><sub>1</sub> ... <span class="c009">arg</span><sub><span class="c009">n</span></sub>
</pre><p>
Notice that it is not possible to pass options to <span class="c003">ocamlrun</span> when
invoking <span class="c003">a.out</span> directly.</p><blockquote class="quote"><span class="c007">Windows:</span>  
Under several versions of Windows, bytecode executable files are
self-executable only if their name ends in <span class="c003">.exe</span>. It is recommended
to always give <span class="c003">.exe</span> names to bytecode executables, e.g. compile
with <span class="c003">ocamlc -o myprog.exe ...</span> rather than <span class="c003">ocamlc -o myprog ...</span>.
</blockquote>
<!--TOC section id="s:ocamlrun-options" 11.2  Options-->
<h2 class="section" id="s:ocamlrun-options"><a class="section-anchor" href="#s:ocamlrun-options" aria-hidden="true"></a>11.2  Options</h2><!--SEC END --><p>
The following command-line options are recognized by <span class="c003">ocamlrun</span>.</p><dl class="description"><dt class="dt-description"><span class="c006">-b</span></dt><dd class="dd-description">
When the program aborts due to an uncaught exception, print a detailed
“back trace” of the execution, showing where the exception was
raised and which function calls were outstanding at this point. The
back trace is printed only if the bytecode executable contains
debugging information, i.e. was compiled and linked with the <span class="c003">-g</span>
option to <span class="c003">ocamlc</span> set. This is equivalent to setting the <span class="c003">b</span> flag
in the <span class="c003">OCAMLRUNPARAM</span> environment variable (see below).
</dd><dt class="dt-description"><span class="c013"><span class="c003">-I</span> <span class="c009">dir</span></span></dt><dd class="dd-description">
Search the directory <span class="c009">dir</span> for dynamically-loaded libraries,
in addition to the standard search path (see
section <a href="#s%3Aocamlrun-dllpath">11.3</a>).
</dd><dt class="dt-description"><span class="c006">-m</span></dt><dd class="dd-description">
Print the magic number of the bytecode executable given as argument
and exit.
</dd><dt class="dt-description"><span class="c006">-M</span></dt><dd class="dd-description">
Print the magic number expected by this version of the runtime and exit.
</dd><dt class="dt-description"><span class="c006">-p</span></dt><dd class="dd-description">
Print the names of the primitives known to this version of
<span class="c003">ocamlrun</span> and exit.
</dd><dt class="dt-description"><span class="c006">-v</span></dt><dd class="dd-description">
Direct the memory manager to print some progress messages on
standard error. This is equivalent to setting <span class="c003">v=63</span> in the
<span class="c003">OCAMLRUNPARAM</span> environment variable (see below).
</dd><dt class="dt-description"><span class="c006">-version</span></dt><dd class="dd-description">
Print version string and exit.
</dd><dt class="dt-description"><span class="c006">-vnum</span></dt><dd class="dd-description">
Print short version number and exit.</dd></dl><p>The following environment variables are also consulted:</p><dl class="description"><dt class="dt-description">
<span class="c006">CAML_LD_LIBRARY_PATH</span></dt><dd class="dd-description"> Additional directories to search for
dynamically-loaded libraries (see section <a href="#s%3Aocamlrun-dllpath">11.3</a>).</dd><dt class="dt-description"><span class="c006">OCAMLLIB</span></dt><dd class="dd-description"> The directory containing the OCaml standard
library. (If <span class="c003">OCAMLLIB</span> is not set, <span class="c003">CAMLLIB</span> will be used instead.)
Used to locate the <span class="c003">ld.conf</span> configuration file for
dynamic loading (see section <a href="#s%3Aocamlrun-dllpath">11.3</a>). If not set,
default to the library directory specified when compiling OCaml.</dd><dt class="dt-description"><span class="c006">OCAMLRUNPARAM</span></dt><dd class="dd-description"> Set the runtime system options
and garbage collection parameters.
(If <span class="c003">OCAMLRUNPARAM</span> is not set, <span class="c003">CAMLRUNPARAM</span> will be used instead.)
This variable must be a sequence of parameter specifications separated
by commas.
A parameter specification is an option letter followed by an <span class="c003">=</span>
sign, a decimal number (or an hexadecimal number prefixed by <span class="c003">0x</span>),
and an optional multiplier. The options are documented below;
the last six correspond to the fields of the
<span class="c003">control</span> record documented in
<a href="libref/Gc.html">Module <span class="c003">Gc</span></a>.
<dl class="description"><dt class="dt-description">
<span class="c013">b</span></dt><dd class="dd-description"> (backtrace) Trigger the printing of a stack backtrace
when an uncaught exception aborts the program.
This option takes no argument.
</dd><dt class="dt-description"><span class="c013">p</span></dt><dd class="dd-description"> (parser trace) Turn on debugging support for
<span class="c003">ocamlyacc</span>-generated parsers. When this option is on,
the pushdown automaton that executes the parsers prints a
trace of its actions. This option takes no argument.
</dd><dt class="dt-description"><span class="c013">R</span></dt><dd class="dd-description"> (randomize) Turn on randomization of all hash tables by default
(see
<a href="libref/Hashtbl.html">Module <span class="c003">Hashtbl</span></a>).
This option takes no argument.
</dd><dt class="dt-description"><span class="c013">h</span></dt><dd class="dd-description"> The initial size of the major heap (in words).
</dd><dt class="dt-description"><span class="c013">a</span></dt><dd class="dd-description"> (<span class="c003">allocation_policy</span>)
The policy used for allocating in the OCaml heap. Possible values
are <span class="c003">0</span> for the next-fit policy, <span class="c003">1</span> for the first-fit
policy, and <span class="c003">2</span> for the best-fit policy. Best-fit is still experimental,
but probably the best of the three. The default is <span class="c003">0</span> (next-fit).
See the Gc module documentation for details.
</dd><dt class="dt-description"><span class="c013">s</span></dt><dd class="dd-description"> (<span class="c003">minor_heap_size</span>) Size of the minor heap. (in words)
</dd><dt class="dt-description"><span class="c013">i</span></dt><dd class="dd-description"> (<span class="c003">major_heap_increment</span>) Default size increment for the
major heap. (in words)
</dd><dt class="dt-description"><span class="c013">o</span></dt><dd class="dd-description"> (<span class="c003">space_overhead</span>) The major GC speed setting.
See the Gc module documentation for details.
</dd><dt class="dt-description"><span class="c013">O</span></dt><dd class="dd-description"> (<span class="c003">max_overhead</span>) The heap compaction trigger setting.
</dd><dt class="dt-description"><span class="c013">l</span></dt><dd class="dd-description"> (<span class="c003">stack_limit</span>) The limit (in words) of the stack size. This is only
relevant to the byte-code runtime, as the native code runtime uses the
operating system’s stack.
</dd><dt class="dt-description"><span class="c013">v</span></dt><dd class="dd-description"> (<span class="c003">verbose</span>) What GC messages to print to stderr. This
is a sum of values selected from the following:
<dl class="description"><dt class="dt-description">
<span class="c013">1 (= 0x001)</span></dt><dd class="dd-description"> Start of major GC cycle.
</dd><dt class="dt-description"><span class="c013">2 (= 0x002)</span></dt><dd class="dd-description"> Minor collection and major GC slice.
</dd><dt class="dt-description"><span class="c013">4 (= 0x004)</span></dt><dd class="dd-description"> Growing and shrinking of the heap.
</dd><dt class="dt-description"><span class="c013">8 (= 0x008)</span></dt><dd class="dd-description"> Resizing of stacks and memory manager tables.
</dd><dt class="dt-description"><span class="c013">16 (= 0x010)</span></dt><dd class="dd-description"> Heap compaction.
</dd><dt class="dt-description"><span class="c013">32 (= 0x020)</span></dt><dd class="dd-description"> Change of GC parameters.
</dd><dt class="dt-description"><span class="c013">64 (= 0x040)</span></dt><dd class="dd-description"> Computation of major GC slice size.
</dd><dt class="dt-description"><span class="c013">128 (= 0x080)</span></dt><dd class="dd-description"> Calling of finalization functions
</dd><dt class="dt-description"><span class="c013">256 (= 0x100)</span></dt><dd class="dd-description"> Startup messages (loading the bytecode
executable file, resolving shared libraries).
</dd><dt class="dt-description"><span class="c013">512 (= 0x200)</span></dt><dd class="dd-description"> Computation of compaction-triggering condition.
</dd><dt class="dt-description"><span class="c013">1024 (= 0x400)</span></dt><dd class="dd-description"> Output GC statistics at program exit.
</dd></dl>
</dd><dt class="dt-description"><span class="c013">c</span></dt><dd class="dd-description"> (<span class="c003">cleanup_on_exit</span>) Shut the runtime down gracefully on exit (see
<span class="c003">caml_shutdown</span> in section <a href="#ss%3Ac-embedded-code">20.7.5</a>). The option also enables
pooling (as in <span class="c003">caml_startup_pooled</span>). This mode can be used to detect
leaks with a third-party memory debugger.
</dd><dt class="dt-description"><span class="c013">M</span></dt><dd class="dd-description"> (<span class="c003">custom_major_ratio</span>) Target ratio of floating garbage to
major heap size for out-of-heap memory held by custom values
(e.g. bigarrays) located in the major heap. The GC speed is adjusted
to try to use this much memory for dead values that are not yet
collected. Expressed as a percentage of major heap size. Default:
44. Note: this only applies to values allocated with
<span class="c003">caml_alloc_custom_mem</span>.
</dd><dt class="dt-description"><span class="c013">m</span></dt><dd class="dd-description"> (<span class="c003">custom_minor_ratio</span>) Bound on floating garbage for
out-of-heap memory
held by custom values in the minor heap. A minor GC is triggered
when this much memory is held by custom values located in the minor
heap. Expressed as a percentage of minor heap size. Default:
100. Note: this only applies to values allocated with
<span class="c003">caml_alloc_custom_mem</span>.
</dd><dt class="dt-description"><span class="c013">n</span></dt><dd class="dd-description"> (<span class="c003">custom_minor_max_size</span>) Maximum amount of out-of-heap
memory for each custom value allocated in the minor heap. When a custom
value is allocated on the minor heap and holds more than this many
bytes, only this value is counted against <span class="c003">custom_minor_ratio</span> and
the rest is directly counted against <span class="c003">custom_major_ratio</span>.
Default: 8192 bytes. Note:
this only applies to values allocated with <span class="c003">caml_alloc_custom_mem</span>.
</dd></dl>
The multiplier is <span class="c003">k</span>, <span class="c003">M</span>, or <span class="c003">G</span>, for multiplication by 2<sup>10</sup>,
2<sup>20</sup>, and 2<sup>30</sup> respectively.<p>If the option letter is not recognized, the whole parameter is ignored;
if the equal sign or the number is missing, the value is taken as 1;
if the multiplier is not recognized, it is ignored.</p><p>For example, on a 32-bit machine, under <span class="c003">bash</span> the command
</p><pre>        export OCAMLRUNPARAM='b,s=256k,v=0x015'
</pre><p> tells a subsequent <span class="c003">ocamlrun</span> to print backtraces for uncaught exceptions,
set its initial minor heap size to 1 megabyte and
print a message at the start of each major GC cycle, when the heap
size changes, and when compaction is triggered.</p></dd><dt class="dt-description"><span class="c006">CAMLRUNPARAM</span></dt><dd class="dd-description"> If <span class="c003">OCAMLRUNPARAM</span> is not found in the
environment, then <span class="c003">CAMLRUNPARAM</span> will be used instead. If
<span class="c003">CAMLRUNPARAM</span> is also not found, then the default values will be used.</dd><dt class="dt-description"><span class="c006">PATH</span></dt><dd class="dd-description"> List of directories searched to find the bytecode
executable file.
</dd></dl>
<!--TOC section id="s:ocamlrun-dllpath" 11.3  Dynamic loading of shared libraries-->
<h2 class="section" id="s:ocamlrun-dllpath"><a class="section-anchor" href="#s:ocamlrun-dllpath" aria-hidden="true"></a>11.3  Dynamic loading of shared libraries</h2><!--SEC END --><p>On platforms that support dynamic loading, <span class="c003">ocamlrun</span> can link
dynamically with C shared libraries (DLLs) providing additional C primitives
beyond those provided by the standard runtime system. The names for
these libraries are provided at link time as described in
section <a href="#ss%3Adynlink-c-code">20.1.4</a>), and recorded in the bytecode executable
file; <span class="c003">ocamlrun</span>, then, locates these libraries and resolves references
to their primitives when the bytecode executable program starts.</p><p>The <span class="c003">ocamlrun</span> command searches shared libraries in the following
directories, in the order indicated:
</p><ol class="enumerate" type=1><li class="li-enumerate">
Directories specified on the <span class="c003">ocamlrun</span> command line with the
<span class="c003">-I</span> option.
</li><li class="li-enumerate">Directories specified in the <span class="c003">CAML_LD_LIBRARY_PATH</span> environment
variable.
</li><li class="li-enumerate">Directories specified at link-time via the <span class="c003">-dllpath</span> option to
<span class="c003">ocamlc</span>. (These directories are recorded in the bytecode executable
file.)
</li><li class="li-enumerate">Directories specified in the file <span class="c003">ld.conf</span>. This file resides
in the OCaml standard library directory, and lists directory
names (one per line) to be searched. Typically, it contains only one
line naming the <span class="c003">stublibs</span> subdirectory of the OCaml standard
library directory. Users can add there the names of other directories
containing frequently-used shared libraries; however, for consistency
of installation, we recommend that shared libraries are installed
directly in the system <span class="c003">stublibs</span> directory, rather than adding lines
to the <span class="c003">ld.conf</span> file.
</li><li class="li-enumerate">Default directories searched by the system dynamic loader.
Under Unix, these generally include <span class="c003">/lib</span> and <span class="c003">/usr/lib</span>, plus the
directories listed in the file <span class="c003">/etc/ld.so.conf</span> and the environment
variable <span class="c003">LD_LIBRARY_PATH</span>. Under Windows, these include the Windows
system directories, plus the directories listed in the <span class="c003">PATH</span>
environment variable.
</li></ol>
<!--TOC section id="s:ocamlrun-common-errors" 11.4  Common errors-->
<h2 class="section" id="s:ocamlrun-common-errors"><a class="section-anchor" href="#s:ocamlrun-common-errors" aria-hidden="true"></a>11.4  Common errors</h2><!--SEC END --><p>This section describes and explains the most frequently encountered
error messages.</p><dl class="description"><dt class="dt-description"><span class="c013"><span class="c009">filename</span><span class="c003">: no such file or directory</span></span></dt><dd class="dd-description">
If <span class="c009">filename</span> is the name of a self-executable bytecode file, this
means that either that file does not exist, or that it failed to run
the <span class="c003">ocamlrun</span> bytecode interpreter on itself. The second possibility
indicates that OCaml has not been properly installed on your
system.</dd><dt class="dt-description"><span class="c006">Cannot exec ocamlrun</span></dt><dd class="dd-description">
(When launching a self-executable bytecode file.) The <span class="c003">ocamlrun</span>
could not be found in the executable path. Check that OCaml
has been properly installed on your system.</dd><dt class="dt-description"><span class="c006">Cannot find the bytecode file</span></dt><dd class="dd-description">
The file that <span class="c003">ocamlrun</span> is trying to execute (e.g. the file given as
first non-option argument to <span class="c003">ocamlrun</span>) either does not exist, or is
not a valid executable bytecode file.</dd><dt class="dt-description"><span class="c006">Truncated bytecode file</span></dt><dd class="dd-description">
The file that <span class="c003">ocamlrun</span> is trying to execute is not a valid executable
bytecode file. Probably it has been truncated or mangled since
created. Erase and rebuild it.</dd><dt class="dt-description"><span class="c006">Uncaught exception</span></dt><dd class="dd-description">
The program being executed contains a “stray” exception. That is,
it raises an exception at some point, and this exception is never
caught. This causes immediate termination of the program. The name of
the exception is printed, along with its string, byte sequence, and
integer arguments
(arguments of more complex types are not correctly printed).
To locate the context of the uncaught exception, compile the program
with the <span class="c003">-g</span> option and either run it again under the <span class="c003">ocamldebug</span>
debugger (see chapter <a href="#c%3Adebugger">17</a>), or run it with <span class="c003">ocamlrun -b</span>
or with the <span class="c003">OCAMLRUNPARAM</span> environment variable set to <span class="c003">b=1</span>.</dd><dt class="dt-description"><span class="c006">Out of memory</span></dt><dd class="dd-description">
The program being executed requires more memory than available. Either
the program builds excessively large data structures; or the program
contains too many nested function calls, and the stack overflows. In
some cases, your program is perfectly correct, it just requires more
memory than your machine provides. In other cases, the “out of
memory” message reveals an error in your program: non-terminating
recursive function, allocation of an excessively large array,
string or byte sequence, attempts to build an infinite list or other
data structure, …<p>To help you diagnose this error, run your program with the <span class="c003">-v</span> option
to <span class="c003">ocamlrun</span>, or with the <span class="c003">OCAMLRUNPARAM</span> environment variable set to
<span class="c003">v=63</span>. If it displays lots of “<span class="c003">Growing stack</span>…”
messages, this is probably a looping recursive function. If it
displays lots of “<span class="c003">Growing heap</span>…” messages, with the heap size
growing slowly, this is probably an attempt to construct a data
structure with too many (infinitely many?) cells. If it displays few
“<span class="c003">Growing heap</span>…” messages, but with a huge increment in the
heap size, this is probably an attempt to build an excessively large
array, string or byte sequence.</p></dd></dl>
<!--TOC chapter id="sec310" Chapter 12  Native-code compilation (ocamlopt)-->
<h1 class="chapter" id="sec310">Chapter 12  Native-code compilation (ocamlopt)</h1><!--SEC END --><p> <a id="c:nativecomp"></a>
</p><!--NAME native.html-->
<p>This chapter describes the OCaml high-performance
native-code compiler <span class="c003">ocamlopt</span>, which compiles OCaml source files to
native code object files and links these object files to produce
standalone executables.</p><p>The native-code compiler is only available on certain platforms.
It produces code that runs faster than the bytecode produced by
<span class="c003">ocamlc</span>, at the cost of increased compilation time and executable code
size. Compatibility with the bytecode compiler is extremely high: the
same source code should run identically when compiled with <span class="c003">ocamlc</span> and
<span class="c003">ocamlopt</span>.</p><p>It is not possible to mix native-code object files produced by <span class="c003">ocamlopt</span>
with bytecode object files produced by <span class="c003">ocamlc</span>: a program must be
compiled entirely with <span class="c003">ocamlopt</span> or entirely with <span class="c003">ocamlc</span>. Native-code
object files produced by <span class="c003">ocamlopt</span> cannot be loaded in the toplevel
system <span class="c003">ocaml</span>.</p>
<!--TOC section id="s:native-overview" 12.1  Overview of the compiler-->
<h2 class="section" id="s:native-overview"><a class="section-anchor" href="#s:native-overview" aria-hidden="true"></a>12.1  Overview of the compiler</h2><!--SEC END --><p>The <span class="c003">ocamlopt</span> command has a command-line interface very close to that
of <span class="c003">ocamlc</span>. It accepts the same types of arguments, and processes them
sequentially, after all options have been processed:</p><ul class="itemize"><li class="li-itemize">
Arguments ending in <span class="c003">.mli</span> are taken to be source files for
compilation unit interfaces. Interfaces specify the names exported by
compilation units: they declare value names with their types, define
public data types, declare abstract data types, and so on. From the
file <span class="c009">x</span><span class="c003">.mli</span>, the <span class="c003">ocamlopt</span> compiler produces a compiled interface
in the file <span class="c009">x</span><span class="c003">.cmi</span>. The interface produced is identical to that
produced by the bytecode compiler <span class="c003">ocamlc</span>.</li><li class="li-itemize">Arguments ending in <span class="c003">.ml</span> are taken to be source files for compilation
unit implementations. Implementations provide definitions for the
names exported by the unit, and also contain expressions to be
evaluated for their side-effects. From the file <span class="c009">x</span><span class="c003">.ml</span>, the <span class="c003">ocamlopt</span>
compiler produces two files: <span class="c009">x</span><span class="c003">.o</span>, containing native object code,
and <span class="c009">x</span><span class="c003">.cmx</span>, containing extra information for linking and
optimization of the clients of the unit. The compiled implementation
should always be referred to under the name <span class="c009">x</span><span class="c003">.cmx</span> (when given
a <span class="c003">.o</span> or <span class="c003">.obj</span> file, <span class="c003">ocamlopt</span> assumes that it contains code compiled from C,
not from OCaml).<p>The implementation is checked against the interface file <span class="c009">x</span><span class="c003">.mli</span>
(if it exists) as described in the manual for <span class="c003">ocamlc</span>
(chapter <a href="#c%3Acamlc">9</a>).</p></li><li class="li-itemize">Arguments ending in <span class="c003">.cmx</span> are taken to be compiled object code. These
files are linked together, along with the object files obtained
by compiling <span class="c003">.ml</span> arguments (if any), and the OCaml standard
library, to produce a native-code executable program. The order in
which <span class="c003">.cmx</span> and <span class="c003">.ml</span> arguments are presented on the command line is
relevant: compilation units are initialized in that order at
run-time, and it is a link-time error to use a component of a unit
before having initialized it. Hence, a given <span class="c009">x</span><span class="c003">.cmx</span> file must come
before all <span class="c003">.cmx</span> files that refer to the unit <span class="c009">x</span>.</li><li class="li-itemize">Arguments ending in <span class="c003">.cmxa</span> are taken to be libraries of object code.
Such a library packs in two files (<span class="c009">lib</span><span class="c003">.cmxa</span> and <span class="c009">lib</span><span class="c003">.a</span>/<span class="c003">.lib</span>)
a set of object files (<span class="c003">.cmx</span> and <span class="c003">.o</span>/<span class="c003">.obj</span> files). Libraries are build with
<span class="c003">ocamlopt -a</span> (see the description of the <span class="c003">-a</span> option below). The object
files contained in the library are linked as regular <span class="c003">.cmx</span> files (see
above), in the order specified when the library was built. The only
difference is that if an object file contained in a library is not
referenced anywhere in the program, then it is not linked in.</li><li class="li-itemize">Arguments ending in <span class="c003">.c</span> are passed to the C compiler, which generates
a <span class="c003">.o</span>/<span class="c003">.obj</span> object file. This object file is linked with the program.</li><li class="li-itemize">Arguments ending in <span class="c003">.o</span>, <span class="c003">.a</span> or <span class="c003">.so</span> (<span class="c003">.obj</span>, <span class="c003">.lib</span> and <span class="c003">.dll</span>
under Windows) are assumed to be C object files and
libraries. They are linked with the program.</li></ul><p>The output of the linking phase is a regular Unix or Windows
executable file. It does not need <span class="c003">ocamlrun</span> to run.</p><p>The compiler is able to emit some information on its internal stages.
It can output <span class="c003">.cmt</span> files for the implementation of the compilation unit
and <span class="c003">.cmti</span> for signatures if the option <span class="c003">-bin-annot</span> is passed to it (see the
description of <span class="c003">-bin-annot</span> below).
Each such file contains a typed abstract syntax tree (AST), that is produced
during the type checking procedure. This tree contains all available information
about the location and the specific type of each term in the source file.
The AST is partial if type checking was unsuccessful.</p><p>These <span class="c003">.cmt</span> and <span class="c003">.cmti</span> files are typically useful for code inspection tools.</p>
<!--TOC section id="s:native-options" 12.2  Options-->
<h2 class="section" id="s:native-options"><a class="section-anchor" href="#s:native-options" aria-hidden="true"></a>12.2  Options</h2><!--SEC END --><p>The following command-line options are recognized by <span class="c003">ocamlopt</span>.
The options <span class="c003">-pack</span>, <span class="c003">-a</span>, <span class="c003">-shared</span>, <span class="c003">-c</span> and <span class="c003">-output-obj</span> are mutually
exclusive.</p><dl class="description"><dt class="dt-description">
<span class="c006">-a</span></dt><dd class="dd-description">
Build a library(<span class="c003">.cmxa</span> and <span class="c003">.a</span>/<span class="c003">.lib</span> files)
with the object files (<span class="c003">.cmx</span> and <span class="c003">.o</span>/<span class="c003">.obj</span> files)
given on the command line, instead of linking them into an executable file.
The name of the library must be set with the <span class="c003">-o</span> option.<p>If <span class="c003">-cclib</span> or <span class="c003">-ccopt</span> options are passed on the command
line, these options are stored in the resulting <span class="c003">.cmxa</span>library. Then,
linking with this library automatically adds back the 
<span class="c003">-cclib</span> and <span class="c003">-ccopt</span> options as if they had been provided on the
command line, unless the <span class="c003">-noautolink</span> option is given.
</p></dd><dt class="dt-description"><span class="c006">-absname</span></dt><dd class="dd-description">
Force error messages to show absolute paths for file names.</dd><dt class="dt-description"><span class="c006">-annot</span></dt><dd class="dd-description">
Deprecated since OCaml 4.11. Please use <span class="c003">-bin-annot</span> instead.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-args</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Read additional newline-terminated command line arguments from <span class="c009">filename</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-args0</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Read additional null character terminated command line arguments from
<span class="c009">filename</span>.
</dd><dt class="dt-description"><span class="c006">-bin-annot</span></dt><dd class="dd-description">
Dump detailed information about the compilation (types, bindings,
tail-calls, etc) in binary format. The information for file <span class="c009">src</span><span class="c003">.ml</span>
(resp. <span class="c009">src</span><span class="c003">.mli</span>) is put into file <span class="c009">src</span><span class="c003">.cmt</span>
(resp. <span class="c009">src</span><span class="c003">.cmti</span>). In case of a type error, dump
all the information inferred by the type-checker before the error.
The <span class="c003">*.cmt</span> and <span class="c003">*.cmti</span> files produced by <span class="c003">-bin-annot</span> contain
more information and are much more compact than the files produced by
<span class="c003">-annot</span>.
</dd><dt class="dt-description"><span class="c006">-c</span></dt><dd class="dd-description">
Compile only. Suppress the linking phase of the
compilation. Source code files are turned into compiled files, but no
executable file is produced. This option is useful to
compile modules separately.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-cc</span> <span class="c009">ccomp</span></span></dt><dd class="dd-description">
Use <span class="c009">ccomp</span> as the C linker called to build the final executable 

and as the C compiler for compiling <span class="c003">.c</span> source files.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-cclib</span> <span class="c003">-l</span><span class="c009">libname</span></span></dt><dd class="dd-description">
Pass the <span class="c003">-l</span><span class="c009">libname</span> option to the  linker
.
This causes the given C library to be linked with the program.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-ccopt</span> <span class="c009">option</span></span></dt><dd class="dd-description">
Pass the given option to the C compiler and linker.
For instance,<span class="c003">-ccopt -L</span><span class="c009">dir</span> causes the C linker to search for C libraries in
directory <span class="c009">dir</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-color</span> <span class="c009">mode</span></span></dt><dd class="dd-description">
Enable or disable colors in compiler messages (especially warnings and errors).
The following modes are supported:
<dl class="description"><dt class="dt-description">
<span class="c006">auto</span></dt><dd class="dd-description"> use heuristics to enable colors only if the output supports them
(an ANSI-compatible tty terminal);
</dd><dt class="dt-description"><span class="c006">always</span></dt><dd class="dd-description"> enable colors unconditionally;
</dd><dt class="dt-description"><span class="c006">never</span></dt><dd class="dd-description"> disable color output.
</dd></dl>
The default setting is ’auto’, and the current heuristic
checks that the <span class="c003">TERM</span> environment variable exists and is
not empty or <span class="c003">dumb</span>, and that ’isatty(stderr)’ holds.<p>The environment variable <span class="c003">OCAML_COLOR</span> is considered if <span class="c003">-color</span> is not
provided. Its values are auto/always/never as above.
</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-error-style</span> <span class="c009">mode</span></span></dt><dd class="dd-description">
Control the way error messages and warnings are printed.
The following modes are supported:
<dl class="description"><dt class="dt-description">
<span class="c006">short</span></dt><dd class="dd-description"> only print the error and its location;
</dd><dt class="dt-description"><span class="c006">contextual</span></dt><dd class="dd-description"> like <span class="c003">short</span>, but also display the source code snippet
corresponding to the location of the error.
</dd></dl>
The default setting is <span class="c003">contextual</span>.<p>The environment variable <span class="c003">OCAML_ERROR_STYLE</span> is considered if <span class="c003">-error-style</span> is
not provided. Its values are short/contextual as above.
</p></dd><dt class="dt-description"><span class="c006">-compact</span></dt><dd class="dd-description">
Optimize the produced code for space rather than for time. This
results in slightly smaller but slightly slower programs. The default is to
optimize for speed.
</dd><dt class="dt-description"><span class="c006">-config</span></dt><dd class="dd-description">
Print the version number of <span class="c003">ocamlopt</span> and a detailed
summary of its configuration, then exit.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-config-var</span> <span class="c009">var</span></span></dt><dd class="dd-description">
Print the value of a specific configuration variable from the
<span class="c003">-config</span> output, then exit. If the variable does not exist, the exit
code is non-zero. This option is only available since OCaml 4.08,
so script authors should have a fallback for older versions.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-depend</span> <span class="c009">ocamldep-args</span></span></dt><dd class="dd-description">
Compute dependencies, as the <span class="c003">ocamldep</span> command would do. The remaining
arguments are interpreted as if they were given to the <span class="c003">ocamldep</span> command.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-for-pack</span> <span class="c009">module-path</span></span></dt><dd class="dd-description">
Generate an object file (<span class="c003">.cmx</span> and <span class="c003">.o</span>/<span class="c003">.obj</span> files)
that can later be included
as a sub-module (with the given access path) of a compilation unit
constructed with <span class="c003">-pack</span>. For instance,
<span class="c003">ocamlopt -for-pack P -c A.ml</span>
will generate <span class="c003">a..cmx</span> and <span class="c003">a.o</span> files that can
later be used with <span class="c003">ocamlopt -pack -o P.cmx a.cmx</span>.
Note: you can still pack a module that was compiled without
<span class="c003">-for-pack</span> but in this case exceptions will be printed with the wrong
names.
</dd><dt class="dt-description"><span class="c006">-g</span></dt><dd class="dd-description">
Add debugging information while compiling and linking. This option is
required in order to  produce stack backtraces when
the program terminates on an uncaught exception (see
section <a href="#s%3Aocamlrun-options">11.2</a>).
</dd><dt class="dt-description"><span class="c006">-i</span></dt><dd class="dd-description">
Cause the compiler to print all defined names (with their inferred
types or their definitions) when compiling an implementation (<span class="c003">.ml</span>
file). No compiled files (<span class="c003">.cmo</span> and <span class="c003">.cmi</span> files) are produced.
This can be useful to check the types inferred by the
compiler. Also, since the output follows the syntax of interfaces, it
can help in writing an explicit interface (<span class="c003">.mli</span> file) for a file:
just redirect the standard output of the compiler to a <span class="c003">.mli</span> file,
and edit that file to remove all declarations of unexported names.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-I</span> <span class="c009">directory</span></span></dt><dd class="dd-description">
Add the given directory to the list of directories searched for
compiled interface files (<span class="c003">.cmi</span>), compiled object code files (<span class="c003">.cmx</span>),
and libraries (<span class="c003">.cmxa</span>).


By default, the current directory is searched first, then the standard
library directory. Directories added with <span class="c003">-I</span> are searched after the
current directory, in the order in which they were given on the command line,
but before the standard library directory. See also option <span class="c003">-nostdlib</span>.<p>If the given directory starts with <span class="c003">+</span>, it is taken relative to the
standard library directory. For instance, <span class="c003">-I +unix</span> adds the
subdirectory <span class="c003">unix</span> of the standard library to the search path.</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-impl</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Compile the file <span class="c009">filename</span> as an implementation file, even if its
extension is not <span class="c003">.ml</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-inline</span> <span class="c009">n</span></span></dt><dd class="dd-description">
Set aggressiveness of inlining to <span class="c009">n</span>, where <span class="c009">n</span> is a positive
integer. Specifying <span class="c003">-inline 0</span> prevents all functions from being
inlined, except those whose body is smaller than the call site. Thus,
inlining causes no expansion in code size. The default aggressiveness,
<span class="c003">-inline 1</span>, allows slightly larger functions to be inlined, resulting
in a slight expansion in code size. Higher values for the <span class="c003">-inline</span>
option cause larger and larger functions to become candidate for
inlining, but can result in a serious increase in code size.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-intf</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Compile the file <span class="c009">filename</span> as an interface file, even if its
extension is not <span class="c003">.mli</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-intf-suffix</span> <span class="c009">string</span></span></dt><dd class="dd-description">
Recognize file names ending with <span class="c009">string</span> as interface files
(instead of the default <span class="c003">.mli</span>).
</dd><dt class="dt-description"><span class="c006">-labels</span></dt><dd class="dd-description">
Labels are not ignored in types, labels may be used in applications,
and labelled parameters can be given in any order. This is the default.</dd><dt class="dt-description"><span class="c006">-linkall</span></dt><dd class="dd-description">
Force all modules contained in libraries to be linked in. If this
flag is not given, unreferenced modules are not linked in. When
building a library (option <span class="c003">-a</span>), setting the <span class="c003">-linkall</span> option forces all
subsequent links of programs involving that library to link all the
modules contained in the library. When compiling a module (option
<span class="c003">-c</span>), setting the <span class="c003">-linkall</span> option ensures that this module will
always be linked if it is put in a library and this library is linked.
</dd><dt class="dt-description"><span class="c006">-linscan</span></dt><dd class="dd-description">
Use linear scan register allocation. Compiling with this allocator is faster
than with the usual graph coloring allocator, sometimes quite drastically so for
long functions and modules. On the other hand, the generated code can be a bit
slower.
</dd><dt class="dt-description"><span class="c006">-match-context-rows</span></dt><dd class="dd-description">
Set the number of rows of context used for optimization during
pattern matching compilation. The default value is 32. Lower values
cause faster compilation, but less optimized code. This advanced
option is meant for use in the event that a pattern-match-heavy
program leads to significant increases in compilation time.
</dd><dt class="dt-description"><span class="c006">-no-alias-deps</span></dt><dd class="dd-description">
Do not record dependencies for module aliases. See
section <a href="#s%3Amodule-alias">8.8</a> for more information.
</dd><dt class="dt-description"><span class="c006">-no-app-funct</span></dt><dd class="dd-description">
Deactivates the applicative behaviour of functors. With this option,
each functor application generates new types in its result and
applying the same functor twice to the same argument yields two
incompatible structures.</dd><dt class="dt-description"><span class="c006">-no-float-const-prop</span></dt><dd class="dd-description">
Deactivates the constant propagation for floating-point operations.
This option should be given if the program changes the float rounding
mode during its execution.
</dd><dt class="dt-description"><span class="c006">-noassert</span></dt><dd class="dd-description">
Do not compile assertion checks. Note that the special form
<span class="c003">assert false</span> is always compiled because it is typed specially.
This flag has no effect when linking already-compiled files.</dd><dt class="dt-description"><span class="c006">-noautolink</span></dt><dd class="dd-description">
When linking <span class="c003">.cmxa</span>libraries, ignore  <span class="c003">-cclib</span> and <span class="c003">-ccopt</span>
options potentially contained in the libraries (if these options were
given when building the libraries). This can be useful if a library
contains incorrect specifications of C libraries or C options; in this
case, during linking, set <span class="c003">-noautolink</span> and pass the correct C
libraries and options on the command line.
</dd><dt class="dt-description"><span class="c006">-nodynlink</span></dt><dd class="dd-description">
Allow the compiler to use some optimizations that are valid only for code
that is never dynlinked.
</dd><dt class="dt-description"><span class="c006">-nolabels</span></dt><dd class="dd-description">
Ignore non-optional labels in types. Labels cannot be used in
applications, and parameter order becomes strict.</dd><dt class="dt-description"><span class="c006">-nostdlib</span></dt><dd class="dd-description">
Do not automatically add the standard library directory to the list of
directories searched for compiled interface files (<span class="c003">.cmi</span>), compiled
object code files (<span class="c003">.cmx</span>), and libraries (<span class="c003">.cmxa</span>). See also option
<span class="c003">-I</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-o</span> <span class="c009">exec-file</span></span></dt><dd class="dd-description">
Specify the name of the output file produced by the
linker. The
default output name is <span class="c003">a.out</span> under Unix and <span class="c003">camlprog.exe</span> under
Windows. If the <span class="c003">-a</span> option is given, specify the name of the library
produced. If the <span class="c003">-pack</span> option is given, specify the name of the
packed object file produced. If the <span class="c003">-output-obj</span> option is given,
specify the name of the output file produced.
If the <span class="c003">-shared</span> option is given, specify the name of plugin
file produced.

</dd><dt class="dt-description"><span class="c006">-opaque</span></dt><dd class="dd-description">
When the native compiler compiles an implementation, by default it
produces a <span class="c003">.cmx</span> file containing information for cross-module
optimization. It also expects <span class="c003">.cmx</span> files to be present for the
dependencies of the currently compiled source, and uses them for
optimization. Since OCaml 4.03, the compiler will emit a warning if it
is unable to locate the <span class="c003">.cmx</span> file of one of those dependencies.<p>The <span class="c003">-opaque</span> option, available since 4.04, disables cross-module
optimization information for the currently compiled unit. When
compiling <span class="c003">.mli</span> interface, using <span class="c003">-opaque</span> marks the compiled <span class="c003">.cmi</span>
interface so that subsequent compilations of modules that depend on it
will not rely on the corresponding <span class="c003">.cmx</span> file, nor warn if it is
absent. When the native compiler compiles a <span class="c003">.ml</span> implementation,
using <span class="c003">-opaque</span> generates a <span class="c003">.cmx</span> that does not contain any
cross-module optimization information.</p><p>Using this option may degrade the quality of generated code, but it
reduces compilation time, both on clean and incremental
builds. Indeed, with the native compiler, when the implementation of
a compilation unit changes, all the units that depend on it may need
to be recompiled – because the cross-module information may have
changed. If the compilation unit whose implementation changed was
compiled with <span class="c003">-opaque</span>, no such recompilation needs to occur. This
option can thus be used, for example, to get faster edit-compile-test
feedback loops.
</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-open</span> <span class="c009">Module</span></span></dt><dd class="dd-description">
Opens the given module before processing the interface or
implementation files. If several <span class="c003">-open</span> options are given,
they are processed in order, just as if
the statements <span class="c003">open!</span> <span class="c009">Module1</span><span class="c003">;;</span> <span class="c003">...</span> <span class="c003">open!</span> <span class="c009">ModuleN</span><span class="c003">;;</span>
were added at the top of each file.
</dd><dt class="dt-description"><span class="c006">-output-obj</span></dt><dd class="dd-description">
Cause the linker to produce a C object file instead of
an executable file.
This is useful to wrap OCaml code as a C library,
callable from any C program. See chapter <a href="#c%3Aintf-c">20</a>,
section <a href="#ss%3Ac-embedded-code">20.7.5</a>. The name of the output object file
must be set with the <span class="c003">-o</span> option.
This option can also be used to produce a  compiled shared/dynamic library (<span class="c003">.so</span> extension, <span class="c003">.dll</span> under Windows).
</dd><dt class="dt-description"><span class="c006">-pack</span></dt><dd class="dd-description">
Build an object file (<span class="c003">.cmx</span> and <span class="c003">.o</span>/<span class="c003">.obj</span> files) and its associated compiled
interface (<span class="c003">.cmi</span>) that combines the <span class="c003">.cmx</span> object
files given on the command line, making them appear as sub-modules of
the output <span class="c003">.cmx</span> file. The name of the output <span class="c003">.cmx</span> file must be
given with the <span class="c003">-o</span> option. For instance,
<pre>        ocamlopt -pack -o P.cmx A.cmx B.cmx C.cmx
</pre>generates compiled files <span class="c003">P.cmx</span>, <span class="c003">P.o</span> and <span class="c003">P.cmi</span> describing a
compilation unit having three sub-modules <span class="c003">A</span>, <span class="c003">B</span> and <span class="c003">C</span>,
corresponding to the contents of the object files <span class="c003">A.cmx</span>, <span class="c003">B.cmx</span> and
<span class="c003">C.cmx</span>. These contents can be referenced as <span class="c003">P.A</span>, <span class="c003">P.B</span> and <span class="c003">P.C</span>
in the remainder of the program.<p>The <span class="c003">.cmx</span> object files being combined must have been compiled with
the appropriate <span class="c003">-for-pack</span> option. In the example above,
<span class="c003">A.cmx</span>, <span class="c003">B.cmx</span> and <span class="c003">C.cmx</span> must have been compiled with
<span class="c003">ocamlopt -for-pack P</span>.</p><p>Multiple levels of packing can be achieved by combining <span class="c003">-pack</span> with
<span class="c003">-for-pack</span>. Consider the following example:
</p><pre>        ocamlopt -for-pack P.Q -c A.ml
        ocamlopt -pack -o Q.cmx -for-pack P A.cmx
        ocamlopt -for-pack P -c B.ml
        ocamlopt -pack -o P.cmx Q.cmx B.cmx
</pre><p>The resulting <span class="c003">P.cmx</span> object file has sub-modules <span class="c003">P.Q</span>, <span class="c003">P.Q.A</span>
and <span class="c003">P.B</span>.
</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-pp</span> <span class="c009">command</span></span></dt><dd class="dd-description">
Cause the compiler to call the given <span class="c009">command</span> as a preprocessor
for each source file. The output of <span class="c009">command</span> is redirected to
an intermediate file, which is compiled. If there are no compilation
errors, the intermediate file is deleted afterwards.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-ppx</span> <span class="c009">command</span></span></dt><dd class="dd-description">
After parsing, pipe the abstract syntax tree through the preprocessor
<span class="c009">command</span>. The module <span class="c003">Ast_mapper</span>, described in
chapter <a href="#c%3Aparsinglib">27</a>:
<a href="compilerlibref/Ast_mapper.html"> <span class="c003">Ast_mapper</span> </a>
,
implements the external interface of a preprocessor.</dd><dt class="dt-description"><span class="c006">-principal</span></dt><dd class="dd-description">
Check information path during type-checking, to make sure that all
types are derived in a principal way. When using labelled arguments
and/or polymorphic methods, this flag is required to ensure future
versions of the compiler will be able to infer types correctly, even
if internal algorithms change.
All programs accepted in <span class="c003">-principal</span> mode are also accepted in the
default mode with equivalent types, but different binary signatures,
and this may slow down type checking; yet it is a good idea to
use it once before publishing source code.</dd><dt class="dt-description"><span class="c006">-rectypes</span></dt><dd class="dd-description">
Allow arbitrary recursive types during type-checking. By default,
only recursive types where the recursion goes through an object type
are supported.Note that once you have created an interface using this
flag, you must use it again for all dependencies.</dd><dt class="dt-description"><span class="c013"><span class="c003">-runtime-variant</span> <span class="c009">suffix</span></span></dt><dd class="dd-description">
Add the <span class="c009">suffix</span> string to the name of the runtime library used by
the program. Currently, only one such suffix is supported: <span class="c003">d</span>, and
only if the OCaml compiler was configured with option
<span class="c003">-with-debug-runtime</span>. This suffix gives the debug version of the
runtime, which is useful for debugging pointer problems in low-level
code such as C stubs.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-stop-after</span> <span class="c009">pass</span></span></dt><dd class="dd-description">
Stop compilation after the given compilation pass. The currently
supported passes are: <span class="c003">parsing</span>, <span class="c003">typing</span>.
</dd><dt class="dt-description"><span class="c006">-S</span></dt><dd class="dd-description">
Keep the assembly code produced during the compilation. The assembly
code for the source file <span class="c009">x</span><span class="c003">.ml</span> is saved in the file <span class="c009">x</span><span class="c003">.s</span>.
</dd><dt class="dt-description"><span class="c006">-shared</span></dt><dd class="dd-description">
Build a plugin (usually <span class="c003">.cmxs</span>) that can be dynamically loaded with
the <span class="c003">Dynlink</span> module. The name of the plugin must be
set with the <span class="c003">-o</span> option. A plugin can include a number of OCaml
modules and libraries, and extra native objects (<span class="c003">.o</span>, <span class="c003">.obj</span>, <span class="c003">.a</span>,
<span class="c003">.lib</span> files). Building native plugins is only supported for some
operating system. Under some systems (currently,
only Linux AMD 64), all the OCaml code linked in a plugin must have
been compiled without the <span class="c003">-nodynlink</span> flag. Some constraints might also
apply to the way the extra native objects have been compiled (under
Linux AMD 64, they must contain only position-independent code).
</dd><dt class="dt-description"><span class="c006">-safe-string</span></dt><dd class="dd-description">
Enforce the separation between types <span class="c003">string</span> and <span class="c003">bytes</span>,
thereby making strings read-only. This is the default.</dd><dt class="dt-description"><span class="c006">-short-paths</span></dt><dd class="dd-description">
When a type is visible under several module-paths, use the shortest
one when printing the type’s name in inferred interfaces and error and
warning messages. Identifier names starting with an underscore <span class="c003">_</span> or
containing double underscores <span class="c003">__</span> incur a penalty of +10 when computing
their length.</dd><dt class="dt-description"><span class="c006">-strict-sequence</span></dt><dd class="dd-description">
Force the left-hand part of each sequence to have type unit.</dd><dt class="dt-description"><span class="c006">-strict-formats</span></dt><dd class="dd-description">
Reject invalid formats that were accepted in legacy format
implementations. You should use this flag to detect and fix such
invalid formats, as they will be rejected by future OCaml versions.</dd><dt class="dt-description"><span class="c006">-unboxed-types</span></dt><dd class="dd-description">
When a type is unboxable (i.e. a record with a single argument or a
concrete datatype with a single constructor of one argument) it will
be unboxed unless annotated with <span class="c003">[@@ocaml.boxed]</span>.
</dd><dt class="dt-description"><span class="c006">-no-unboxed-types</span></dt><dd class="dd-description">
When a type is unboxable it will be boxed unless annotated with
<span class="c003">[@@ocaml.unboxed]</span>. This is the default.
</dd><dt class="dt-description"><span class="c006">-unsafe</span></dt><dd class="dd-description">
Turn bound checking off for array and string accesses (the <span class="c003">v.(i)</span> and
<span class="c003">s.[i]</span> constructs). Programs compiled with <span class="c003">-unsafe</span> are therefore
 faster, but unsafe: anything can happen if the program
accesses an array or string outside of its bounds.
Additionally, turn off the check for zero divisor in integer division
and modulus operations. With <span class="c003">-unsafe</span>, an integer division
(or modulus) by zero can halt the program or continue with an
unspecified result instead of raising a <span class="c003">Division_by_zero</span> exception.
</dd><dt class="dt-description"><span class="c006">-unsafe-string</span></dt><dd class="dd-description">
Identify the types <span class="c003">string</span> and <span class="c003">bytes</span>, thereby making strings writable.
This is intended for compatibility with old source code and should not
be used with new software.</dd><dt class="dt-description"><span class="c006">-v</span></dt><dd class="dd-description">
Print the version number of the compiler and the location of the
standard library directory, then exit.</dd><dt class="dt-description"><span class="c006">-verbose</span></dt><dd class="dd-description">
Print all external commands before they are executed,
in particular invocations of the assembler, C compiler, and linker.

Useful to debug C library problems.</dd><dt class="dt-description"><span class="c013"><span class="c003">-version</span> or <span class="c003">-vnum</span></span></dt><dd class="dd-description">
Print the version number of the compiler in short form (e.g. <span class="c003">3.11.0</span>),
then exit.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-w</span> <span class="c009">warning-list</span></span></dt><dd class="dd-description">
Enable, disable, or mark as fatal the warnings specified by the argument
<span class="c009">warning-list</span>.
Each warning can be <em>enabled</em> or <em>disabled</em>, and each warning
can be <em>fatal</em> or <em>non-fatal</em>.
If a warning is disabled, it isn’t displayed and doesn’t affect
compilation in any way (even if it is fatal). If a warning is
enabled, it is displayed normally by the compiler whenever the source
code triggers it. If it is enabled and fatal, the compiler will also
stop with an error after displaying it.<p>The <span class="c009">warning-list</span> argument is a sequence of warning specifiers,
with no separators between them. A warning specifier is one of the
following:</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">+</span><span class="c009">num</span></span></dt><dd class="dd-description"> Enable warning number <span class="c009">num</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-</span><span class="c009">num</span></span></dt><dd class="dd-description"> Disable warning number <span class="c009">num</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">@</span><span class="c009">num</span></span></dt><dd class="dd-description"> Enable and mark as fatal warning number <span class="c009">num</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">+</span><span class="c009">num1</span>..<span class="c009">num2</span></span></dt><dd class="dd-description"> Enable warnings in the given range.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-</span><span class="c009">num1</span>..<span class="c009">num2</span></span></dt><dd class="dd-description"> Disable warnings in the given range.
</dd><dt class="dt-description"><span class="c013"><span class="c003">@</span><span class="c009">num1</span>..<span class="c009">num2</span></span></dt><dd class="dd-description"> Enable and mark as fatal warnings in
the given range.
</dd><dt class="dt-description"><span class="c013"><span class="c003">+</span><span class="c009">letter</span></span></dt><dd class="dd-description"> Enable the set of warnings corresponding to
<span class="c009">letter</span>. The letter may be uppercase or lowercase.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-</span><span class="c009">letter</span></span></dt><dd class="dd-description"> Disable the set of warnings corresponding to
<span class="c009">letter</span>. The letter may be uppercase or lowercase.
</dd><dt class="dt-description"><span class="c013"><span class="c003">@</span><span class="c009">letter</span></span></dt><dd class="dd-description"> Enable and mark as fatal the set of warnings
corresponding to <span class="c009">letter</span>. The letter may be uppercase or
lowercase.
</dd><dt class="dt-description"><span class="c011">uppercase-letter</span></dt><dd class="dd-description"> Enable the set of warnings corresponding
to <span class="c009">uppercase-letter</span>.
</dd><dt class="dt-description"><span class="c011">lowercase-letter</span></dt><dd class="dd-description"> Disable the set of warnings corresponding
to <span class="c009">lowercase-letter</span>.
</dd></dl><p>Warning numbers and letters which are out of the range of warnings
that are currently defined are ignored. The warnings are as follows.
</p><dl class="description"><dt class="dt-description">
<span class="c013">1</span></dt><dd class="dd-description"> Suspicious-looking start-of-comment mark.
</dd><dt class="dt-description"><span class="c013">2</span></dt><dd class="dd-description"> Suspicious-looking end-of-comment mark.
</dd><dt class="dt-description"><span class="c013">3</span></dt><dd class="dd-description"> Deprecated synonym for the ’deprecated’ alert.
</dd><dt class="dt-description"><span class="c013">4</span></dt><dd class="dd-description"> Fragile pattern matching: matching that will remain complete even
if additional constructors are added to one of the variant types
matched.
</dd><dt class="dt-description"><span class="c013">5</span></dt><dd class="dd-description"> Partially applied function: expression whose result has function
type and is ignored.
</dd><dt class="dt-description"><span class="c013">6</span></dt><dd class="dd-description"> Label omitted in function application.
</dd><dt class="dt-description"><span class="c013">7</span></dt><dd class="dd-description"> Method overridden.
</dd><dt class="dt-description"><span class="c013">8</span></dt><dd class="dd-description"> Partial match: missing cases in pattern-matching.
</dd><dt class="dt-description"><span class="c013">9</span></dt><dd class="dd-description"> Missing fields in a record pattern.
</dd><dt class="dt-description"><span class="c013">10</span></dt><dd class="dd-description"> Expression on the left-hand side of a sequence that doesn’t have type
<span class="c003">unit</span> (and that is not a function, see warning number 5).
</dd><dt class="dt-description"><span class="c013">11</span></dt><dd class="dd-description"> Redundant case in a pattern matching (unused match case).
</dd><dt class="dt-description"><span class="c013">12</span></dt><dd class="dd-description"> Redundant sub-pattern in a pattern-matching.
</dd><dt class="dt-description"><span class="c013">13</span></dt><dd class="dd-description"> Instance variable overridden.
</dd><dt class="dt-description"><span class="c013">14</span></dt><dd class="dd-description"> Illegal backslash escape in a string constant.
</dd><dt class="dt-description"><span class="c013">15</span></dt><dd class="dd-description"> Private method made public implicitly.
</dd><dt class="dt-description"><span class="c013">16</span></dt><dd class="dd-description"> Unerasable optional argument.
</dd><dt class="dt-description"><span class="c013">17</span></dt><dd class="dd-description"> Undeclared virtual method.
</dd><dt class="dt-description"><span class="c013">18</span></dt><dd class="dd-description"> Non-principal type.
</dd><dt class="dt-description"><span class="c013">19</span></dt><dd class="dd-description"> Type without principality.
</dd><dt class="dt-description"><span class="c013">20</span></dt><dd class="dd-description"> Unused function argument.
</dd><dt class="dt-description"><span class="c013">21</span></dt><dd class="dd-description"> Non-returning statement.
</dd><dt class="dt-description"><span class="c013">22</span></dt><dd class="dd-description"> Preprocessor warning.
</dd><dt class="dt-description"><span class="c013">23</span></dt><dd class="dd-description"> Useless record <span class="c003">with</span> clause.
</dd><dt class="dt-description"><span class="c013">24</span></dt><dd class="dd-description"> Bad module name: the source file name is not a valid OCaml module name.
</dd><dt class="dt-description"><span class="c013">25</span></dt><dd class="dd-description"> Deprecated: now part of warning 8.
</dd><dt class="dt-description"><span class="c013">26</span></dt><dd class="dd-description"> Suspicious unused variable: unused variable that is bound
with <span class="c003">let</span> or <span class="c003">as</span>, and doesn’t start with an underscore (<span class="c003">_</span>)
character.
</dd><dt class="dt-description"><span class="c013">27</span></dt><dd class="dd-description"> Innocuous unused variable: unused variable that is not bound with
<span class="c003">let</span> nor <span class="c003">as</span>, and doesn’t start with an underscore (<span class="c003">_</span>)
character.
</dd><dt class="dt-description"><span class="c013">28</span></dt><dd class="dd-description"> Wildcard pattern given as argument to a constant constructor.
</dd><dt class="dt-description"><span class="c013">29</span></dt><dd class="dd-description"> Unescaped end-of-line in a string constant (non-portable code).
</dd><dt class="dt-description"><span class="c013">30</span></dt><dd class="dd-description"> Two labels or constructors of the same name are defined in two
mutually recursive types.
</dd><dt class="dt-description"><span class="c013">31</span></dt><dd class="dd-description"> A module is linked twice in the same executable.
</dd><dt class="dt-description"><span class="c013">32</span></dt><dd class="dd-description"> Unused value declaration.
</dd><dt class="dt-description"><span class="c013">33</span></dt><dd class="dd-description"> Unused open statement.
</dd><dt class="dt-description"><span class="c013">34</span></dt><dd class="dd-description"> Unused type declaration.
</dd><dt class="dt-description"><span class="c013">35</span></dt><dd class="dd-description"> Unused for-loop index.
</dd><dt class="dt-description"><span class="c013">36</span></dt><dd class="dd-description"> Unused ancestor variable.
</dd><dt class="dt-description"><span class="c013">37</span></dt><dd class="dd-description"> Unused constructor.
</dd><dt class="dt-description"><span class="c013">38</span></dt><dd class="dd-description"> Unused extension constructor.
</dd><dt class="dt-description"><span class="c013">39</span></dt><dd class="dd-description"> Unused rec flag.
</dd><dt class="dt-description"><span class="c013">40</span></dt><dd class="dd-description"> Constructor or label name used out of scope.
</dd><dt class="dt-description"><span class="c013">41</span></dt><dd class="dd-description"> Ambiguous constructor or label name.
</dd><dt class="dt-description"><span class="c013">42</span></dt><dd class="dd-description"> Disambiguated constructor or label name (compatibility warning).
</dd><dt class="dt-description"><span class="c013">43</span></dt><dd class="dd-description"> Nonoptional label applied as optional.
</dd><dt class="dt-description"><span class="c013">44</span></dt><dd class="dd-description"> Open statement shadows an already defined identifier.
</dd><dt class="dt-description"><span class="c013">45</span></dt><dd class="dd-description"> Open statement shadows an already defined label or constructor.
</dd><dt class="dt-description"><span class="c013">46</span></dt><dd class="dd-description"> Error in environment variable.
</dd><dt class="dt-description"><span class="c013">47</span></dt><dd class="dd-description"> Illegal attribute payload.
</dd><dt class="dt-description"><span class="c013">48</span></dt><dd class="dd-description"> Implicit elimination of optional arguments.
</dd><dt class="dt-description"><span class="c013">49</span></dt><dd class="dd-description"> Absent cmi file when looking up module alias.
</dd><dt class="dt-description"><span class="c013">50</span></dt><dd class="dd-description"> Unexpected documentation comment.
</dd><dt class="dt-description"><span class="c013">51</span></dt><dd class="dd-description"> Warning on non-tail calls if @tailcall present.
</dd><dt class="dt-description"><span class="c013">52 (see </span><a href="#ss%3Awarn52"><span class="c013">9.5.2</span></a><span class="c013">)</span></dt><dd class="dd-description"> Fragile constant pattern.
</dd><dt class="dt-description"><span class="c013">53</span></dt><dd class="dd-description"> Attribute cannot appear in this context.
</dd><dt class="dt-description"><span class="c013">54</span></dt><dd class="dd-description"> Attribute used more than once on an expression.
</dd><dt class="dt-description"><span class="c013">55</span></dt><dd class="dd-description"> Inlining impossible.
</dd><dt class="dt-description"><span class="c013">56</span></dt><dd class="dd-description"> Unreachable case in a pattern-matching (based on type information).
</dd><dt class="dt-description"><span class="c013">57 (see </span><a href="#ss%3Awarn57"><span class="c013">9.5.3</span></a><span class="c013">)</span></dt><dd class="dd-description"> Ambiguous or-pattern variables under guard.
</dd><dt class="dt-description"><span class="c013">58</span></dt><dd class="dd-description"> Missing cmx file.
</dd><dt class="dt-description"><span class="c013">59</span></dt><dd class="dd-description"> Assignment to non-mutable value.
</dd><dt class="dt-description"><span class="c013">60</span></dt><dd class="dd-description"> Unused module declaration.
</dd><dt class="dt-description"><span class="c013">61</span></dt><dd class="dd-description"> Unboxable type in primitive declaration.
</dd><dt class="dt-description"><span class="c013">62</span></dt><dd class="dd-description"> Type constraint on GADT type declaration.
</dd><dt class="dt-description"><span class="c013">63</span></dt><dd class="dd-description"> Erroneous printed signature.
</dd><dt class="dt-description"><span class="c013">64</span></dt><dd class="dd-description"> -unsafe used with a preprocessor returning a syntax tree.
</dd><dt class="dt-description"><span class="c013">65</span></dt><dd class="dd-description"> Type declaration defining a new ’()’ constructor.
</dd><dt class="dt-description"><span class="c013">66</span></dt><dd class="dd-description"> Unused open! statement.
</dd><dt class="dt-description"><span class="c013">67</span></dt><dd class="dd-description"> Unused functor parameter.
</dd><dt class="dt-description"><span class="c013">A</span></dt><dd class="dd-description"> all warnings
</dd><dt class="dt-description"><span class="c013">C</span></dt><dd class="dd-description"> warnings 1, 2.
</dd><dt class="dt-description"><span class="c013">D</span></dt><dd class="dd-description"> Alias for warning 3.
</dd><dt class="dt-description"><span class="c013">E</span></dt><dd class="dd-description"> Alias for warning 4.
</dd><dt class="dt-description"><span class="c013">F</span></dt><dd class="dd-description"> Alias for warning 5.
</dd><dt class="dt-description"><span class="c013">K</span></dt><dd class="dd-description"> warnings 32, 33, 34, 35, 36, 37, 38, 39.
</dd><dt class="dt-description"><span class="c013">L</span></dt><dd class="dd-description"> Alias for warning 6.
</dd><dt class="dt-description"><span class="c013">M</span></dt><dd class="dd-description"> Alias for warning 7.
</dd><dt class="dt-description"><span class="c013">P</span></dt><dd class="dd-description"> Alias for warning 8.
</dd><dt class="dt-description"><span class="c013">R</span></dt><dd class="dd-description"> Alias for warning 9.
</dd><dt class="dt-description"><span class="c013">S</span></dt><dd class="dd-description"> Alias for warning 10.
</dd><dt class="dt-description"><span class="c013">U</span></dt><dd class="dd-description"> warnings 11, 12.
</dd><dt class="dt-description"><span class="c013">V</span></dt><dd class="dd-description"> Alias for warning 13.
</dd><dt class="dt-description"><span class="c013">X</span></dt><dd class="dd-description"> warnings 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 30.
</dd><dt class="dt-description"><span class="c013">Y</span></dt><dd class="dd-description"> Alias for warning 26.
</dd><dt class="dt-description"><span class="c013">Z</span></dt><dd class="dd-description"> Alias for warning 27.

</dd></dl><p>The default setting is <span class="c003">-w +a-4-6-7-9-27-29-32..42-44-45-48-50-60</span>.
It is displayed by <span class="c003">ocamlopt -help</span>.
Note that warnings 5 and 10 are not always triggered, depending on
the internals of the type checker.</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-warn-error</span> <span class="c009">warning-list</span></span></dt><dd class="dd-description">
Mark as fatal the warnings specified in the argument <span class="c009">warning-list</span>.
The compiler will stop with an error when one of these warnings is
emitted. The <span class="c009">warning-list</span> has the same meaning as for
the <span class="c003">-w</span> option: a <span class="c003">+</span> sign (or an uppercase letter) marks the
corresponding warnings as fatal, a <span class="c003">-</span>
sign (or a lowercase letter) turns them back into non-fatal warnings,
and a <span class="c003">@</span> sign both enables and marks as fatal the corresponding
warnings.<p>Note: it is not recommended to use warning sets (i.e. letters) as
arguments to <span class="c003">-warn-error</span>
in production code, because this can break your build when future versions
of OCaml add some new warnings.</p><p>The default setting is <span class="c003">-warn-error -a+31</span> (only warning 31 is fatal).</p></dd><dt class="dt-description"><span class="c006">-warn-help</span></dt><dd class="dd-description">
Show the description of all available warning numbers.</dd><dt class="dt-description"><span class="c006">-where</span></dt><dd class="dd-description">
Print the location of the standard library, then exit.
</dd><dt class="dt-description"><span class="c006">-with-runtime</span></dt><dd class="dd-description">
Include the runtime system in the generated program. This is the default.
</dd><dt class="dt-description"><span class="c006">-without-runtime</span></dt><dd class="dd-description">
The compiler does not include the runtime system (nor a reference to it) in the
generated program; it must be supplied separately.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Process <span class="c009">file</span> as a file name, even if it starts with a dash (<span class="c003">-</span>)
character.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-help</span> or <span class="c003">--help</span></span></dt><dd class="dd-description">
Display a short usage summary and exit.</dd></dl>
<!--TOC paragraph id="sec313" Options for the IA32 architecture-->
<h5 class="paragraph" id="sec313"><a class="section-anchor" href="#sec313" aria-hidden="true"></a>Options for the IA32 architecture</h5><!--SEC END --><p>
The IA32 code generator (Intel Pentium, AMD Athlon) supports the
following additional option:</p><dl class="description"><dt class="dt-description">
<span class="c006">-ffast-math</span></dt><dd class="dd-description"> Use the IA32 instructions to compute
trigonometric and exponential functions, instead of calling the
corresponding library routines. The functions affected are:
<span class="c003">atan</span>, <span class="c003">atan2</span>, <span class="c003">cos</span>, <span class="c003">log</span>, <span class="c003">log10</span>, <span class="c003">sin</span>, <span class="c003">sqrt</span> and <span class="c003">tan</span>.
The resulting code runs faster, but the range of supported arguments
and the precision of the result can be reduced. In particular,
trigonometric operations <span class="c003">cos</span>, <span class="c003">sin</span>, <span class="c003">tan</span> have their range reduced to
[−2<sup>64</sup>, 2<sup>64</sup>].
</dd></dl>
<!--TOC paragraph id="sec314" Options for the AMD64 architecture-->
<h5 class="paragraph" id="sec314"><a class="section-anchor" href="#sec314" aria-hidden="true"></a>Options for the AMD64 architecture</h5><!--SEC END --><p>
The AMD64 code generator (64-bit versions of Intel Pentium and AMD
Athlon) supports the following additional options:</p><dl class="description"><dt class="dt-description">
<span class="c006">-fPIC</span></dt><dd class="dd-description"> Generate position-independent machine code. This is
the default.
</dd><dt class="dt-description"><span class="c006">-fno-PIC</span></dt><dd class="dd-description"> Generate position-dependent machine code.
</dd></dl>
<!--TOC paragraph id="sec315" Options for the PowerPC architecture-->
<h5 class="paragraph" id="sec315"><a class="section-anchor" href="#sec315" aria-hidden="true"></a>Options for the PowerPC architecture</h5><!--SEC END --><p>
The PowerPC code generator supports the following additional options:</p><dl class="description"><dt class="dt-description">
<span class="c006">-flarge-toc</span></dt><dd class="dd-description"> Enables the PowerPC large model allowing the TOC (table of
contents) to be arbitrarily large. This is the default since 4.11.
</dd><dt class="dt-description"><span class="c006">-fsmall-toc</span></dt><dd class="dd-description"> Enables the PowerPC small model allowing the TOC to be up
to 64 kbytes per compilation unit. Prior to 4.11 this was the default
behaviour.
</dd></dl>
<!--TOC paragraph id="sec316" Contextual control of command-line options-->
<h5 class="paragraph" id="sec316"><a class="section-anchor" href="#sec316" aria-hidden="true"></a>Contextual control of command-line options</h5><!--SEC END --><p>The compiler command line can be modified “from the outside”
with the following mechanisms. These are experimental
and subject to change. They should be used only for experimental and
development work, not in released packages.</p><dl class="description"><dt class="dt-description">
<span class="c006">OCAMLPARAM</span> (environment variable)</dt><dd class="dd-description">
A set of arguments that will be inserted before or after the arguments from
the command line. Arguments are specified in a comma-separated list
of <span class="c003">name=value</span> pairs. A <span class="c003">_</span> is used to specify the position of
the command line arguments, i.e. <span class="c003">a=x,_,b=y</span> means that <span class="c003">a=x</span> should be
executed before parsing the arguments, and <span class="c003">b=y</span> after. Finally,
an alternative separator can be specified as the
first character of the string, within the set <span class="c003">:|; ,</span>.
</dd><dt class="dt-description"><span class="c006">ocaml_compiler_internal_params</span> (file in the stdlib directory)</dt><dd class="dd-description">
A mapping of file names to lists of arguments that
will be added to the command line (and <span class="c003">OCAMLPARAM</span>) arguments.
</dd><dt class="dt-description"><span class="c006">OCAML_FLEXLINK</span> (environment variable)</dt><dd class="dd-description">
Alternative executable to use on native
Windows for <span class="c003">flexlink</span> instead of the
configured value. Primarily used for bootstrapping.
</dd></dl>
<!--TOC section id="s:native-common-errors" 12.3  Common errors-->
<h2 class="section" id="s:native-common-errors"><a class="section-anchor" href="#s:native-common-errors" aria-hidden="true"></a>12.3  Common errors</h2><!--SEC END --><p>The error messages are almost identical to those of <span class="c003">ocamlc</span>.
See section <a href="#s%3Acomp-errors">9.4</a>.</p>
<!--TOC section id="s:native:running-executable" 12.4  Running executables produced by ocamlopt-->
<h2 class="section" id="s:native:running-executable"><a class="section-anchor" href="#s:native:running-executable" aria-hidden="true"></a>12.4  Running executables produced by ocamlopt</h2><!--SEC END --><p>Executables generated by <span class="c003">ocamlopt</span> are native, stand-alone executable
files that can be invoked directly. They do
not depend on the <span class="c003">ocamlrun</span> bytecode runtime system nor on
dynamically-loaded C/OCaml stub libraries.</p><p>During execution of an <span class="c003">ocamlopt</span>-generated executable,
the following environment variables are also consulted:
</p><dl class="description"><dt class="dt-description">
<span class="c006">OCAMLRUNPARAM</span></dt><dd class="dd-description"> Same usage as in <span class="c003">ocamlrun</span>
(see section <a href="#s%3Aocamlrun-options">11.2</a>), except that option <span class="c003">l</span>
is ignored (the operating system’s stack size limit
is used instead).
</dd><dt class="dt-description"><span class="c006">CAMLRUNPARAM</span></dt><dd class="dd-description"> If <span class="c003">OCAMLRUNPARAM</span> is not found in the
environment, then <span class="c003">CAMLRUNPARAM</span> will be used instead. If
<span class="c003">CAMLRUNPARAM</span> is not found, then the default values will be used.
</dd></dl>
<!--TOC section id="s:compat-native-bytecode" 12.5  Compatibility with the bytecode compiler-->
<h2 class="section" id="s:compat-native-bytecode"><a class="section-anchor" href="#s:compat-native-bytecode" aria-hidden="true"></a>12.5  Compatibility with the bytecode compiler</h2><!--SEC END --><p>This section lists the known incompatibilities between the bytecode
compiler and the native-code compiler. Except on those points, the two
compilers should generate code that behave identically.</p><ul class="itemize"><li class="li-itemize">Signals are detected only when the program performs an
allocation in the heap. That is, if a signal is delivered while in a
piece of code that does not allocate, its handler will not be called
until the next heap allocation.</li><li class="li-itemize">On ARM and PowerPC processors (32 and 64 bits), fused
multiply-add (FMA) instructions can be generated for a
floating-point multiplication followed by a floating-point addition
or subtraction, as in <span class="c003">x *. y +. z</span>. The FMA instruction avoids
rounding the intermediate result <span class="c003">x *. y</span>, which is generally
beneficial, but produces floating-point results that differ slightly
from those produced by the bytecode interpreter.</li><li class="li-itemize">On IA32 processors only (Intel and AMD x86 processors in 32-bit
mode), some intermediate results in floating-point computations are
kept in extended precision rather than being rounded to double
precision like the bytecode compiler always does. Floating-point
results can therefore differ slightly between bytecode and native code.</li><li class="li-itemize">The native-code compiler performs a number of optimizations that
the bytecode compiler does not perform, especially when the Flambda
optimizer is active. In particular, the native-code compiler
identifies and eliminates “dead code”, i.e. computations that do
not contribute to the results of the program. For example,
<pre>        let _ = ignore M.f
</pre>contains a reference to compilation unit <span class="c003">M</span> when compiled to
bytecode. This reference forces <span class="c003">M</span> to be linked and its
initialization code to be executed. The native-code compiler
eliminates the reference to <span class="c003">M</span>, hence the compilation unit <span class="c003">M</span> may
not be linked and executed. A workaround is to compile <span class="c003">M</span> with the
<span class="c003">-linkall</span> flag so that it will always be linked and executed, even if
not referenced. See also the <span class="c003">Sys.opaque_identity</span> function from the
<span class="c003">Sys</span> standard library module.</li><li class="li-itemize">Before 4.10, stack overflows, typically caused by excessively
deep recursion, are not always turned into a <span class="c003">Stack_overflow</span>
exception like with the bytecode compiler. The runtime system makes
a best effort to trap stack overflows and raise the <span class="c003">Stack_overflow</span>
exception, but sometimes it fails and a “segmentation fault” or
another system fault occurs instead.</li></ul>
<!--TOC chapter id="sec320" Chapter 13  Lexer and parser generators (ocamllex, ocamlyacc)-->
<h1 class="chapter" id="sec320">Chapter 13  Lexer and parser generators (ocamllex, ocamlyacc)</h1><!--SEC END --><p>
<a id="c:ocamlyacc"></a>
</p><!--NAME lexyacc.html-->
<p>This chapter describes two program generators: <span class="c003">ocamllex</span>, that
produces a lexical analyzer from a set of regular expressions with
associated semantic actions, and <span class="c003">ocamlyacc</span>, that produces a parser
from a grammar with associated semantic actions.</p><p>These program generators are very close to the well-known <span class="c003">lex</span> and
<span class="c003">yacc</span> commands that can be found in most C programming environments.
This chapter assumes a working knowledge of <span class="c003">lex</span> and <span class="c003">yacc</span>: while
it describes the input syntax for <span class="c003">ocamllex</span> and <span class="c003">ocamlyacc</span> and the
main differences with <span class="c003">lex</span> and <span class="c003">yacc</span>, it does not explain the basics
of writing a lexer or parser description in <span class="c003">lex</span> and <span class="c003">yacc</span>. Readers
unfamiliar with <span class="c003">lex</span> and <span class="c003">yacc</span> are referred to “Compilers:
principles, techniques, and tools” by Aho, Sethi and Ullman
(Addison-Wesley, 1986), or “Lex &amp; Yacc”, by Levine, Mason and
Brown (O’Reilly, 1992).</p>
<!--TOC section id="s:ocamllex-overview" 13.1  Overview of <span class="c003">ocamllex</span>-->
<h2 class="section" id="s:ocamllex-overview"><a class="section-anchor" href="#s:ocamllex-overview" aria-hidden="true"></a>13.1  Overview of <span class="c003">ocamllex</span></h2><!--SEC END --><p>The <span class="c003">ocamllex</span> command produces a lexical analyzer from a set of regular
expressions with attached semantic actions, in the style of
<span class="c003">lex</span>. Assuming the input file is <span class="c009">lexer</span><span class="c003">.mll</span>, executing
</p><pre>
        ocamllex <span class="c009">lexer</span>.mll
</pre><p>
produces OCaml code for a lexical analyzer in file <span class="c009">lexer</span><span class="c003">.ml</span>.
This file defines one lexing function per entry point in the lexer
definition. These functions have the same names as the entry
points. Lexing functions take as argument a lexer buffer, and return
the semantic attribute of the corresponding entry point.</p><p>Lexer buffers are an abstract data type implemented in the standard
library module <span class="c003">Lexing</span>. The functions <span class="c003">Lexing.from_channel</span>,
<span class="c003">Lexing.from_string</span> and <span class="c003">Lexing.from_function</span> create
lexer buffers that read from an input channel, a character string, or
any reading function, respectively. (See the description of module
<span class="c003">Lexing</span> in chapter <a href="#c%3Astdlib">26</a>.)</p><p>When used in conjunction with a parser generated by <span class="c003">ocamlyacc</span>, the
semantic actions compute a value belonging to the type <span class="c003">token</span> defined
by the generated parsing module. (See the description of <span class="c003">ocamlyacc</span>
below.)</p>
<!--TOC subsection id="ss:ocamllex-options" 13.1.1  Options-->
<h3 class="subsection" id="ss:ocamllex-options"><a class="section-anchor" href="#ss:ocamllex-options" aria-hidden="true"></a>13.1.1  Options</h3><!--SEC END --><p>
The following command-line options are recognized by <span class="c003">ocamllex</span>.</p><dl class="description"><dt class="dt-description"><span class="c006">-ml</span></dt><dd class="dd-description">
Output code that does not use OCaml’s built-in automata
interpreter. Instead, the automaton is encoded by OCaml functions.
This option improves performance when using the native compiler, but
decreases it when using the bytecode compiler.</dd><dt class="dt-description"><span class="c013"><span class="c003">-o</span> <span class="c009">output-file</span></span></dt><dd class="dd-description">
Specify the name of the output file produced by <span class="c003">ocamllex</span>.
The default is the input file name with its extension replaced by <span class="c003">.ml</span>.</dd><dt class="dt-description"><span class="c006">-q</span></dt><dd class="dd-description">
Quiet mode. <span class="c003">ocamllex</span> normally outputs informational messages
to standard output. They are suppressed if option <span class="c003">-q</span> is used.</dd><dt class="dt-description"><span class="c013"><span class="c003">-v</span> or <span class="c003">-version</span></span></dt><dd class="dd-description">
Print version string and exit.</dd><dt class="dt-description"><span class="c006">-vnum</span></dt><dd class="dd-description">
Print short version number and exit.</dd><dt class="dt-description"><span class="c013"><span class="c003">-help</span> or <span class="c003">--help</span></span></dt><dd class="dd-description">
Display a short usage summary and exit.
</dd></dl>
<!--TOC section id="s:ocamllex-syntax" 13.2  Syntax of lexer definitions-->
<h2 class="section" id="s:ocamllex-syntax"><a class="section-anchor" href="#s:ocamllex-syntax" aria-hidden="true"></a>13.2  Syntax of lexer definitions</h2><!--SEC END --><p>The format of lexer definitions is as follows:
</p><pre>
{ <span class="c009">header</span> }
let <span class="c009">ident</span> = <span class="c009">regexp</span> …
[refill { <span class="c009">refill-handler</span> }]
rule <span class="c009">entrypoint</span> [<span class="c009">arg</span><sub>1</sub>… <span class="c009">arg</span><sub><span class="c009">n</span></sub>] =
  parse <span class="c009">regexp</span> { <span class="c009">action</span> }
      | …
      | <span class="c009">regexp</span> { <span class="c009">action</span> }
and <span class="c009">entrypoint</span> [<span class="c009">arg</span><sub>1</sub>… <span class="c009">arg</span><sub><span class="c009">n</span></sub>] =
  parse …
and …
{ <span class="c009">trailer</span> }
</pre><p>
Comments are delimited by <span class="c003">(*</span> and <span class="c003">*)</span>, as in OCaml.
The <span class="c003">parse</span> keyword, can be replaced by the <span class="c003">shortest</span> keyword, with
the semantic consequences explained below.</p><p>Refill handlers are a recent (optional) feature introduced in 4.02,
documented below in subsection <a href="#ss%3Arefill-handlers">13.2.7</a>.</p>
<!--TOC subsection id="ss:ocamllex-header-trailer" 13.2.1  Header and trailer-->
<h3 class="subsection" id="ss:ocamllex-header-trailer"><a class="section-anchor" href="#ss:ocamllex-header-trailer" aria-hidden="true"></a>13.2.1  Header and trailer</h3><!--SEC END --><p>
The <span class="c009">header</span> and <span class="c009">trailer</span> sections are arbitrary OCaml
text enclosed in curly braces. Either or both can be omitted. If
present, the header text is copied as is at the beginning of the
output file and the trailer text at the end. Typically, the
header section contains the <span class="c003">open</span> directives required
by the actions, and possibly some auxiliary functions used in the
actions.</p>
<!--TOC subsection id="ss:ocamllex-named-regexp" 13.2.2  Naming regular expressions-->
<h3 class="subsection" id="ss:ocamllex-named-regexp"><a class="section-anchor" href="#ss:ocamllex-named-regexp" aria-hidden="true"></a>13.2.2  Naming regular expressions</h3><!--SEC END --><p>Between the header and the entry points, one can give names to
frequently-occurring regular expressions. This is written
<span class="c004">let</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a> <span class="c004">=</span>  <a class="syntax" href="#regexp"><span class="c010">regexp</span></a>.
In regular expressions that follow this declaration, the identifier
<span class="c009">ident</span> can be used as shorthand for <span class="c009">regexp</span>.</p>
<!--TOC subsection id="ss:ocamllex-entry-points" 13.2.3  Entry points-->
<h3 class="subsection" id="ss:ocamllex-entry-points"><a class="section-anchor" href="#ss:ocamllex-entry-points" aria-hidden="true"></a>13.2.3  Entry points</h3><!--SEC END --><p>The names of the entry points must be valid identifiers for OCaml
values (starting with a lowercase letter).
Similarly, the arguments <span class="c005">arg</span><sub>1</sub><span class="c003">…
<span class="c009">arg</span></span><sub><span class="c009">n</span></sub> must be valid identifiers for OCaml.
Each entry point becomes an
OCaml function that takes <span class="c009">n</span>+1 arguments,
the extra implicit last argument being of type <span class="c003">Lexing.lexbuf</span>.
Characters are read from the <span class="c003">Lexing.lexbuf</span> argument and matched
against the regular expressions provided in the rule, until a prefix
of the input matches one of the rule. The corresponding action is
then evaluated and returned as the result of the function.</p><p>If several regular expressions match a prefix of the input, the
“longest match” rule applies: the regular expression that matches
the longest prefix of the input is selected. In case of tie, the
regular expression that occurs earlier in the rule is selected.</p><p>However, if lexer rules are introduced with the <span class="c003">shortest</span> keyword in
place of the <span class="c003">parse</span> keyword, then the “shortest match” rule applies:
the shortest prefix of the input is selected. In case of tie, the
regular expression that occurs earlier in the rule is still selected.
This feature is not intended for use in ordinary lexical analyzers, it
may facilitate the use of <span class="c003">ocamllex</span> as a simple text processing tool.</p>
<!--TOC subsection id="ss:ocamllex-regexp" 13.2.4  Regular expressions-->
<h3 class="subsection" id="ss:ocamllex-regexp"><a class="section-anchor" href="#ss:ocamllex-regexp" aria-hidden="true"></a>13.2.4  Regular expressions</h3><!--SEC END --><p>The regular expressions are in the style of <span class="c003">lex</span>, with a more
OCaml-like syntax.
</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="regexp"><span class="c010">regexp</span></a></td><td class="c015">::=</td><td class="c017">
…
</td></tr>
</table></td></tr>
</table></div><dl class="description"><dt class="dt-description"><span class="c004">'</span> <span class="c010">regular-char</span> ∣  <a class="syntax" href="#escape-sequence"><span class="c010">escape-sequence</span></a> <span class="c004">'</span></dt><dd class="dd-description">
A character constant, with the same syntax as OCaml character
constants. Match the denoted character.</dd><dt class="dt-description"><span class="c006">_</span></dt><dd class="dd-description">
(underscore) Match any character.</dd><dt class="dt-description"><span class="c004">eof</span></dt><dd class="dd-description">
Match the end of the lexer input.<br>
<span class="c013">Note:</span> On some systems, with interactive input, an end-of-file
may be followed by more characters. However, <span class="c003">ocamllex</span> will not
correctly handle regular expressions that contain <span class="c003">eof</span> followed by
something else.</dd><dt class="dt-description"><span class="c004">"</span> { <a class="syntax" href="#string-character"><span class="c010">string-character</span></a> } <span class="c004">"</span></dt><dd class="dd-description">
A string constant, with the same syntax as OCaml string
constants. Match the corresponding sequence of characters.</dd><dt class="dt-description"><span class="c002"><span class="c003">[</span> <span class="c010">character-set</span> <span class="c003">]</span></span></dt><dd class="dd-description">
Match any single character belonging to the given
character set. Valid character sets are: single
character constants <span class="c002"><span class="c003">'</span> <span class="c010">c</span> <span class="c003">'</span></span>; ranges of characters
<span class="c004">'</span> <span class="c010">c</span><sub>1</sub> <span class="c002"><span class="c003">'</span> <span class="c003">-</span> <span class="c003">'</span></span> <span class="c010">c</span><sub>2</sub> <span class="c004">'</span> (all characters between <span class="c009">c</span><sub>1</sub> and <span class="c009">c</span><sub>2</sub>,
inclusive); and the union of two or more character sets, denoted by
concatenation.</dd><dt class="dt-description"><span class="c002"><span class="c003">[</span> <span class="c003">^</span> <span class="c010">character-set</span> <span class="c003">]</span></span></dt><dd class="dd-description">
Match any single character not belonging to the given character set.</dd><dt class="dt-description"><a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>1</sub> <span class="c004">#</span>  <a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>2</sub></dt><dd class="dd-description">
(difference of character sets)
Regular expressions <a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>1</sub> and <a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>2</sub> must be character sets
defined with <span class="c004">[</span>… <span class="c004">]</span> (or a single character expression or
underscore <span class="c003">_</span>).
Match the difference of the two specified character sets.</dd><dt class="dt-description"><a class="syntax" href="#regexp"><span class="c010">regexp</span></a> <span class="c004">*</span></dt><dd class="dd-description">
(repetition) Match the concatenation of zero or more
strings that match <a class="syntax" href="#regexp"><span class="c010">regexp</span></a>.</dd><dt class="dt-description"><a class="syntax" href="#regexp"><span class="c010">regexp</span></a> <span class="c004">+</span></dt><dd class="dd-description">
(strict repetition) Match the concatenation of one or more
strings that match <a class="syntax" href="#regexp"><span class="c010">regexp</span></a>.</dd><dt class="dt-description"><a class="syntax" href="#regexp"><span class="c010">regexp</span></a> <span class="c004">?</span></dt><dd class="dd-description">
(option) Match the empty string, or a string matching <a class="syntax" href="#regexp"><span class="c010">regexp</span></a>.</dd><dt class="dt-description"><a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>1</sub> <span class="c004">|</span>  <a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>2</sub></dt><dd class="dd-description">
(alternative) Match any string that matches <a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>1</sub> or <a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>2</sub></dd><dt class="dt-description"><a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>1</sub>  <a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>2</sub></dt><dd class="dd-description">
(concatenation) Match the concatenation of two strings, the first
matching <a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>1</sub>, the second matching <a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>2</sub>.</dd><dt class="dt-description"><span class="c004">(</span> <a class="syntax" href="#regexp"><span class="c010">regexp</span></a> <span class="c004">)</span></dt><dd class="dd-description">
Match the same strings as <a class="syntax" href="#regexp"><span class="c010">regexp</span></a>.</dd><dt class="dt-description"><a class="syntax" href="#ident"><span class="c010">ident</span></a></dt><dd class="dd-description">
Reference the regular expression bound to <a class="syntax" href="#ident"><span class="c010">ident</span></a> by an earlier
<span class="c004">let</span> <a class="syntax" href="#ident"><span class="c010">ident</span></a> <span class="c004">=</span>  <a class="syntax" href="#regexp"><span class="c010">regexp</span></a> definition.</dd><dt class="dt-description"><a class="syntax" href="#regexp"><span class="c010">regexp</span></a> <span class="c004">as</span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a></dt><dd class="dd-description">
Bind the substring matched by <a class="syntax" href="#regexp"><span class="c010">regexp</span></a> to identifier <a class="syntax" href="#ident"><span class="c010">ident</span></a>.
</dd></dl><p>Concerning the precedences of operators, <span class="c003">#</span> has the highest precedence,
followed by <span class="c003">*</span>, <span class="c003">+</span> and <span class="c003">?</span>,
then concatenation, then <span class="c003">|</span> (alternation), then <span class="c003">as</span>.</p>
<!--TOC subsection id="ss:ocamllex-actions" 13.2.5  Actions-->
<h3 class="subsection" id="ss:ocamllex-actions"><a class="section-anchor" href="#ss:ocamllex-actions" aria-hidden="true"></a>13.2.5  Actions</h3><!--SEC END --><p>The actions are arbitrary OCaml expressions. They are evaluated in
a context where the identifiers defined by using the <span class="c003">as</span> construct
are bound to subparts of the matched string.
Additionally, <span class="c003">lexbuf</span> is bound to the current lexer
buffer. Some typical uses for <span class="c003">lexbuf</span>, in conjunction with the
operations on lexer buffers provided by the <span class="c003">Lexing</span> standard library
module, are listed below.</p><dl class="description"><dt class="dt-description">
<span class="c006">Lexing.lexeme lexbuf</span></dt><dd class="dd-description">
Return the matched string.</dd><dt class="dt-description"><span class="c006">Lexing.lexeme_char lexbuf </span><span class="c009">n</span></dt><dd class="dd-description">
Return the <span class="c009">n</span><sup><span class="c008">th</span></sup>
character in the matched string. The first character corresponds to <span class="c009">n</span> = 0.</dd><dt class="dt-description"><span class="c006">Lexing.lexeme_start lexbuf</span></dt><dd class="dd-description">
Return the absolute position in the input text of the beginning of the
matched string (i.e. the offset of the first character of the matched
string). The first character read from the input text has offset 0.</dd><dt class="dt-description"><span class="c006">Lexing.lexeme_end lexbuf</span></dt><dd class="dd-description">
Return the absolute position in the input text of the end of the
matched string (i.e. the offset of the first character after the
matched string). The first character read from the input text has
offset 0.</dd><dt class="dt-description"><span class="c013"><span class="c009">entrypoint</span> [<span class="c009">exp</span></span><sub>1</sub><span class="c013">… <span class="c009">exp</span></span><sub><span class="c009">n</span></sub><span class="c013">] <span class="c003">lexbuf</span></span></dt><dd class="dd-description">
(Where <span class="c009">entrypoint</span> is the name of another entry point in the same
lexer definition.) Recursively call the lexer on the given entry point.
Notice that <span class="c003">lexbuf</span> is the last argument.
Useful for lexing nested comments, for example.</dd></dl>
<!--TOC subsection id="ss:ocamllex-variables" 13.2.6  Variables in regular expressions-->
<h3 class="subsection" id="ss:ocamllex-variables"><a class="section-anchor" href="#ss:ocamllex-variables" aria-hidden="true"></a>13.2.6  Variables in regular expressions</h3><!--SEC END --><p>
The <span class="c003">as</span> construct is similar to “<em>groups</em>” as provided by
numerous regular expression packages.
The type of these variables can be <span class="c003">string</span>, <span class="c003">char</span>, <span class="c003">string option</span>
or <span class="c003">char option</span>.</p><p>We first consider the case of linear patterns, that is the case when
all <span class="c003">as</span> bound variables are distinct.
In <a class="syntax" href="#regexp"><span class="c010">regexp</span></a> <span class="c004">as</span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a>, the type of <a class="syntax" href="#ident"><span class="c010">ident</span></a> normally is <span class="c003">string</span> (or
<span class="c003">string option</span>) except
when <a class="syntax" href="#regexp"><span class="c010">regexp</span></a> is a character constant, an underscore, a string
constant of length one, a character set specification, or an
alternation of those. Then, the type of <a class="syntax" href="#ident"><span class="c010">ident</span></a> is <span class="c003">char</span> (or <span class="c003">char option</span>).
Option types are introduced when overall rule matching does not
imply matching of the bound sub-pattern. This is in particular the
case of <span class="c004">(</span> <a class="syntax" href="#regexp"><span class="c010">regexp</span></a> <span class="c004">as</span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a> <span class="c002"><span class="c003">)</span> <span class="c003">?</span></span> and of
<a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>1</sub> <span class="c002"><span class="c003">|</span> <span class="c003">(</span></span>  <a class="syntax" href="#regexp"><span class="c010">regexp</span></a><sub>2</sub> <span class="c004">as</span>  <a class="syntax" href="#ident"><span class="c010">ident</span></a> <span class="c004">)</span>.</p><p>There is no linearity restriction over <span class="c003">as</span> bound variables.
When a variable is bound more than once, the previous rules are to be
extended as follows:
</p><ul class="itemize"><li class="li-itemize">
A variable is a <span class="c003">char</span> variable when all its occurrences bind
<span class="c003">char</span> occurrences in the previous sense.
</li><li class="li-itemize">A variable is an <span class="c003">option</span> variable when the overall expression
can be matched without binding this variable.
</li></ul><p>
For instance, in
<span class="c003">('a' as x) | ( 'a' (_ as x) )</span> the variable <span class="c003">x</span> is of type
<span class="c003">char</span>, whereas in
<span class="c003">("ab" as x) | ( 'a' (_ as x) ? )</span> the variable <span class="c003">x</span> is of type
<span class="c003">string option</span>.</p><p>In some cases, a successful match may not yield a unique set of bindings.
For instance the matching of <code>aba</code> by the regular expression
<span class="c003">(('a'|"ab") as x) (("ba"|'a') as y)</span> may result in binding
either
<code>x</code> to <code>"ab"</code> and <code>y</code> to <code>"a"</code>, or
<code>x</code> to <code>"a"</code> and <code>y</code> to <code>"ba"</code>.
The automata produced <span class="c003">ocamllex</span> on such ambiguous regular
expressions will select one of the possible resulting sets of
bindings.
The selected set of bindings is purposely left unspecified.</p>
<!--TOC subsection id="ss:refill-handlers" 13.2.7  Refill handlers-->
<h3 class="subsection" id="ss:refill-handlers"><a class="section-anchor" href="#ss:refill-handlers" aria-hidden="true"></a>13.2.7  Refill handlers</h3><!--SEC END --><p>By default, when ocamllex reaches the end of its lexing buffer, it
will silently call the <span class="c003">refill_buff</span> function of <span class="c003">lexbuf</span> structure
and continue lexing. It is sometimes useful to be able to take control
of refilling action; typically, if you use a library for asynchronous
computation, you may want to wrap the refilling action in a delaying
function to avoid blocking synchronous operations.</p><p>Since OCaml 4.02, it is possible to specify a <span class="c009">refill-handler</span>,
a function that will be called when refill happens. It is passed the
continuation of the lexing, on which it has total control. The OCaml
expression used as refill action should have a type that is an
instance of
</p><pre>   (Lexing.lexbuf -&gt; 'a) -&gt; Lexing.lexbuf -&gt; 'a
</pre><p>where the first argument is the continuation which captures the
processing ocamllex would usually perform (refilling the buffer, then
calling the lexing function again), and the result type that
instantiates [’a] should unify with the result type of all lexing
rules.</p><p>As an example, consider the following lexer that is parametrized over
an arbitrary monad:
</p><pre>{
type token = EOL | INT of int | PLUS

module Make (M : sig
               type 'a t
               val return: 'a -&gt; 'a t
               val bind: 'a t -&gt; ('a -&gt; 'b t) -&gt; 'b t
               val fail : string -&gt; 'a t

               (* Set up lexbuf *)
               val on_refill : Lexing.lexbuf -&gt; unit t
             end)
= struct

let refill_handler k lexbuf =
    M.bind (M.on_refill lexbuf) (fun () -&gt; k lexbuf)

}

refill {refill_handler}

rule token = parse
| [' ' '\t']
    { token lexbuf }
| '\n'
    { M.return EOL }
| ['0'-'9']+ as i
    { M.return (INT (int_of_string i)) }
| '+'
    { M.return PLUS }
| _
    { M.fail "unexpected character" }
{
end
}
</pre>
<!--TOC subsection id="ss:ocamllex-reserved-ident" 13.2.8  Reserved identifiers-->
<h3 class="subsection" id="ss:ocamllex-reserved-ident"><a class="section-anchor" href="#ss:ocamllex-reserved-ident" aria-hidden="true"></a>13.2.8  Reserved identifiers</h3><!--SEC END --><p>All identifiers starting with <span class="c003">__ocaml_lex</span> are reserved for use by
<span class="c003">ocamllex</span>; do not use any such identifier in your programs.</p>
<!--TOC section id="s:ocamlyacc-overview" 13.3  Overview of <span class="c003">ocamlyacc</span>-->
<h2 class="section" id="s:ocamlyacc-overview"><a class="section-anchor" href="#s:ocamlyacc-overview" aria-hidden="true"></a>13.3  Overview of <span class="c003">ocamlyacc</span></h2><!--SEC END --><p>The <span class="c003">ocamlyacc</span> command produces a parser from a context-free grammar
specification with attached semantic actions, in the style of <span class="c003">yacc</span>.
Assuming the input file is <span class="c009">grammar</span><span class="c003">.mly</span>, executing
</p><pre>
        ocamlyacc <span class="c009">options grammar</span>.mly
</pre><p>
produces OCaml code for a parser in the file <span class="c009">grammar</span><span class="c003">.ml</span>,
and its interface in file <span class="c009">grammar</span><span class="c003">.mli</span>.</p><p>The generated module defines one parsing function per entry point in
the grammar. These functions have the same names as the entry points.
Parsing functions take as arguments a lexical analyzer (a function
from lexer buffers to tokens) and a lexer buffer, and return the
semantic attribute of the corresponding entry point. Lexical analyzer
functions are usually generated from a lexer specification by the
<span class="c003">ocamllex</span> program. Lexer buffers are an abstract data type
implemented in the standard library module <span class="c003">Lexing</span>. Tokens are values from
the concrete type <span class="c003">token</span>, defined in the interface file
<span class="c009">grammar</span><span class="c003">.mli</span> produced by <span class="c003">ocamlyacc</span>.</p>
<!--TOC section id="s:ocamlyacc-syntax" 13.4  Syntax of grammar definitions-->
<h2 class="section" id="s:ocamlyacc-syntax"><a class="section-anchor" href="#s:ocamlyacc-syntax" aria-hidden="true"></a>13.4  Syntax of grammar definitions</h2><!--SEC END --><p>Grammar definitions have the following format:
</p><pre>
%{
  <span class="c009">header</span>
%}
  <span class="c009">declarations</span>
%%
  <span class="c009">rules</span>
%%
  <span class="c009">trailer</span>
</pre><p>Comments are enclosed between <code>/*</code> and <code>*/</code> (as in C) in the
“declarations” and “rules” sections, and between <code>(*</code> and
<code>*)</code> (as in OCaml) in the “header” and “trailer” sections.</p>
<!--TOC subsection id="ss:ocamlyacc-header-trailer" 13.4.1  Header and trailer-->
<h3 class="subsection" id="ss:ocamlyacc-header-trailer"><a class="section-anchor" href="#ss:ocamlyacc-header-trailer" aria-hidden="true"></a>13.4.1  Header and trailer</h3><!--SEC END --><p>The header and the trailer sections are OCaml code that is copied
as is into file <span class="c009">grammar</span><span class="c003">.ml</span>. Both sections are optional. The header
goes at the beginning of the output file; it usually contains
<span class="c003">open</span> directives and auxiliary functions required by the semantic
actions of the rules. The trailer goes at the end of the output file.</p>
<!--TOC subsection id="ss:ocamlyacc-declarations" 13.4.2  Declarations-->
<h3 class="subsection" id="ss:ocamlyacc-declarations"><a class="section-anchor" href="#ss:ocamlyacc-declarations" aria-hidden="true"></a>13.4.2  Declarations</h3><!--SEC END --><p>Declarations are given one per line. They all start with a <code>%</code> sign.</p><dl class="description"><dt class="dt-description"><span class="c004">%token</span> <a class="syntax" href="#constr"><span class="c010">constr</span></a> …  <a class="syntax" href="#constr"><span class="c010">constr</span></a></dt><dd class="dd-description">
Declare the given symbols <a class="syntax" href="#constr"><span class="c010">constr</span></a> …  <a class="syntax" href="#constr"><span class="c010">constr</span></a>
as tokens (terminal symbols). These symbols
are added as constant constructors for the <span class="c003">token</span> concrete type.</dd><dt class="dt-description"><span class="c002"><span class="c003">%token</span> <span class="c003">&lt;</span></span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">&gt;</span>  <a class="syntax" href="#constr"><span class="c010">constr</span></a> …  <a class="syntax" href="#constr"><span class="c010">constr</span></a></dt><dd class="dd-description">
Declare the given symbols <a class="syntax" href="#constr"><span class="c010">constr</span></a> …  <a class="syntax" href="#constr"><span class="c010">constr</span></a> as tokens with an
attached attribute of the
given type. These symbols are added as constructors with arguments of
the given type for the <span class="c003">token</span> concrete type. The <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> part is
an arbitrary OCaml type expression, except that all type
constructor names must be fully qualified (e.g. <span class="c003">Modname.typename</span>)
for all types except standard built-in types, even if the proper
<code>open</code> directives (e.g. <code>open Modname</code>) were given in the
header section. That’s because the header is copied only to the <span class="c003">.ml</span>
output file, but not to the <span class="c003">.mli</span> output file, while the <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> part
of a <code>%token</code> declaration is copied to both.</dd><dt class="dt-description"><span class="c004">%start</span> <span class="c010">symbol</span> …  <span class="c010">symbol</span></dt><dd class="dd-description">
Declare the given symbols as entry points for the grammar. For each
entry point, a parsing function with the same name is defined in the
output module. Non-terminals that are not declared as entry points
have no such parsing function. Start symbols must be given a type with
the <code>%type</code> directive below.</dd><dt class="dt-description"><span class="c002"><span class="c003">%type</span> <span class="c003">&lt;</span></span> <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">&gt;</span>  <span class="c010">symbol</span> …  <span class="c010">symbol</span></dt><dd class="dd-description">
Specify the type of the semantic attributes for the given symbols.
This is mandatory for start symbols only. Other nonterminal symbols
need not be given types by hand: these types will be inferred when
running the output files through the OCaml compiler (unless the
<code>-s</code> option is in effect). The <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> part is an arbitrary OCaml
type expression, except that all type constructor names must be
fully qualified, as explained above for <span class="c003">%token</span>.</dd><dt class="dt-description"><span class="c004">%left</span> <span class="c010">symbol</span> …  <span class="c010">symbol</span></dt><dd class="dd-description">
</dd><dt class="dt-description"><span class="c004">%right</span> <span class="c010">symbol</span> …  <span class="c010">symbol</span></dt><dd class="dd-description">
</dd><dt class="dt-description"><span class="c004">%nonassoc</span> <span class="c010">symbol</span> …  <span class="c010">symbol</span></dt><dd class="dd-description"><p>Associate precedences and associativities to the given symbols. All
symbols on the same line are given the same precedence. They have
higher precedence than symbols declared before in a <code>%left</code>,
<code>%right</code> or <code>%nonassoc</code> line. They have lower precedence
than symbols declared after in a <code>%left</code>, <code>%right</code> or
<code>%nonassoc</code> line. The symbols are declared to associate to the
left (<code>%left</code>), to the right (<code>%right</code>), or to be
non-associative (<code>%nonassoc</code>). The symbols are usually tokens.
They can also be dummy nonterminals, for use with the <code>%prec</code>
directive inside the rules.</p><p>The precedence declarations are used in the following way to
resolve reduce/reduce and shift/reduce conflicts:
</p><ul class="itemize"><li class="li-itemize">
Tokens and rules have precedences. By default, the precedence
of a rule is the precedence of its rightmost terminal. You
can override this default by using the <span class="c004">%prec</span> directive in the rule.
</li><li class="li-itemize">A reduce/reduce conflict
is resolved in favor of the first rule (in the order given by the
source file), and <span class="c003">ocamlyacc</span> outputs a warning.
</li><li class="li-itemize">A shift/reduce conflict
is resolved by comparing the precedence of the rule to be
reduced with the precedence of the token to be shifted. If the
precedence of the rule is higher, then the rule will be reduced;
if the precedence of the token is higher, then the token will
be shifted.
</li><li class="li-itemize">A shift/reduce conflict between a rule and a token with the
same precedence will be resolved using the associativity: if the
token is left-associative, then the parser will reduce; if the
token is right-associative, then the parser will shift. If the
token is non-associative, then the parser will declare a syntax
error.
</li><li class="li-itemize">When a shift/reduce conflict cannot be resolved using the above
method, then <span class="c003">ocamlyacc</span> will output a warning and the parser will
always shift.
</li></ul></dd></dl>
<!--TOC subsection id="ss:ocamlyacc-rules" 13.4.3  Rules-->
<h3 class="subsection" id="ss:ocamlyacc-rules"><a class="section-anchor" href="#ss:ocamlyacc-rules" aria-hidden="true"></a>13.4.3  Rules</h3><!--SEC END --><p>The syntax for rules is as usual:
</p><pre>
<span class="c009">nonterminal</span> :
    <span class="c009">symbol</span> … <span class="c009">symbol</span> { <span class="c009">semantic-action</span> }
  | …
  | <span class="c009">symbol</span> … <span class="c009">symbol</span> { <span class="c009">semantic-action</span> }
;
</pre><p>
Rules can also contain the <code>%prec </code><span class="c009">symbol</span> directive in the
right-hand side part, to override the default precedence and
associativity of the rule with the precedence and associativity of the
given symbol.</p><p>Semantic actions are arbitrary OCaml expressions, that
are evaluated to produce the semantic attribute attached to
the defined nonterminal. The semantic actions can access the
semantic attributes of the symbols in the right-hand side of
the rule with the <code>$</code> notation: <code>$1</code> is the attribute for the
first (leftmost) symbol, <code>$2</code> is the attribute for the second
symbol, etc.</p><p>The rules may contain the special symbol <span class="c003">error</span> to indicate
resynchronization points, as in <span class="c003">yacc</span>.</p><p>Actions occurring in the middle of rules are not supported.</p><p>Nonterminal symbols are like regular OCaml symbols, except that they
cannot end with <span class="c003">'</span> (single quote).</p>
<!--TOC subsection id="ss:ocamlyacc-error-handling" 13.4.4  Error handling-->
<h3 class="subsection" id="ss:ocamlyacc-error-handling"><a class="section-anchor" href="#ss:ocamlyacc-error-handling" aria-hidden="true"></a>13.4.4  Error handling</h3><!--SEC END --><p>Error recovery is supported as follows: when the parser reaches an
error state (no grammar rules can apply), it calls a function named
<span class="c003">parse_error</span> with the string <span class="c003">"syntax error"</span> as argument. The default
<span class="c003">parse_error</span> function does nothing and returns, thus initiating error
recovery (see below). The user can define a customized <span class="c003">parse_error</span>
function in the header section of the grammar file.</p><p>The parser also enters error recovery mode if one of the grammar
actions raises the <span class="c003">Parsing.Parse_error</span> exception.</p><p>In error recovery mode, the parser discards states from the
stack until it reaches a place where the error token can be shifted.
It then discards tokens from the input until it finds three successive
tokens that can be accepted, and starts processing with the first of
these. If no state can be uncovered where the error token can be
shifted, then the parser aborts by raising the <span class="c003">Parsing.Parse_error</span>
exception.</p><p>Refer to documentation on <span class="c003">yacc</span> for more details and guidance in how
to use error recovery.</p>
<!--TOC section id="s:ocamlyacc-options" 13.5  Options-->
<h2 class="section" id="s:ocamlyacc-options"><a class="section-anchor" href="#s:ocamlyacc-options" aria-hidden="true"></a>13.5  Options</h2><!--SEC END --><p>The <span class="c003">ocamlyacc</span> command recognizes the following options:</p><dl class="description"><dt class="dt-description"><span class="c013"><span class="c003">-b</span><span class="c009">prefix</span></span></dt><dd class="dd-description">
Name the output files <span class="c009">prefix</span><span class="c003">.ml</span>, <span class="c009">prefix</span><span class="c003">.mli</span>,
<span class="c009">prefix</span><span class="c003">.output</span>, instead of the default naming convention.</dd><dt class="dt-description"><span class="c006">-q</span></dt><dd class="dd-description">
This option has no effect.</dd><dt class="dt-description"><span class="c006">-v</span></dt><dd class="dd-description">
Generate a description of the parsing tables and a report on conflicts
resulting from ambiguities in the grammar. The description is put in
file <span class="c009">grammar</span><span class="c003">.output</span>.</dd><dt class="dt-description"><span class="c006">-version</span></dt><dd class="dd-description">
Print version string and exit.</dd><dt class="dt-description"><span class="c006">-vnum</span></dt><dd class="dd-description">
Print short version number and exit.</dd><dt class="dt-description"><span class="c006">-</span></dt><dd class="dd-description">
Read the grammar specification from standard input. The default
output file names are <span class="c003">stdin.ml</span> and <span class="c003">stdin.mli</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">--</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Process <span class="c009">file</span> as the grammar specification, even if its name
starts with a dash (-) character. This option must be the last on the
command line.</dd></dl><p>At run-time, the <span class="c003">ocamlyacc</span>-generated parser can be debugged by
setting the <span class="c003">p</span> option in the <span class="c003">OCAMLRUNPARAM</span> environment variable
(see section <a href="#s%3Aocamlrun-options">11.2</a>). This causes the pushdown
automaton executing the parser to print a trace of its action (tokens
shifted, rules reduced, etc). The trace mentions rule numbers and
state numbers that can be interpreted by looking at the file
<span class="c009">grammar</span><span class="c003">.output</span> generated by <span class="c003">ocamlyacc -v</span>.</p>
<!--TOC section id="s:lexyacc-example" 13.6  A complete example-->
<h2 class="section" id="s:lexyacc-example"><a class="section-anchor" href="#s:lexyacc-example" aria-hidden="true"></a>13.6  A complete example</h2><!--SEC END --><p>The all-time favorite: a desk calculator. This program reads
arithmetic expressions on standard input, one per line, and prints
their values. Here is the grammar definition:
</p><pre>        /* File parser.mly */
        %token &lt;int&gt; INT
        %token PLUS MINUS TIMES DIV
        %token LPAREN RPAREN
        %token EOL
        %left PLUS MINUS        /* lowest precedence */
        %left TIMES DIV         /* medium precedence */
        %nonassoc UMINUS        /* highest precedence */
        %start main             /* the entry point */
        %type &lt;int&gt; main
        %%
        main:
            expr EOL                { $1 }
        ;
        expr:
            INT                     { $1 }
          | LPAREN expr RPAREN      { $2 }
          | expr PLUS expr          { $1 + $3 }
          | expr MINUS expr         { $1 - $3 }
          | expr TIMES expr         { $1 * $3 }
          | expr DIV expr           { $1 / $3 }
          | MINUS expr %prec UMINUS { - $2 }
        ;
</pre><p>Here is the definition for the corresponding lexer:
</p><pre>        (* File lexer.mll *)
        {
        open Parser        (* The type token is defined in parser.mli *)
        exception Eof
        }
        rule token = parse
            [' ' '\t']     { token lexbuf }     (* skip blanks *)
          | ['\n' ]        { EOL }
          | ['0'-'9']+ as lxm { INT(int_of_string lxm) }
          | '+'            { PLUS }
          | '-'            { MINUS }
          | '*'            { TIMES }
          | '/'            { DIV }
          | '('            { LPAREN }
          | ')'            { RPAREN }
          | eof            { raise Eof }
</pre><p>Here is the main program, that combines the parser with the lexer:
</p><pre>        (* File calc.ml *)
        let _ =
          try
            let lexbuf = Lexing.from_channel stdin in
            while true do
              let result = Parser.main Lexer.token lexbuf in
                print_int result; print_newline(); flush stdout
            done
          with Lexer.Eof -&gt;
            exit 0
</pre><p>To compile everything, execute:
</p><pre>        ocamllex lexer.mll       # generates lexer.ml
        ocamlyacc parser.mly     # generates parser.ml and parser.mli
        ocamlc -c parser.mli
        ocamlc -c lexer.ml
        ocamlc -c parser.ml
        ocamlc -c calc.ml
        ocamlc -o calc lexer.cmo parser.cmo calc.cmo
</pre>
<!--TOC section id="s:lexyacc-common-errors" 13.7  Common errors-->
<h2 class="section" id="s:lexyacc-common-errors"><a class="section-anchor" href="#s:lexyacc-common-errors" aria-hidden="true"></a>13.7  Common errors</h2><!--SEC END --><dl class="description"><dt class="dt-description"><span class="c013">ocamllex: transition table overflow, automaton is too big</span></dt><dd class="dd-description"><p>The deterministic automata generated by <span class="c003">ocamllex</span> are limited to at
most 32767 transitions. The message above indicates that your lexer
definition is too complex and overflows this limit. This is commonly
caused by lexer definitions that have separate rules for each of the
alphabetic keywords of the language, as in the following example.
</p><pre>rule token = parse
  "keyword1"   { KWD1 }
| "keyword2"   { KWD2 }
| ...
| "keyword100" { KWD100 }
| ['A'-'Z' 'a'-'z'] ['A'-'Z' 'a'-'z' '0'-'9' '_'] * as id
               { IDENT id}
</pre><p>To keep the generated automata small, rewrite those definitions with
only one general “identifier” rule, followed by a hashtable lookup
to separate keywords from identifiers:
</p><pre>{ let keyword_table = Hashtbl.create 53
  let _ =
    List.iter (fun (kwd, tok) -&gt; Hashtbl.add keyword_table kwd tok)
              [ "keyword1", KWD1;
                "keyword2", KWD2; ...
                "keyword100", KWD100 ]
}
rule token = parse
  ['A'-'Z' 'a'-'z'] ['A'-'Z' 'a'-'z' '0'-'9' '_'] * as id
               { try
                   Hashtbl.find keyword_table id
                 with Not_found -&gt;
                   IDENT id }
</pre></dd><dt class="dt-description"><span class="c013">ocamllex: Position memory overflow, too many bindings</span></dt><dd class="dd-description">
The deterministic automata generated by <span class="c003">ocamllex</span> maintain a table of
positions inside the scanned lexer buffer. The size of this table is
limited to at most 255 cells. This error should not show up in normal
situations.</dd></dl>
<!--TOC chapter id="sec341" Chapter 14  Dependency generator (ocamldep)-->
<h1 class="chapter" id="sec341">Chapter 14  Dependency generator (ocamldep)</h1><!--SEC END --><p> <a id="c:camldep"></a>
</p><!--NAME depend.html-->
<p>The <span class="c003">ocamldep</span> command scans a set of OCaml source files
(<span class="c003">.ml</span> and <span class="c003">.mli</span> files) for references to external compilation units,
and outputs dependency lines in a format suitable for the <span class="c003">make</span>
utility. This ensures that <span class="c003">make</span> will compile the source files in the
correct order, and recompile those files that need to when a source
file is modified.</p><p>The typical usage is:
</p><pre>
        ocamldep <span class="c009">options</span> *.mli *.ml &gt; .depend
</pre><p>
where <span class="c003">*.mli *.ml</span> expands to all source files in the current
directory and <span class="c003">.depend</span> is the file that should contain the
dependencies. (See below for a typical <span class="c003">Makefile</span>.)</p><p>Dependencies are generated both for compiling with the bytecode
compiler <span class="c003">ocamlc</span> and with the native-code compiler <span class="c003">ocamlopt</span>.</p>
<!--TOC section id="s:ocamldep-options" 14.1  Options-->
<h2 class="section" id="s:ocamldep-options"><a class="section-anchor" href="#s:ocamldep-options" aria-hidden="true"></a>14.1  Options</h2><!--SEC END --><p>The following command-line options are recognized by <span class="c003">ocamldep</span>.</p><dl class="description"><dt class="dt-description"><span class="c006">-absname</span></dt><dd class="dd-description">
Show absolute filenames in error messages.</dd><dt class="dt-description"><span class="c006">-all</span></dt><dd class="dd-description">
Generate dependencies on all required files, rather than assuming
implicit dependencies.</dd><dt class="dt-description"><span class="c006">-allow-approx</span></dt><dd class="dd-description">
Allow falling back on a lexer-based approximation when parsing fails.</dd><dt class="dt-description"><span class="c013"><span class="c003">-args</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Read additional newline-terminated command line arguments from <span class="c009">filename</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-args0</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Read additional null character terminated command line arguments from <span class="c009">filename</span>.</dd><dt class="dt-description"><span class="c006">-as-map</span></dt><dd class="dd-description">
For the following files, do not include delayed dependencies for
module aliases.
This option assumes that they are compiled using options
<span class="c003">-no-alias-deps -w -49</span>, and that those files or their interface are
passed with the <span class="c003">-map</span> option when computing dependencies for other
files. Note also that for dependencies to be correct in the
implementation of a map file, its interface should not coerce any of
the aliases it contains.</dd><dt class="dt-description"><span class="c006">-debug-map</span></dt><dd class="dd-description">
Dump the delayed dependency map for each map file.</dd><dt class="dt-description"><span class="c013"><span class="c003">-I</span> <span class="c009">directory</span></span></dt><dd class="dd-description">
Add the given directory to the list of directories searched for
source files. If a source file <span class="c003">foo.ml</span> mentions an external
compilation unit <span class="c003">Bar</span>, a dependency on that unit’s interface
<span class="c003">bar.cmi</span> is generated only if the source for <span class="c003">bar</span> is found in the
current directory or in one of the directories specified with <span class="c003">-I</span>.
Otherwise, <span class="c003">Bar</span> is assumed to be a module from the standard library,
and no dependencies are generated. For programs that span multiple
directories, it is recommended to pass <span class="c003">ocamldep</span> the same <span class="c003">-I</span> options
that are passed to the compiler.</dd><dt class="dt-description"><span class="c006">-nocwd</span></dt><dd class="dd-description">
Do not add current working directory to the list of include directories.</dd><dt class="dt-description"><span class="c013"><span class="c003">-impl</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Process <span class="c009">file</span> as a <span class="c003">.ml</span> file.</dd><dt class="dt-description"><span class="c013"><span class="c003">-intf</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Process <span class="c009">file</span> as a <span class="c003">.mli</span> file.</dd><dt class="dt-description"><span class="c013"><span class="c003">-map</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Read an propagate the delayed dependencies for module aliases in
<span class="c009">file</span>, so that the following files will depend on the
exported aliased modules if they use them. See the example below.</dd><dt class="dt-description"><span class="c013"><span class="c003">-ml-synonym</span> <span class="c009">.ext</span></span></dt><dd class="dd-description">
Consider the given extension (with leading dot) to be a synonym for .ml.</dd><dt class="dt-description"><span class="c013"><span class="c003">-mli-synonym</span> <span class="c009">.ext</span></span></dt><dd class="dd-description">
Consider the given extension (with leading dot) to be a synonym for .mli.</dd><dt class="dt-description"><span class="c006">-modules</span></dt><dd class="dd-description">
Output raw dependencies of the form
<pre>      filename: Module1 Module2 ... ModuleN
</pre>where <span class="c003">Module1</span>, …, <span class="c003">ModuleN</span> are the names of the compilation
units referenced within the file <span class="c003">filename</span>, but these names are not
resolved to source file names. Such raw dependencies cannot be used
by <span class="c003">make</span>, but can be post-processed by other tools such as <span class="c003">Omake</span>.</dd><dt class="dt-description"><span class="c006">-native</span></dt><dd class="dd-description">
Generate dependencies for a pure native-code program (no bytecode
version). When an implementation file (<span class="c003">.ml</span> file) has no explicit
interface file (<span class="c003">.mli</span> file), <span class="c003">ocamldep</span> generates dependencies on the
bytecode compiled file (<span class="c003">.cmo</span> file) to reflect interface changes.
This can cause unnecessary bytecode recompilations for programs that
are compiled to native-code only. The flag <span class="c003">-native</span> causes
dependencies on native compiled files (<span class="c003">.cmx</span>) to be generated instead
of on <span class="c003">.cmo</span> files. (This flag makes no difference if all source files
have explicit <span class="c003">.mli</span> interface files.)</dd><dt class="dt-description"><span class="c006">-one-line</span></dt><dd class="dd-description">
Output one line per file, regardless of the length.</dd><dt class="dt-description"><span class="c013"><span class="c003">-open</span> <span class="c009">module</span></span></dt><dd class="dd-description">
Assume that module <span class="c009">module</span> is opened before parsing each of the
following files.</dd><dt class="dt-description"><span class="c013"><span class="c003">-pp</span> <span class="c009">command</span></span></dt><dd class="dd-description">
Cause <span class="c003">ocamldep</span> to call the given <span class="c009">command</span> as a preprocessor
for each source file.</dd><dt class="dt-description"><span class="c013"><span class="c003">-ppx</span> <span class="c009">command</span></span></dt><dd class="dd-description">
Pipe abstract syntax trees through preprocessor <span class="c009">command</span>.</dd><dt class="dt-description"><span class="c006">-shared</span></dt><dd class="dd-description">
Generate dependencies for native plugin files (.cmxs) in addition to
native compiled files (.cmx).</dd><dt class="dt-description"><span class="c006">-slash</span></dt><dd class="dd-description">
Under Windows, use a forward slash (/) as the path separator instead
of the usual backward slash (\). Under Unix, this option does
nothing.</dd><dt class="dt-description"><span class="c006">-sort</span></dt><dd class="dd-description">
Sort files according to their dependencies.</dd><dt class="dt-description"><span class="c006">-version</span></dt><dd class="dd-description">
Print version string and exit.</dd><dt class="dt-description"><span class="c006">-vnum</span></dt><dd class="dd-description">
Print short version number and exit.</dd><dt class="dt-description"><span class="c013"><span class="c003">-help</span> or <span class="c003">--help</span></span></dt><dd class="dd-description">
Display a short usage summary and exit.
</dd></dl>
<!--TOC section id="s:ocamldep-makefile" 14.2  A typical Makefile-->
<h2 class="section" id="s:ocamldep-makefile"><a class="section-anchor" href="#s:ocamldep-makefile" aria-hidden="true"></a>14.2  A typical Makefile</h2><!--SEC END --><p>Here is a template <span class="c003">Makefile</span> for a OCaml program.</p><pre>OCAMLC=ocamlc
OCAMLOPT=ocamlopt
OCAMLDEP=ocamldep
INCLUDES=                 # all relevant -I options here
OCAMLFLAGS=$(INCLUDES)    # add other options for ocamlc here
OCAMLOPTFLAGS=$(INCLUDES) # add other options for ocamlopt here

# prog1 should be compiled to bytecode, and is composed of three
# units: mod1, mod2 and mod3.

# The list of object files for prog1
PROG1_OBJS=mod1.cmo mod2.cmo mod3.cmo

prog1: $(PROG1_OBJS)
        $(OCAMLC) -o prog1 $(OCAMLFLAGS) $(PROG1_OBJS)

# prog2 should be compiled to native-code, and is composed of two
# units: mod4 and mod5.

# The list of object files for prog2
PROG2_OBJS=mod4.cmx mod5.cmx

prog2: $(PROG2_OBJS)
        $(OCAMLOPT) -o prog2 $(OCAMLFLAGS) $(PROG2_OBJS)

# Common rules
.SUFFIXES: .ml .mli .cmo .cmi .cmx

.ml.cmo:
        $(OCAMLC) $(OCAMLFLAGS) -c $&lt;

.mli.cmi:
        $(OCAMLC) $(OCAMLFLAGS) -c $&lt;

.ml.cmx:
        $(OCAMLOPT) $(OCAMLOPTFLAGS) -c $&lt;

# Clean up
clean:
        rm -f prog1 prog2
        rm -f *.cm[iox]

# Dependencies
depend:
        $(OCAMLDEP) $(INCLUDES) *.mli *.ml &gt; .depend

include .depend
</pre><p>
If you use module aliases to give shorter names to modules, you need
to change the above definitions. Assuming that your map file is called
<span class="c003">mylib.mli</span>, here are minimal modifications.
</p><pre>OCAMLFLAGS=$(INCLUDES) -open Mylib

mylib.cmi: mylib.mli
        $(OCAMLC) $(INCLUDES) -no-alias-deps -w -49 -c $&lt;

depend:
        $(OCAMLDEP) $(INCLUDES) -map mylib.mli $(PROG1_OBJS:.cmo=.ml) &gt; .depend
</pre><p>Note that in this case you should not compute dependencies for
<span class="c003">mylib.mli</span> together with the other files, hence the need to pass
explicitly the list of files to process.
If <span class="c003">mylib.mli</span> itself has dependencies, you should compute them using
<span class="c003">-as-map</span>.

</p>
<!--TOC chapter id="sec344" Chapter 15  The browser/editor (ocamlbrowser)-->
<h1 class="chapter" id="sec344">Chapter 15  The browser/editor (ocamlbrowser)</h1><!--SEC END --><p> <a id="c:browser"></a>
</p><!--NAME browser.html-->
<p>Since OCaml version 4.02, the OCamlBrowser tool and the Labltk library
are distributed separately from the OCaml compiler. The project is now
hosted at <a href="https://forge.ocamlcore.org/projects/labltk/"><span class="c003">https://forge.ocamlcore.org/projects/labltk/</span></a>.

</p>
<!--TOC chapter id="sec345" Chapter 16  The documentation generator (ocamldoc)-->
<h1 class="chapter" id="sec345">Chapter 16  The documentation generator (ocamldoc)</h1><!--SEC END --><p> <a id="c:ocamldoc"></a>
</p><!--NAME ocamldoc.html-->
<p>This chapter describes OCamldoc, a tool that generates documentation from
special comments embedded in source files. The comments used by OCamldoc
are of the form <span class="c003">(**</span>…<span class="c003">*)</span> and follow the format described
in section <a href="#s%3Aocamldoc-comments">16.2</a>.</p><p>OCamldoc can produce documentation in various formats: HTML, L<sup>A</sup>T<sub>E</sub>X,
TeXinfo, Unix man pages, and <span class="c003">dot</span> dependency graphs. Moreover,
users can add their own custom generators, as explained in
section <a href="#s%3Aocamldoc-custom-generators">16.3</a>.</p><p>In this chapter, we use the word <em>element</em> to refer to any of the
following parts of an OCaml source file: a type declaration, a value,
a module, an exception, a module type, a type constructor, a record
field, a class, a class type, a class method, a class value or a class
inheritance clause.</p>
<!--TOC section id="s:ocamldoc-usage" 16.1  Usage-->
<h2 class="section" id="s:ocamldoc-usage"><a class="section-anchor" href="#s:ocamldoc-usage" aria-hidden="true"></a>16.1  Usage</h2><!--SEC END -->
<!--TOC subsection id="ss:ocamldoc-invocation" 16.1.1  Invocation-->
<h3 class="subsection" id="ss:ocamldoc-invocation"><a class="section-anchor" href="#ss:ocamldoc-invocation" aria-hidden="true"></a>16.1.1  Invocation</h3><!--SEC END --><p>OCamldoc is invoked via the command <span class="c003">ocamldoc</span>, as follows:
</p><pre>
        ocamldoc <span class="c009">options sourcefiles</span>
</pre><!--TOC subsubsection id="sss:ocamldoc-output" Options for choosing the output format-->
<h4 class="subsubsection" id="sss:ocamldoc-output"><a class="section-anchor" href="#sss:ocamldoc-output" aria-hidden="true"></a>Options for choosing the output format</h4><!--SEC END --><p>The following options determine the format for the generated
documentation.</p><dl class="description"><dt class="dt-description">
<span class="c006">-html</span></dt><dd class="dd-description">
Generate documentation in HTML default format. The generated HTML pages
are stored in the current directory, or in the directory specified
with the <span class="c006">-d</span> option. You can customize the style of the
generated pages by editing the generated <span class="c003">style.css</span> file, or by providing
your own style sheet using option <span class="c003">-css-style</span>.
The file <span class="c003">style.css</span> is not generated if it already exists or if -css-style is used.</dd><dt class="dt-description"><span class="c006">-latex</span></dt><dd class="dd-description">
Generate documentation in L<sup>A</sup>T<sub>E</sub>X default format. The generated
L<sup>A</sup>T<sub>E</sub>X document is saved in file <span class="c003">ocamldoc.out</span>, or in the file
specified with the <span class="c006">-o</span> option. The document uses the style file
<span class="c003">ocamldoc.sty</span>. This file is generated when using the <span class="c003">-latex</span> option,
if it does not already exist.
You can change this file to customize the style of your L<sup>A</sup>T<sub>E</sub>X documentation.</dd><dt class="dt-description"><span class="c006">-texi</span></dt><dd class="dd-description">
Generate documentation in TeXinfo default format. The generated
L<sup>A</sup>T<sub>E</sub>X document is saved in file <span class="c003">ocamldoc.out</span>, or in the file
specified with the <span class="c006">-o</span> option.</dd><dt class="dt-description"><span class="c006">-man</span></dt><dd class="dd-description">
Generate documentation as a set of Unix <span class="c003">man</span> pages. The generated pages
are stored in the current directory, or in the directory specified
with the <span class="c006">-d</span> option.</dd><dt class="dt-description"><span class="c006">-dot</span></dt><dd class="dd-description">
Generate a dependency graph for the toplevel modules, in a format suitable
for displaying and processing by <span class="c003">dot</span>. The <span class="c003">dot</span> tool is available from
<a href="https://graphviz.org/"><span class="c003">https://graphviz.org/</span></a>.
The textual representation of the graph is written to the file
<span class="c003">ocamldoc.out</span>, or to the file specified with the <span class="c006">-o</span> option.
Use <span class="c003">dot ocamldoc.out</span> to display it.</dd><dt class="dt-description"><span class="c013"><span class="c003">-g</span> <span class="c009">file.cm[o,a,xs]</span></span></dt><dd class="dd-description">
Dynamically load the given file, which defines a custom documentation
generator. See section <a href="#ss%3Aocamldoc-compilation-and-usage">16.4.1</a>. This
option is supported by the <span class="c003">ocamldoc</span> command (to load <span class="c003">.cmo</span> and <span class="c003">.cma</span> files)
and by its native-code version <span class="c003">ocamldoc.opt</span> (to load <span class="c003">.cmxs</span> files).
If the given file is a simple one and does not exist in
the current directory, then ocamldoc looks for it in the custom
generators default directory, and in the directories specified with
optional <span class="c003">-i</span> options.</dd><dt class="dt-description"><span class="c006">-customdir</span></dt><dd class="dd-description">
Display the custom generators default directory.</dd><dt class="dt-description"><span class="c013"><span class="c003">-i</span> <span class="c009">directory</span></span></dt><dd class="dd-description">
Add the given directory to the path where to look for custom generators.</dd></dl><!--TOC subsubsection id="sss:ocamldoc-options" General options-->
<h4 class="subsubsection" id="sss:ocamldoc-options"><a class="section-anchor" href="#sss:ocamldoc-options" aria-hidden="true"></a>General options</h4><!--SEC END --><dl class="description"><dt class="dt-description"><span class="c013"><span class="c003">-d</span> <span class="c009">dir</span></span></dt><dd class="dd-description">
Generate files in directory <span class="c009">dir</span>, rather than the current directory.</dd><dt class="dt-description"><span class="c013"><span class="c003">-dump</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Dump collected information into <span class="c009">file</span>. This information can be
read with the <span class="c003">-load</span> option in a subsequent invocation of <span class="c003">ocamldoc</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-hide</span> <span class="c009">modules</span></span></dt><dd class="dd-description">
Hide the given complete module names in the generated documentation.
<span class="c009">modules</span> is a list of complete module names separated
by ’<span class="c003">,</span>’, without blanks. For instance: <span class="c003">Stdlib,M2.M3</span>.</dd><dt class="dt-description"><span class="c006">-inv-merge-ml-mli</span></dt><dd class="dd-description">
Reverse the precedence of implementations and interfaces when merging.
All elements
in implementation files are kept, and the <span class="c006">-m</span> option
indicates which parts of the comments in interface files are merged
with the comments in implementation files.</dd><dt class="dt-description"><span class="c006">-keep-code</span></dt><dd class="dd-description">
Always keep the source code for values, methods and instance variables,
when available.</dd><dt class="dt-description"><span class="c013"><span class="c003">-load</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Load information from <span class="c009">file</span>, which has been produced by
<span class="c003">ocamldoc -dump</span>. Several <span class="c003">-load</span> options can be given.</dd><dt class="dt-description"><span class="c013"><span class="c003">-m</span> <span class="c009">flags</span></span></dt><dd class="dd-description">
Specify merge options between interfaces and implementations.
(see section <a href="#ss%3Aocamldoc-merge">16.1.2</a> for details).
<span class="c009">flags</span> can be one or several of the following characters:
<dl class="description"><dt class="dt-description">
<span class="c006">d</span></dt><dd class="dd-description"> merge description
</dd><dt class="dt-description"><span class="c006">a</span></dt><dd class="dd-description"> merge <span class="c003">@author</span>
</dd><dt class="dt-description"><span class="c006">v</span></dt><dd class="dd-description"> merge <span class="c003">@version</span>
</dd><dt class="dt-description"><span class="c006">l</span></dt><dd class="dd-description"> merge <span class="c003">@see</span>
</dd><dt class="dt-description"><span class="c006">s</span></dt><dd class="dd-description"> merge <span class="c003">@since</span>
</dd><dt class="dt-description"><span class="c006">b</span></dt><dd class="dd-description"> merge <span class="c003">@before</span>
</dd><dt class="dt-description"><span class="c006">o</span></dt><dd class="dd-description"> merge <span class="c003">@deprecated</span>
</dd><dt class="dt-description"><span class="c006">p</span></dt><dd class="dd-description"> merge <span class="c003">@param</span>
</dd><dt class="dt-description"><span class="c006">e</span></dt><dd class="dd-description"> merge <span class="c003">@raise</span>
</dd><dt class="dt-description"><span class="c006">r</span></dt><dd class="dd-description"> merge <span class="c003">@return</span>
</dd><dt class="dt-description"><span class="c006">A</span></dt><dd class="dd-description"> merge everything
</dd></dl></dd><dt class="dt-description"><span class="c006">-no-custom-tags</span></dt><dd class="dd-description">
Do not allow custom @-tags (see section <a href="#ss%3Aocamldoc-tags">16.2.5</a>).</dd><dt class="dt-description"><span class="c006">-no-stop</span></dt><dd class="dd-description">
Keep elements placed after/between the <span class="c003">(**/**)</span> special comment(s)
(see section <a href="#s%3Aocamldoc-comments">16.2</a>).</dd><dt class="dt-description"><span class="c013"><span class="c003">-o</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Output the generated documentation to <span class="c009">file</span> instead of <span class="c003">ocamldoc.out</span>.
This option is meaningful only in conjunction with the
<span class="c006">-latex</span>, <span class="c006">-texi</span>, or <span class="c006">-dot</span> options.</dd><dt class="dt-description"><span class="c013"><span class="c003">-pp</span> <span class="c009">command</span></span></dt><dd class="dd-description">
Pipe sources through preprocessor <span class="c009">command</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-impl</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Process the file <span class="c009">filename</span> as an implementation file, even if its
extension is not <span class="c003">.ml</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-intf</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Process the file <span class="c009">filename</span> as an interface file, even if its
extension is not <span class="c003">.mli</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-text</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Process the file <span class="c009">filename</span> as a text file, even if its
extension is not <span class="c003">.txt</span>.</dd><dt class="dt-description"><span class="c006">-sort</span></dt><dd class="dd-description">
Sort the list of top-level modules before generating the documentation.</dd><dt class="dt-description"><span class="c006">-stars</span></dt><dd class="dd-description">
Remove blank characters until the first asterisk (’<span class="c003">*</span>’) in each
line of comments.</dd><dt class="dt-description"><span class="c013"><span class="c003">-t</span> <span class="c009">title</span></span></dt><dd class="dd-description">
Use <span class="c009">title</span> as the title for the generated documentation.</dd><dt class="dt-description"><span class="c013"><span class="c003">-intro</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Use content of <span class="c009">file</span> as ocamldoc text to use as introduction (HTML,
L<sup>A</sup>T<sub>E</sub>X and TeXinfo only).
For HTML, the file is used to create the whole <span class="c003">index.html</span> file.</dd><dt class="dt-description"><span class="c006">-v</span></dt><dd class="dd-description">
Verbose mode. Display progress information.</dd><dt class="dt-description"><span class="c006">-version</span></dt><dd class="dd-description">
Print version string and exit.</dd><dt class="dt-description"><span class="c006">-vnum</span></dt><dd class="dd-description">
Print short version number and exit.</dd><dt class="dt-description"><span class="c006">-warn-error</span></dt><dd class="dd-description">
Treat Ocamldoc warnings as errors.</dd><dt class="dt-description"><span class="c006">-hide-warnings</span></dt><dd class="dd-description">
Do not print OCamldoc warnings.</dd><dt class="dt-description"><span class="c013"><span class="c003">-help</span> or <span class="c003">--help</span></span></dt><dd class="dd-description">
Display a short usage summary and exit.
</dd></dl><!--TOC subsubsection id="sss:ocamldoc-type-checking" Type-checking options-->
<h4 class="subsubsection" id="sss:ocamldoc-type-checking"><a class="section-anchor" href="#sss:ocamldoc-type-checking" aria-hidden="true"></a>Type-checking options</h4><!--SEC END --><p>OCamldoc calls the OCaml type-checker to obtain type
information. The following options impact the type-checking phase.
They have the same meaning as for the <span class="c003">ocamlc</span> and <span class="c003">ocamlopt</span> commands.</p><dl class="description"><dt class="dt-description"><span class="c013"><span class="c003">-I</span> <span class="c009">directory</span></span></dt><dd class="dd-description">
Add <span class="c009">directory</span> to the list of directories search for compiled
interface files (<span class="c003">.cmi</span> files).</dd><dt class="dt-description"><span class="c006">-nolabels</span></dt><dd class="dd-description">
Ignore non-optional labels in types.</dd><dt class="dt-description"><span class="c006">-rectypes</span></dt><dd class="dd-description">
Allow arbitrary recursive types. (See the <span class="c003">-rectypes</span> option to <span class="c003">ocamlc</span>.)</dd></dl><!--TOC subsubsection id="sss:ocamldoc-html" Options for generating HTML pages-->
<h4 class="subsubsection" id="sss:ocamldoc-html"><a class="section-anchor" href="#sss:ocamldoc-html" aria-hidden="true"></a>Options for generating HTML pages</h4><!--SEC END --><p>The following options apply in conjunction with the <span class="c003">-html</span> option:</p><dl class="description"><dt class="dt-description">
<span class="c006">-all-params</span></dt><dd class="dd-description">
Display the complete list of parameters for functions and methods.</dd><dt class="dt-description"><span class="c013"><span class="c003">-charset</span> <span class="c009">charset</span></span></dt><dd class="dd-description">
Add information about character encoding being <span class="c009">charset</span>
(default is iso-8859-1).</dd><dt class="dt-description"><span class="c006">-colorize-code</span></dt><dd class="dd-description">
Colorize the OCaml code enclosed in <span class="c003">[ ]</span> and <span class="c003">{[ ]}</span>, using colors
to emphasize keywords, etc. If the code fragments are not
syntactically correct, no color is added.</dd><dt class="dt-description"><span class="c013"><span class="c003">-css-style</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Use <span class="c009">filename</span> as the Cascading Style Sheet file.</dd><dt class="dt-description"><span class="c006">-index-only</span></dt><dd class="dd-description">
Generate only index files.</dd><dt class="dt-description"><span class="c006">-short-functors</span></dt><dd class="dd-description">
Use a short form to display functors:
<pre>
module M : functor (A:Module) -&gt; functor (B:Module2) -&gt; sig .. end
</pre>
is displayed as:
<pre>
module M (A:Module) (B:Module2) : sig .. end
</pre></dd></dl><!--TOC subsubsection id="sss:ocamldoc-latex" Options for generating L<sup>A</sup>T<sub>E</sub>X files-->
<h4 class="subsubsection" id="sss:ocamldoc-latex"><a class="section-anchor" href="#sss:ocamldoc-latex" aria-hidden="true"></a>Options for generating L<sup>A</sup>T<sub>E</sub>X files</h4><!--SEC END --><p>The following options apply in conjunction with the <span class="c003">-latex</span> option:</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">-latex-value-prefix</span> <span class="c009">prefix</span></span></dt><dd class="dd-description">
Give a prefix to use for the labels of the values in the generated
L<sup>A</sup>T<sub>E</sub>X document.
The default prefix is the empty string. You can also use the options
<span class="c003">-latex-type-prefix</span>, <span class="c003">-latex-exception-prefix</span>,
<span class="c003">-latex-module-prefix</span>,
<span class="c003">-latex-module-type-prefix</span>, <span class="c003">-latex-class-prefix</span>,
<span class="c003">-latex-class-type-prefix</span>,
<span class="c003">-latex-attribute-prefix</span> and <span class="c003">-latex-method-prefix</span>.<p>These options are useful when you have, for example, a type and a value with
the same name. If you do not specify prefixes, L<sup>A</sup>T<sub>E</sub>X will complain about
multiply defined labels.</p></dd><dt class="dt-description"><span class="c013"><span class="c003">-latextitle</span> <span class="c009">n,style</span></span></dt><dd class="dd-description">
Associate style number <span class="c009">n</span> to the given L<sup>A</sup>T<sub>E</sub>X sectioning command
<span class="c009">style</span>, e.g. <span class="c003">section</span> or <span class="c003">subsection</span>. (L<sup>A</sup>T<sub>E</sub>X only.) This is
useful when including the generated document in another L<sup>A</sup>T<sub>E</sub>X document,
at a given sectioning level. The default association is 1 for <span class="c003">section</span>,
2 for <span class="c003">subsection</span>, 3 for <span class="c003">subsubsection</span>, 4 for <span class="c003">paragraph</span> and 5 for
<span class="c003">subparagraph</span>.</dd><dt class="dt-description"><span class="c006">-noheader</span></dt><dd class="dd-description">
Suppress header in generated documentation.</dd><dt class="dt-description"><span class="c006">-notoc</span></dt><dd class="dd-description">
Do not generate a table of contents.</dd><dt class="dt-description"><span class="c006">-notrailer</span></dt><dd class="dd-description">
Suppress trailer in generated documentation.</dd><dt class="dt-description"><span class="c006">-sepfiles</span></dt><dd class="dd-description">
Generate one <span class="c003">.tex</span> file per toplevel module, instead of the global
<span class="c003">ocamldoc.out</span> file.
</dd></dl><!--TOC subsubsection id="sss:ocamldoc-info" Options for generating TeXinfo files-->
<h4 class="subsubsection" id="sss:ocamldoc-info"><a class="section-anchor" href="#sss:ocamldoc-info" aria-hidden="true"></a>Options for generating TeXinfo files</h4><!--SEC END --><p>The following options apply in conjunction with the <span class="c003">-texi</span> option:</p><dl class="description"><dt class="dt-description">
<span class="c006">-esc8</span></dt><dd class="dd-description">
Escape accented characters in Info files.</dd><dt class="dt-description"><span class="c006">-info-entry</span></dt><dd class="dd-description">
Specify Info directory entry.</dd><dt class="dt-description"><span class="c006">-info-section</span></dt><dd class="dd-description">
Specify section of Info directory.</dd><dt class="dt-description"><span class="c006">-noheader</span></dt><dd class="dd-description">
Suppress header in generated documentation.</dd><dt class="dt-description"><span class="c006">-noindex</span></dt><dd class="dd-description">
Do not build index for Info files.</dd><dt class="dt-description"><span class="c006">-notrailer</span></dt><dd class="dd-description">
Suppress trailer in generated documentation.
</dd></dl><!--TOC subsubsection id="sss:ocamldoc-dot" Options for generating <span class="c003">dot</span> graphs-->
<h4 class="subsubsection" id="sss:ocamldoc-dot"><a class="section-anchor" href="#sss:ocamldoc-dot" aria-hidden="true"></a>Options for generating <span class="c003">dot</span> graphs</h4><!--SEC END --><p>The following options apply in conjunction with the <span class="c003">-dot</span> option:</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">-dot-colors</span> <span class="c009">colors</span></span></dt><dd class="dd-description">
Specify the colors to use in the generated <span class="c003">dot</span> code.
When generating module dependencies, <span class="c003">ocamldoc</span> uses different colors
for modules, depending on the directories in which they reside.
When generating types dependencies, <span class="c003">ocamldoc</span> uses different colors
for types, depending on the modules in which they are defined.
<span class="c009">colors</span> is a list of color names separated by ’<span class="c003">,</span>’, as
in <span class="c003">Red,Blue,Green</span>. The available colors are the ones supported by
the <span class="c003">dot</span> tool.</dd><dt class="dt-description"><span class="c006">-dot-include-all</span></dt><dd class="dd-description">
Include all modules in the <span class="c003">dot</span> output, not only modules given
on the command line or loaded with the <span class="c006">-load</span> option.</dd><dt class="dt-description"><span class="c006">-dot-reduce</span></dt><dd class="dd-description">
Perform a transitive reduction of the dependency graph before
outputting the <span class="c003">dot</span> code. This can be useful if there are
a lot of transitive dependencies that clutter the graph.</dd><dt class="dt-description"><span class="c006">-dot-types</span></dt><dd class="dd-description">
Output <span class="c003">dot</span> code describing the type dependency graph instead of
the module dependency graph.
</dd></dl><!--TOC subsubsection id="sss:ocamldoc-man" Options for generating man files-->
<h4 class="subsubsection" id="sss:ocamldoc-man"><a class="section-anchor" href="#sss:ocamldoc-man" aria-hidden="true"></a>Options for generating man files</h4><!--SEC END --><p>The following options apply in conjunction with the <span class="c003">-man</span> option:</p><dl class="description"><dt class="dt-description">
<span class="c006">-man-mini</span></dt><dd class="dd-description">
Generate man pages only for modules, module types, classes and class
types, instead of pages for all elements.</dd><dt class="dt-description"><span class="c013"><span class="c003">-man-suffix</span> <span class="c009">suffix</span></span></dt><dd class="dd-description">
Set the suffix used for generated man filenames. Default is ’<span class="c003">3o</span>’,
as in <span class="c003">List.3o</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-man-section</span> <span class="c009">section</span></span></dt><dd class="dd-description">
Set the section number used for generated man filenames. Default is ’<span class="c003">3</span>’.</dd></dl>
<!--TOC subsection id="ss:ocamldoc-merge" 16.1.2  Merging of module information-->
<h3 class="subsection" id="ss:ocamldoc-merge"><a class="section-anchor" href="#ss:ocamldoc-merge" aria-hidden="true"></a>16.1.2  Merging of module information</h3><!--SEC END --><p>Information on a module can be extracted either from the <span class="c003">.mli</span> or <span class="c003">.ml</span>
file, or both, depending on the files given on the command line.
When both <span class="c003">.mli</span> and <span class="c003">.ml</span> files are given for the same module,
information extracted from these files is merged according to the
following rules:
</p><ul class="itemize"><li class="li-itemize">
Only elements (values, types, classes, ...) declared in the <span class="c003">.mli</span>
file are kept. In other terms, definitions from the <span class="c003">.ml</span> file that are
not exported in the <span class="c003">.mli</span> file are not documented.
</li><li class="li-itemize">Descriptions of elements and descriptions in @-tags are handled
as follows. If a description for the same element or in the same
@-tag of the same element is present in both files, then the
description of the <span class="c003">.ml</span> file is concatenated to the one in the <span class="c003">.mli</span> file,
if the corresponding <span class="c003">-m</span> flag is given on the command line.
If a description is present in the <span class="c003">.ml</span> file and not in the
<span class="c003">.mli</span> file, the <span class="c003">.ml</span> description is kept.
In either case, all the information given in the <span class="c003">.mli</span> file is kept.
</li></ul>
<!--TOC subsection id="ss:ocamldoc-rules" 16.1.3  Coding rules-->
<h3 class="subsection" id="ss:ocamldoc-rules"><a class="section-anchor" href="#ss:ocamldoc-rules" aria-hidden="true"></a>16.1.3  Coding rules</h3><!--SEC END --><p>
The following rules must be respected in order to avoid name clashes
resulting in cross-reference errors:
</p><ul class="itemize"><li class="li-itemize">
In a module, there must not be two modules, two module types or
a module and a module type with the same name.
In the default HTML generator, modules <span class="c003">ab</span> and <span class="c003">AB</span> will be printed
to the same file on case insensitive file systems.
</li><li class="li-itemize">In a module, there must not be two classes, two class types or
a class and a class type with the same name.
</li><li class="li-itemize">In a module, there must not be two values, two types, or two
exceptions with the same name.
</li><li class="li-itemize">Values defined in tuple, as in <span class="c003">let (x,y,z) = (1,2,3)</span>
are not kept by OCamldoc.
</li><li class="li-itemize">Avoid the following construction:


<div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">open</span> Foo <span class="ocamlcomment">(* which has a module Bar with a value x *)</span>
 <span class="ocamlkeyword">module</span> Foo =
   <span class="ocamlkeyword">struct</span>
     <span class="ocamlkeyword">module</span> Bar =
       <span class="ocamlkeyword">struct</span>
         <span class="ocamlkeyword">let</span> x = 1
       <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">end</span>
   <span class="ocamlkeyword">let</span> dummy = Bar.x</div></div>

</div>


In this case, OCamldoc will associate <span class="c003">Bar.x</span> to the <span class="c003">x</span> of module
<span class="c003">Foo</span> defined just above, instead of to the <span class="c003">Bar.x</span> defined in the
opened module <span class="c003">Foo</span>.
</li></ul>
<!--TOC section id="s:ocamldoc-comments" 16.2  Syntax of documentation comments-->
<h2 class="section" id="s:ocamldoc-comments"><a class="section-anchor" href="#s:ocamldoc-comments" aria-hidden="true"></a>16.2  Syntax of documentation comments</h2><!--SEC END --><p>Comments containing documentation material are called <em>special
comments</em> and are written between <span class="c003">(**</span> and <span class="c003">*)</span>. Special comments
must start exactly with <span class="c003">(**</span>. Comments beginning with <span class="c003">(</span> and more
than two <span class="c003">*</span> are ignored.</p>
<!--TOC subsection id="ss:ocamldoc-placement" 16.2.1  Placement of documentation comments-->
<h3 class="subsection" id="ss:ocamldoc-placement"><a class="section-anchor" href="#ss:ocamldoc-placement" aria-hidden="true"></a>16.2.1  Placement of documentation comments</h3><!--SEC END --><p>
OCamldoc can associate comments to some elements of the language
encountered in the source files. The association is made according to
the locations of comments with respect to the language elements. The
locations of comments in <span class="c003">.mli</span> and <span class="c003">.ml</span> files are different.</p>
<!--TOC subsubsection id="sss:ocamldoc-mli" Comments in <span class="c003">.mli</span> files-->
<h4 class="subsubsection" id="sss:ocamldoc-mli"><a class="section-anchor" href="#sss:ocamldoc-mli" aria-hidden="true"></a>Comments in <span class="c003">.mli</span> files</h4><!--SEC END --><p>
A special comment is associated to an element if it is placed before or
after the element.<br>
A special comment before an element is associated to this element if :
</p><ul class="itemize"><li class="li-itemize">
There is no blank line or another special comment between the special
comment and the element. However, a regular comment can occur between
the special comment and the element.
</li><li class="li-itemize">The special comment is not already associated to the previous element.
</li><li class="li-itemize">The special comment is not the first one of a toplevel module.
</li></ul><p>A special comment after an element is associated to this element if
there is no blank line or comment between the special comment and the
element.</p><p>There are two exceptions: for constructors and record fields in
type definitions, the associated comment can only be placed after the
constructor or field definition, without blank lines or other comments
between them. The special comment for a constructor
with another constructor following must be placed before the ’<span class="c003">|</span>’
character separating the two constructors.</p><p>The following sample interface file <span class="c003">foo.mli</span> illustrates the
placement rules for comments in <span class="c003">.mli</span> files.</p><div class="caml-example signature">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlcomment">(** The first special comment of the file is the comment associated
     with the whole module.*)</span>


 <span class="ocamlcomment">(** Special comments can be placed between elements and are kept
     by the OCamldoc tool, but are not associated to any element.
     @-tags in these comments are ignored.*)</span>

 <span class="ocamlcomment">(*******************************************************************)</span>
 <span class="ocamlcomment">(** Comments like the one above, with more than two asterisks,
     are ignored. *)</span>

 <span class="ocamlcomment">(** The comment for function f. *)</span>
 <span class="ocamlkeyword">val</span> f : int -&gt; int -&gt; int
 <span class="ocamlcomment">(** The continuation of the comment for function f. *)</span>

 <span class="ocamlcomment">(** Comment for exception My_exception, even with a simple comment
     between the special comment and the exception.*)</span>
 <span class="ocamlcomment">(* Hello, I'm a simple comment :-) *)</span>
 <span class="ocamlkeyword">exception</span> My_exception <span class="ocamlkeyword">of</span> (int -&gt; int) * int

 <span class="ocamlcomment">(** Comment for type weather  *)</span>
 <span class="ocamlkeyword">type</span> weather =
 | Rain <span class="ocamlkeyword">of</span> int <span class="ocamlcomment">(** The comment for constructor Rain *)</span>
 | Sun <span class="ocamlcomment">(** The comment for constructor Sun *)</span>

 <span class="ocamlcomment">(** Comment for type weather2  *)</span>
 <span class="ocamlkeyword">type</span> weather2 =
 | Rain <span class="ocamlkeyword">of</span> int <span class="ocamlcomment">(** The comment for constructor Rain *)</span>
 | Sun <span class="ocamlcomment">(** The comment for constructor Sun *)</span>
 <span class="ocamlcomment">(** I can continue the comment for type weather2 here
   because there is already a comment associated to the last constructor.*)</span>

 <span class="ocamlcomment">(** The comment for type my_record *)</span>
 <span class="ocamlkeyword">type</span> my_record = {
     foo : int ;    <span class="ocamlcomment">(** Comment for field foo *)</span>
     bar : string ; <span class="ocamlcomment">(** Comment for field bar *)</span>
   }
   <span class="ocamlcomment">(** Continuation of comment for type my_record *)</span>

 <span class="ocamlcomment">(** Comment for foo *)</span>
 <span class="ocamlkeyword">val</span> foo : string
 <span class="ocamlcomment">(** This comment is associated to foo and not to bar. *)</span>
 <span class="ocamlkeyword">val</span> bar : string
 <span class="ocamlcomment">(** This comment is associated to bar. *)</span>

 <span class="ocamlcomment">(** The comment for class my_class *)</span>
 <span class="ocamlkeyword">class</span> my_class :
   <span class="ocamlkeyword">object</span>
     <span class="ocamlcomment">(** A comment to describe inheritance from cl *)</span>
     <span class="ocamlkeyword">inherit</span> cl

     <span class="ocamlcomment">(** The comment for attribute tutu *)</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> tutu : string

     <span class="ocamlcomment">(** The comment for attribute toto. *)</span>
     <span class="ocamlkeyword">val</span> toto : int

     <span class="ocamlcomment">(** This comment is not attached to titi since
         there is a blank line before titi, but is kept
         as a comment in the class. *)</span>

     <span class="ocamlkeyword">val</span> titi : string

     <span class="ocamlcomment">(** Comment for method toto *)</span>
     <span class="ocamlkeyword">method</span> toto : string

     <span class="ocamlcomment">(** Comment for method m *)</span>
     <span class="ocamlkeyword">method</span> m : float -&gt; int
   <span class="ocamlkeyword">end</span>

 <span class="ocamlcomment">(** The comment for the class type my_class_type *)</span>
 <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> my_class_type =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlcomment">(** The comment for variable x. *)</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int

     <span class="ocamlcomment">(** The comment for method m. *)</span>
     <span class="ocamlkeyword">method</span> m : int -&gt; int
 <span class="ocamlkeyword">end</span>

 <span class="ocamlcomment">(** The comment for module Foo *)</span>
 <span class="ocamlkeyword">module</span> Foo :
   <span class="ocamlkeyword">sig</span>
     <span class="ocamlcomment">(** The comment for x *)</span>
     <span class="ocamlkeyword">val</span> x : int

     <span class="ocamlcomment">(** A special comment that is kept but not associated to any element *)</span>
   <span class="ocamlkeyword">end</span>

 <span class="ocamlcomment">(** The comment for module type my_module_type. *)</span>
 <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> my_module_type =
   <span class="ocamlkeyword">sig</span>
     <span class="ocamlcomment">(** The comment for value x. *)</span>
     <span class="ocamlkeyword">val</span> x : int

     <span class="ocamlcomment">(** The comment for module M. *)</span>
     <span class="ocamlkeyword">module</span> M :
       <span class="ocamlkeyword">sig</span>
         <span class="ocamlcomment">(** The comment for value y. *)</span>
         <span class="ocamlkeyword">val</span> y : int

         <span class="ocamlcomment">(* ... *)</span>
       <span class="ocamlkeyword">end</span>

   <span class="ocamlkeyword">end</span></div></div>

</div>
<!--TOC subsubsection id="sss:ocamldoc-comments-ml" Comments in <span class="c003">.ml</span> files-->
<h4 class="subsubsection" id="sss:ocamldoc-comments-ml"><a class="section-anchor" href="#sss:ocamldoc-comments-ml" aria-hidden="true"></a>Comments in <span class="c003">.ml</span> files</h4><!--SEC END --><p>A special comment is associated to an element if it is placed before
the element and there is no blank line between the comment and the
element. Meanwhile, there can be a simple comment between the special
comment and the element. There are two exceptions, for
constructors and record fields in type definitions, whose associated
comment must be placed after the constructor or field definition,
without blank line between them. The special comment for a constructor
with another constructor following must be placed before the ’<span class="c003">|</span>’
character separating the two constructors.</p><p>The following example of file <span class="c003">toto.ml</span> shows where to place comments
in a <span class="c003">.ml</span> file.</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlcomment">(** The first special comment of the file is the comment associated
     to the whole module. *)</span>

 <span class="ocamlcomment">(** The comment for function f *)</span>
 <span class="ocamlkeyword">let</span> f x y = x + y

 <span class="ocamlcomment">(** This comment is not attached to any element since there is another
     special comment just before the next element. *)</span>

 <span class="ocamlcomment">(** Comment for exception My_exception, even with a simple comment
     between the special comment and the exception.*)</span>
 <span class="ocamlcomment">(* A simple comment. *)</span>
 <span class="ocamlkeyword">exception</span> My_exception <span class="ocamlkeyword">of</span> (int -&gt; int) * int

 <span class="ocamlcomment">(** Comment for type weather  *)</span>
 <span class="ocamlkeyword">type</span> weather =
 | Rain <span class="ocamlkeyword">of</span> int <span class="ocamlcomment">(** The comment for constructor Rain *)</span>
 | Sun <span class="ocamlcomment">(** The comment for constructor Sun *)</span>

 <span class="ocamlcomment">(** The comment for type my_record *)</span>
 <span class="ocamlkeyword">type</span> my_record = {
     foo : int ;    <span class="ocamlcomment">(** Comment for field foo *)</span>
     bar : string ; <span class="ocamlcomment">(** Comment for field bar *)</span>
   }

 <span class="ocamlcomment">(** The comment for class my_class *)</span>
 <span class="ocamlkeyword">class</span> my_class =
     <span class="ocamlkeyword">object</span>
       <span class="ocamlcomment">(** A comment to describe inheritance from cl *)</span>
       <span class="ocamlkeyword">inherit</span> cl

       <span class="ocamlcomment">(** The comment for the instance variable tutu *)</span>
       <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> tutu = <span class="ocamlstring">"tutu"</span>
       <span class="ocamlcomment">(** The comment for toto *)</span>
       <span class="ocamlkeyword">val</span> toto = 1
       <span class="ocamlkeyword">val</span> titi = <span class="ocamlstring">"titi"</span>
       <span class="ocamlcomment">(** Comment for method toto *)</span>
       <span class="ocamlkeyword">method</span> toto = tutu ^ <span class="ocamlstring">"!"</span>
       <span class="ocamlcomment">(** Comment for method m *)</span>
       <span class="ocamlkeyword">method</span> m (f : float) = 1
     <span class="ocamlkeyword">end</span>

 <span class="ocamlcomment">(** The comment for class type my_class_type *)</span>
 <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> my_class_type =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlcomment">(** The comment for the instance variable x. *)</span>
     <span class="ocamlkeyword">val</span> <span class="ocamlkeyword">mutable</span> x : int
     <span class="ocamlcomment">(** The comment for method m. *)</span>
     <span class="ocamlkeyword">method</span> m : int -&gt; int
   <span class="ocamlkeyword">end</span>

 <span class="ocamlcomment">(** The comment for module Foo *)</span>
 <span class="ocamlkeyword">module</span> Foo =
   <span class="ocamlkeyword">struct</span>
     <span class="ocamlcomment">(** The comment for x *)</span>
     <span class="ocamlkeyword">let</span> x = 0
     <span class="ocamlcomment">(** A special comment in the class, but not associated to any element. *)</span>
   <span class="ocamlkeyword">end</span>

 <span class="ocamlcomment">(** The comment for module type my_module_type. *)</span>
 <span class="ocamlkeyword">module</span> <span class="ocamlkeyword">type</span> my_module_type =
   <span class="ocamlkeyword">sig</span>
     <span class="ocamlcomment">(* Comment for value x. *)</span>
     <span class="ocamlkeyword">val</span> x : int
     <span class="ocamlcomment">(* ... *)</span>
   <span class="ocamlkeyword">end</span></div></div>

</div>
<!--TOC subsection id="ss:ocamldoc-stop" 16.2.2  The Stop special comment-->
<h3 class="subsection" id="ss:ocamldoc-stop"><a class="section-anchor" href="#ss:ocamldoc-stop" aria-hidden="true"></a>16.2.2  The Stop special comment</h3><!--SEC END --><p>
The special comment <span class="c003">(**/**)</span> tells OCamldoc to discard
elements placed after this comment, up to the end of the current
class, class type, module or module type, or up to the next stop comment.
For instance:


</p><div class="caml-example signature">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">class</span> <span class="ocamlkeyword">type</span> foo =
   <span class="ocamlkeyword">object</span>
     <span class="ocamlcomment">(** comment for method m *)</span>
     <span class="ocamlkeyword">method</span> m : string

     <span class="ocamlcomment">(**/**)</span>

     <span class="ocamlcomment">(** This method won't appear in the documentation *)</span>
     <span class="ocamlkeyword">method</span> bar : int
   <span class="ocamlkeyword">end</span>

 <span class="ocamlcomment">(** This value appears in the documentation, since the Stop special comment
     in the class does not affect the parent module of the class.*)</span>
 <span class="ocamlkeyword">val</span> foo : string

 <span class="ocamlcomment">(**/**)</span>
 <span class="ocamlcomment">(** The value bar does not appear in the documentation.*)</span>
 <span class="ocamlkeyword">val</span> bar : string
 <span class="ocamlcomment">(**/**)</span>

 <span class="ocamlcomment">(** The type t appears since in the documentation since the previous stop comment
 toggled off the "no documentation mode". *)</span>
 <span class="ocamlkeyword">type</span> t = string</div></div>

</div><p>The <span class="c006">-no-stop</span> option to <span class="c003">ocamldoc</span> causes the Stop special
comments to be ignored.</p>
<!--TOC subsection id="ss:ocamldoc-syntax" 16.2.3  Syntax of documentation comments-->
<h3 class="subsection" id="ss:ocamldoc-syntax"><a class="section-anchor" href="#ss:ocamldoc-syntax" aria-hidden="true"></a>16.2.3  Syntax of documentation comments</h3><!--SEC END --><p>The inside of documentation comments <span class="c003">(**</span>…<span class="c003">*)</span> consists of
free-form text with optional formatting annotations, followed by
optional <em>tags</em> giving more specific information about parameters,
version, authors, … The tags are distinguished by a leading <span class="c003">@</span>
character. Thus, a documentation comment has the following shape:
</p><pre>(** The comment begins with a description, which is text formatted
   according to the rules described in the next section.
   The description continues until the first non-escaped '@' character.
   @author Mr Smith
   @param x description for parameter x
*)
</pre><p>Some elements support only a subset of all @-tags. Tags that are not
relevant to the documented element are simply ignored. For instance,
all tags are ignored when documenting type constructors, record
fields, and class inheritance clauses. Similarly, a <span class="c003">@param</span> tag on a
class instance variable is ignored.</p><p>At last, <span class="c003">(**)</span> is the empty documentation comment.</p>
<!--TOC subsection id="ss:ocamldoc-formatting" 16.2.4  Text formatting-->
<h3 class="subsection" id="ss:ocamldoc-formatting"><a class="section-anchor" href="#ss:ocamldoc-formatting" aria-hidden="true"></a>16.2.4  Text formatting</h3><!--SEC END --><p>Here is the BNF grammar for the simple markup language used to format
text descriptions.</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="text"><span class="c010">text</span></a></td><td class="c015">::=</td><td class="c017"> {<a class="syntax" href="#text-element"><span class="c010">text-element</span></a>}<sup>+</sup>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
</table></td></tr>
</table></div><div class="syntaxleft"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="text-element"><span class="c010">text-element</span></a></td><td class="c015">::=</td></tr>
</table></div><table class="c001 cellpading0"><tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{</span> { <span class="c004">0</span> … <span class="c004">9</span> }<sup>+</sup> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">format <a class="syntax" href="#text"><span class="c010">text</span></a> as a section header;
the integer following <span class="c003">{</span> indicates the sectioning level. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{</span> { <span class="c004">0</span> … <span class="c004">9</span> }<sup>+</sup> <span class="c004">:</span>  <span class="c010">label</span>  <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020"> same, but also associate the name <span class="c010">label</span> to the current point.
This point can be referenced by its fully-qualified label in a
<span class="c003">{!</span> command, just like any other element. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{b</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">set <a class="syntax" href="#text"><span class="c010">text</span></a> in bold. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{i</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">set <a class="syntax" href="#text"><span class="c010">text</span></a> in italic. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{e</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">emphasize <a class="syntax" href="#text"><span class="c010">text</span></a>. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{C</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">center <a class="syntax" href="#text"><span class="c010">text</span></a>. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{L</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">left align <a class="syntax" href="#text"><span class="c010">text</span></a>. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{R</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">right align <a class="syntax" href="#text"><span class="c010">text</span></a>. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{ul</span> <a class="syntax" href="#list"><span class="c010">list</span></a> <span class="c004">}</span> </td><td class="c020">build a list. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{ol</span> <a class="syntax" href="#list"><span class="c010">list</span></a> <span class="c004">}</span> </td><td class="c020">build an enumerated list. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c002"><span class="c003">{{:</span> <span class="c010">string</span> <span class="c003">}</span></span>  <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">put a link to the given address
(given as <span class="c010">string</span>) on the given <a class="syntax" href="#text"><span class="c010">text</span></a>. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c002"><span class="c003">[</span> <span class="c010">string</span> <span class="c003">]</span></span> </td><td class="c020">set the given <span class="c010">string</span> in source code style. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c002"><span class="c003">{[</span> <span class="c010">string</span> <span class="c003">]}</span></span> </td><td class="c020">set the given <span class="c010">string</span> in preformatted
				source code style.</td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c002"><span class="c003">{v</span> <span class="c010">string</span> <span class="c003">v}</span></span> </td><td class="c020">set the given <span class="c010">string</span> in verbatim style. </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c002"><span class="c003">{%</span> <span class="c010">string</span> <span class="c003">%}</span></span> </td><td class="c020">target-specific content
(L<sup>A</sup>T<sub>E</sub>X code by default, see details
in <a href="#sss%3Aocamldoc-target-specific-syntax">16.2.4.4</a>) </td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c002"><span class="c003">{!</span> <span class="c010">string</span> <span class="c003">}</span></span> </td><td class="c020">insert a cross-reference to an element
(see section <a href="#sss%3Aocamldoc-crossref">16.2.4.2</a> for the syntax of cross-references).</td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{!modules:</span> <span class="c010">string</span>  <span class="c010">string</span> ... <span class="c004">}</span> </td><td class="c020">insert an index table
for the given module names. Used in HTML only.</td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{!indexlist}</span> </td><td class="c020">insert a table of links to the various indexes
(types, values, modules, ...). Used in HTML only.</td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{^</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">set text in superscript.</td></tr>
<tr><td class="c024">∣ </td><td class="c023"> <span class="c004">{_</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> </td><td class="c020">set text in subscript.</td></tr>
<tr><td class="c024">∣ </td><td class="c023"><span class="c010">escaped-string</span></td><td class="c020">typeset the given string as is;
special characters (’<span class="c003">{</span>’, ’<span class="c003">}</span>’, ’<span class="c003">[</span>’, ’<span class="c003">]</span>’ and ’<span class="c003">@</span>’)
must be	escaped by a ’<span class="c003">\</span>’</td></tr>
<tr><td class="c024">∣ </td><td class="c023"><span class="c010">blank-line</span></td><td class="c020">force a new line.
</td></tr>
</table><p> <br>

</p>
<!--TOC subsubsection id="sss:ocamldoc-list" 16.2.4.1  List formatting-->
<h4 class="subsubsection" id="sss:ocamldoc-list"><a class="section-anchor" href="#sss:ocamldoc-list" aria-hidden="true"></a>16.2.4.1  List formatting</h4><!--SEC END --><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="list"><span class="c010">list</span></a></td><td class="c015">::=</td><td class="c017">
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> { <span class="c004">{-</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> }<sup>+</sup>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> { <span class="c004">{li</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> }<sup>+</sup>
</td></tr>
</table></td></tr>
</table></div><p>A shortcut syntax exists for lists and enumerated lists:
</p><pre>(** Here is a {b list}
- item 1
- item 2
- item 3

The list is ended by the blank line.*)
</pre><p>is equivalent to:
</p><pre>(** Here is a {b list}
{ul {- item 1}
{- item 2}
{- item 3}}
The list is ended by the blank line.*)
</pre><p>
The same shortcut is available for enumerated lists, using ’<span class="c003">+</span>’
instead of ’<span class="c003">-</span>’.
Note that only one list can be defined by this shortcut in nested lists.</p>
<!--TOC subsubsection id="sss:ocamldoc-crossref" 16.2.4.2  Cross-reference formatting-->
<h4 class="subsubsection" id="sss:ocamldoc-crossref"><a class="section-anchor" href="#sss:ocamldoc-crossref" aria-hidden="true"></a>16.2.4.2  Cross-reference formatting</h4><!--SEC END --><p>Cross-references are fully qualified element names, as in the example
<span class="c003">{!Foo.Bar.t}</span>. This is an ambiguous reference as it may designate
a type name, a value name, a class name, etc. It is possible to make
explicit the intended syntactic class, using <span class="c003">{!type:Foo.Bar.t}</span> to
designate a type, and <span class="c003">{!val:Foo.Bar.t}</span> a value of the same name.</p><p>The list of possible syntactic class is as follows:
</p><div class="center">
<table class="c001 cellpading0"><tr><td class="c015"><span class="c003">tag</span></td><td class="c015">syntactic class</td></tr>
<tr><td class="hbar" colspan=2></td></tr>
<tr><td class="c018"><span class="c003">module:</span></td><td class="c017">module </td></tr>
<tr><td class="c018"><span class="c003">modtype:</span></td><td class="c017">module type </td></tr>
<tr><td class="c018"><span class="c003">class:</span></td><td class="c017">class </td></tr>
<tr><td class="c018"><span class="c003">classtype:</span></td><td class="c017">class type </td></tr>
<tr><td class="c018"><span class="c003">val:</span></td><td class="c017">value </td></tr>
<tr><td class="c018"><span class="c003">type:</span></td><td class="c017">type </td></tr>
<tr><td class="c018"><span class="c003">exception:</span></td><td class="c017">exception </td></tr>
<tr><td class="c018"><span class="c003">attribute:</span></td><td class="c017">attribute </td></tr>
<tr><td class="c018"><span class="c003">method:</span></td><td class="c017">class method </td></tr>
<tr><td class="c018"><span class="c003">section:</span></td><td class="c017">ocamldoc section </td></tr>
<tr><td class="c018"><span class="c003">const:</span></td><td class="c017">variant constructor </td></tr>
<tr><td class="c018"><span class="c003">recfield:</span></td><td class="c017">record field
</td></tr>
</table>
</div><p>In the case of variant constructors or record field, the constructor
or field name should be preceded by the name of the correspond type –
to avoid the ambiguity of several types having the same constructor
names. For example, the constructor <span class="c003">Node</span> of the type <span class="c003">tree</span> will be
referenced as <span class="c003">{!tree.Node}</span> or <span class="c003">{!const:tree.Node}</span>, or possibly
<span class="c003">{!Mod1.Mod2.tree.Node}</span> from outside the module.</p>
<!--TOC subsubsection id="sss:ocamldoc-preamble" 16.2.4.3  First sentence-->
<h4 class="subsubsection" id="sss:ocamldoc-preamble"><a class="section-anchor" href="#sss:ocamldoc-preamble" aria-hidden="true"></a>16.2.4.3  First sentence</h4><!--SEC END --><p>In the description of a value, type, exception, module, module type, class
or class type, the <em>first sentence</em> is sometimes used in indexes, or
when just a part of the description is needed. The first sentence
is composed of the first characters of the description, until
</p><ul class="itemize"><li class="li-itemize">
the first dot followed by a blank, or
</li><li class="li-itemize">the first blank line
</li></ul><p>
outside of the following text formatting :
 <span class="c004">{ul</span> <a class="syntax" href="#list"><span class="c010">list</span></a> <span class="c004">}</span> ,
 <span class="c004">{ol</span> <a class="syntax" href="#list"><span class="c010">list</span></a> <span class="c004">}</span> ,
 <span class="c002"><span class="c003">[</span> <span class="c010">string</span> <span class="c003">]</span></span> ,
 <span class="c002"><span class="c003">{[</span> <span class="c010">string</span> <span class="c003">]}</span></span> ,
 <span class="c002"><span class="c003">{v</span> <span class="c010">string</span> <span class="c003">v}</span></span> ,
 <span class="c002"><span class="c003">{%</span> <span class="c010">string</span> <span class="c003">%}</span></span> ,
 <span class="c002"><span class="c003">{!</span> <span class="c010">string</span> <span class="c003">}</span></span> ,
 <span class="c004">{^</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> ,
 <span class="c004">{_</span> <a class="syntax" href="#text"><span class="c010">text</span></a> <span class="c004">}</span> .</p>
<!--TOC subsubsection id="sss:ocamldoc-target-specific-syntax" 16.2.4.4  Target-specific formatting-->
<h4 class="subsubsection" id="sss:ocamldoc-target-specific-syntax"><a class="section-anchor" href="#sss:ocamldoc-target-specific-syntax" aria-hidden="true"></a>16.2.4.4  Target-specific formatting</h4><!--SEC END --><p>The content inside <span class="c003">{%foo: ... %}</span> is target-specific and will only be
interpreted by the backend <span class="c003">foo</span>, and ignored by the others. The
backends of the distribution are <span class="c003">latex</span>, <span class="c003">html</span>, <span class="c003">texi</span> and <span class="c003">man</span>. If
no target is specified (syntax <span class="c003">{% ... %}</span>), <span class="c003">latex</span> is chosen by
default. Custom generators may support their own target prefix.</p>
<!--TOC subsubsection id="sss:ocamldoc-html-tags" 16.2.4.5  Recognized HTML tags-->
<h4 class="subsubsection" id="sss:ocamldoc-html-tags"><a class="section-anchor" href="#sss:ocamldoc-html-tags" aria-hidden="true"></a>16.2.4.5  Recognized HTML tags</h4><!--SEC END --><p>
The HTML tags <span class="c003">&lt;b&gt;..&lt;/b&gt;</span>,
<span class="c003">&lt;code&gt;..&lt;/code&gt;</span>,
<span class="c003">&lt;i&gt;..&lt;/i&gt;</span>,
<span class="c003">&lt;ul&gt;..&lt;/ul&gt;</span>,
<span class="c003">&lt;ol&gt;..&lt;/ol&gt;</span>,
<span class="c003">&lt;li&gt;..&lt;/li&gt;</span>,
<span class="c003">&lt;center&gt;..&lt;/center&gt;</span> and
<span class="c003">&lt;h[0-9]&gt;..&lt;/h[0-9]&gt;</span> can be used instead of, respectively,
 <span class="c004">{b ..}</span> ,
 <span class="c004">[..]</span> ,
 <span class="c004">{i ..}</span> ,
 <span class="c004">{ul ..}</span> ,
 <span class="c004">{ol ..}</span> ,
 <span class="c004">{li ..}</span> ,
 <span class="c004">{C ..}</span>  and
<span class="c003">{[0-9] ..}</span>.</p>
<!--TOC subsection id="ss:ocamldoc-tags" 16.2.5  Documentation tags (@-tags)-->
<h3 class="subsection" id="ss:ocamldoc-tags"><a class="section-anchor" href="#ss:ocamldoc-tags" aria-hidden="true"></a>16.2.5  Documentation tags (@-tags)</h3><!--SEC END -->
<!--TOC subsubsection id="sss:ocamldoc-builtin-tags" Predefined tags-->
<h4 class="subsubsection" id="sss:ocamldoc-builtin-tags"><a class="section-anchor" href="#sss:ocamldoc-builtin-tags" aria-hidden="true"></a>Predefined tags</h4><!--SEC END --><p>
The following table gives the list of predefined @-tags, with their
syntax and meaning.<br>

</p><table class="cellpadding1" border=1 style="border-spacing:0;"><tr><td class="c021"> <span class="c004">@author</span> <span class="c010">string</span> </td><td class="c021">The author of the element. One author per
<span class="c003">@author</span> tag.
There may be several <span class="c003">@author</span> tags for the same element. </td></tr>
<tr><td class="c021">
 <span class="c004">@deprecated</span> <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">The <a class="syntax" href="#text"><span class="c010">text</span></a> should describe when the element was
deprecated, what to use as a replacement, and possibly the reason
for deprecation. </td></tr>
<tr><td class="c021">
 <span class="c004">@param</span> <span class="c010">id</span>  <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Associate the given description (<a class="syntax" href="#text"><span class="c010">text</span></a>) to the
given parameter name <span class="c010">id</span>. This tag is used for functions,
methods, classes and functors. </td></tr>
<tr><td class="c021">
 <span class="c004">@raise</span> <span class="c010">Exc</span>  <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Explain that the element may raise
the exception <span class="c010">Exc</span>. </td></tr>
<tr><td class="c021">
 <span class="c004">@return</span> <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Describe the return value and
its possible values. This tag is used for functions
and methods. </td></tr>
<tr><td class="c021">
 <span class="c002"><span class="c003">@see</span> <span class="c003">&lt;</span> <span class="c010">URL</span> <span class="c003">&gt;</span></span>  <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Add a reference to the <span class="c010">URL</span>
with the given <a class="syntax" href="#text"><span class="c010">text</span></a> as comment. </td></tr>
<tr><td class="c021">
 <span class="c002"><span class="c003">@see</span> <span class="c003">'</span><span class="c010">filename</span><span class="c003">'</span></span> <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Add a reference to the given file name
(written between single quotes), with the given <a class="syntax" href="#text"><span class="c010">text</span></a> as comment. </td></tr>
<tr><td class="c021">
 <span class="c002"><span class="c003">@see</span> <span class="c003">"</span><span class="c010">document-name</span><span class="c003">"</span></span> <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Add a reference to the given
document name (written between double quotes), with the given <a class="syntax" href="#text"><span class="c010">text</span></a>
as comment. </td></tr>
<tr><td class="c021">
 <span class="c004">@since</span> <span class="c010">string</span> </td><td class="c021">Indicate when the element was introduced. </td></tr>
<tr><td class="c021">
 <span class="c004">@before</span>  <span class="c010">version</span>  <a class="syntax" href="#text"><span class="c010">text</span></a> </td><td class="c021">Associate the given description (<a class="syntax" href="#text"><span class="c010">text</span></a>)
to the given <span class="c010">version</span> in order to document compatibility issues. </td></tr>
<tr><td class="c021">
 <span class="c004">@version</span> <span class="c010">string</span> </td><td class="c021">The version number for the element. </td></tr>
</table>
<!--TOC subsubsection id="sss:ocamldoc-custom-tags" Custom tags-->
<h4 class="subsubsection" id="sss:ocamldoc-custom-tags"><a class="section-anchor" href="#sss:ocamldoc-custom-tags" aria-hidden="true"></a>Custom tags</h4><!--SEC END --><p>
You can use custom tags in the documentation comments, but they will
have no effect if the generator used does not handle them. To use a
custom tag, for example <span class="c003">foo</span>, just put <span class="c003">@foo</span> with some text in your
comment, as in:
</p><pre>(** My comment to show you a custom tag.
@foo this is the text argument to the [foo] custom tag.
*)
</pre><p>
To handle custom tags, you need to define a custom generator,
as explained in section <a href="#ss%3Aocamldoc-handling-custom-tags">16.3.2</a>.</p>
<!--TOC section id="s:ocamldoc-custom-generators" 16.3  Custom generators-->
<h2 class="section" id="s:ocamldoc-custom-generators"><a class="section-anchor" href="#s:ocamldoc-custom-generators" aria-hidden="true"></a>16.3  Custom generators</h2><!--SEC END --><p>OCamldoc operates in two steps:
</p><ol class="enumerate" type=1><li class="li-enumerate">
analysis of the source files;
</li><li class="li-enumerate">generation of documentation, through a documentation generator,
	which is an object of class <span class="c003">Odoc_args.class_generator</span>.
</li></ol><p>
Users can provide their own documentation generator to be used during
step 2 instead of the default generators.
All the information retrieved during the analysis step is available through
the <span class="c003">Odoc_info</span> module, which gives access to all the types and functions
representing the elements found in the given modules, with their associated
description.</p><p>The files you can use to define custom generators are installed in the
<span class="c003">ocamldoc</span> sub-directory of the OCaml standard library.</p>
<!--TOC subsection id="ss:ocamldoc-generators" 16.3.1  The generator modules-->
<h3 class="subsection" id="ss:ocamldoc-generators"><a class="section-anchor" href="#ss:ocamldoc-generators" aria-hidden="true"></a>16.3.1  The generator modules</h3><!--SEC END --><p>
The type of a generator module depends on the kind of generated documentation.
Here is the list of generator module types, with the name of the generator
class in the module :
</p><ul class="itemize"><li class="li-itemize">
for HTML : <span class="c003">Odoc_html.Html_generator</span> (class <span class="c003">html</span>),
</li><li class="li-itemize">for L<sup>A</sup>T<sub>E</sub>X : <span class="c003">Odoc_latex.Latex_generator</span> (class <span class="c003">latex</span>),
</li><li class="li-itemize">for TeXinfo : <span class="c003">Odoc_texi.Texi_generator</span> (class <span class="c003">texi</span>),
</li><li class="li-itemize">for man pages : <span class="c003">Odoc_man.Man_generator</span> (class <span class="c003">man</span>),
</li><li class="li-itemize">for graphviz (dot) : <span class="c003">Odoc_dot.Dot_generator</span> (class <span class="c003">dot</span>),
</li><li class="li-itemize">for other kinds : <span class="c003">Odoc_gen.Base</span> (class <span class="c003">generator</span>).
</li></ul><p>
That is, to define a new generator, one must implement a module with
the expected signature, and with the given generator class, providing
the <span class="c003">generate</span> method as entry point to make the generator generates
documentation for a given list of modules :</p><pre>        method generate : Odoc_info.Module.t_module list -&gt; unit
</pre><p>
This method will be called with the list of analysed and possibly
merged <span class="c003">Odoc_info.t_module</span> structures.</p><p>It is recommended to inherit from the current generator of the same
kind as the one you want to define. Doing so, it is possible to
load various custom generators to combine improvements brought by each one.</p><p>This is done using first class modules (see chapter <a href="#s%3Afirst-class-modules">8.5</a>).</p><p>The easiest way to define a custom generator is the following this example,
here extending the current HTML generator. We don’t have to know if this is
the original HTML generator defined in ocamldoc or if it has been extended
already by a previously loaded custom generator :</p><pre>module Generator (G : Odoc_html.Html_generator) =
struct
  class html =
    object(self)
      inherit G.html as html
      (* ... *)

      method generate module_list =
        (* ... *)
        ()

      (* ... *)
  end
end;;

let _ = Odoc_args.extend_html_generator (module Generator : Odoc_gen.Html_functor);;
</pre><p>
To know which methods to override and/or which methods are available,
have a look at the different base implementations, depending on the
kind of generator you are extending :

</p><ul class="itemize"><li class="li-itemize">
for HTML : <a href="https://github.com/ocaml/ocaml/blob/4.11/ocamldoc/odoc_html.ml"><span class="c003">odoc_html.ml</span></a>,
</li><li class="li-itemize">for L<sup>A</sup>T<sub>E</sub>X : <a href="https://github.com/ocaml/ocaml/blob/4.11/ocamldoc/odoc_latex.ml"><span class="c003">odoc_latex.ml</span></a>,
</li><li class="li-itemize">for TeXinfo : <a href="https://github.com/ocaml/ocaml/blob/4.11/ocamldoc/odoc_texi.ml"><span class="c003">odoc_texi.ml</span></a>,
</li><li class="li-itemize">for man pages : <a href="https://github.com/ocaml/ocaml/blob/4.11/ocamldoc/odoc_man.ml"><span class="c003">odoc_man.ml</span></a>,
</li><li class="li-itemize">for graphviz (dot) : <a href="https://github.com/ocaml/ocaml/blob/4.11/ocamldoc/odoc_dot.ml"><span class="c003">odoc_dot.ml</span></a>.
</li></ul>
<!--TOC subsection id="ss:ocamldoc-handling-custom-tags" 16.3.2  Handling custom tags-->
<h3 class="subsection" id="ss:ocamldoc-handling-custom-tags"><a class="section-anchor" href="#ss:ocamldoc-handling-custom-tags" aria-hidden="true"></a>16.3.2  Handling custom tags</h3><!--SEC END --><p>Making a custom generator handle custom tags (see
<a href="#sss%3Aocamldoc-custom-tags">16.2.5</a>) is very simple.</p><!--TOC subsubsection id="sss:ocamldoc-html-generator" For HTML-->
<h4 class="subsubsection" id="sss:ocamldoc-html-generator"><a class="section-anchor" href="#sss:ocamldoc-html-generator" aria-hidden="true"></a>For HTML</h4><!--SEC END --><p>
Here is how to develop a HTML generator handling your custom tags.</p><p>The class <span class="c003">Odoc_html.Generator.html</span> inherits
from the class <span class="c003">Odoc_html.info</span>, containing a field <span class="c003">tag_functions</span> which is a
list pairs composed of a custom tag (e.g. <span class="c003">"foo"</span>) and a function taking
a <span class="c003">text</span> and returning HTML code (of type <span class="c003">string</span>).
To handle a new tag <span class="c003">bar</span>, extend the current HTML generator
and complete the <span class="c003">tag_functions</span> field:
</p><pre>module Generator (G : Odoc_html.Html_generator) =
struct
  class html =
    object(self)
      inherit G.html

      (** Return HTML code for the given text of a bar tag. *)
      method html_of_bar t = (* your code here *)

      initializer
        tag_functions &lt;- ("bar", self#html_of_bar) :: tag_functions
  end
end
let _ = Odoc_args.extend_html_generator (module Generator : Odoc_gen.Html_functor);;
</pre><p>
Another method of the class <span class="c003">Odoc_html.info</span> will look for the
function associated to a custom tag and apply it to the text given to
the tag. If no function is associated to a custom tag, then the method
prints a warning message on <span class="c003">stderr</span>.</p>
<!--TOC subsubsection id="sss:ocamldoc-other-generators" For other generators-->
<h4 class="subsubsection" id="sss:ocamldoc-other-generators"><a class="section-anchor" href="#sss:ocamldoc-other-generators" aria-hidden="true"></a>For other generators</h4><!--SEC END --><p>
You can act the same way for other kinds of generators.</p>
<!--TOC section id="s:ocamldoc-adding-flags" 16.4  Adding command line options-->
<h2 class="section" id="s:ocamldoc-adding-flags"><a class="section-anchor" href="#s:ocamldoc-adding-flags" aria-hidden="true"></a>16.4  Adding command line options</h2><!--SEC END --><p>
The command line analysis is performed after loading the module containing the
documentation generator, thus allowing command line options to be added to the
list of existing ones. Adding an option can be done with the function
</p><pre>        Odoc_args.add_option : string * Arg.spec * string -&gt; unit
</pre><p>Note: Existing command line options can be redefined using
this function.</p>
<!--TOC subsection id="ss:ocamldoc-compilation-and-usage" 16.4.1  Compilation and usage-->
<h3 class="subsection" id="ss:ocamldoc-compilation-and-usage"><a class="section-anchor" href="#ss:ocamldoc-compilation-and-usage" aria-hidden="true"></a>16.4.1  Compilation and usage</h3><!--SEC END -->
<!--TOC subsubsection id="sss:ocamldoc-generator-class" Defining a custom generator class in one file-->
<h4 class="subsubsection" id="sss:ocamldoc-generator-class"><a class="section-anchor" href="#sss:ocamldoc-generator-class" aria-hidden="true"></a>Defining a custom generator class in one file</h4><!--SEC END --><p>
Let <span class="c003">custom.ml</span> be the file defining a new generator class.
Compilation of <span class="c003">custom.ml</span> can be performed by the following command :
</p><pre>
        ocamlc -I +ocamldoc -c custom.ml
</pre><p>
The file <span class="c003">custom.cmo</span> is created and can be used this way :
</p><pre>
        ocamldoc -g custom.cmo <span class="c009">other-options source-files</span>
</pre><p>
Options selecting a built-in generator to <span class="c003">ocamldoc</span>, such as
<span class="c003">-html</span>, have no effect if a custom generator of the same kind is provided using
<span class="c003">-g</span>. If the kinds do not match, the selected built-in generator is used and the
custom one is ignored.</p>
<!--TOC subsubsection id="sss:ocamldoc-modular-generator" Defining a custom generator class in several files-->
<h4 class="subsubsection" id="sss:ocamldoc-modular-generator"><a class="section-anchor" href="#sss:ocamldoc-modular-generator" aria-hidden="true"></a>Defining a custom generator class in several files</h4><!--SEC END --><p>
It is possible to define a generator class in several modules, which
are defined in several files <span class="c009">file</span><sub>1</sub><span class="c003">.ml</span>[<span class="c003">i</span>],
<span class="c009">file</span><sub>2</sub><span class="c003">.ml</span>[<span class="c003">i</span>], ..., <span class="c009">file</span><sub><span class="c009">n</span></sub><span class="c003">.ml</span>[<span class="c003">i</span>]. A <span class="c003">.cma</span>
library file must be created, including all these files.</p><p>The following commands create the <span class="c003">custom.cma</span> file from files
<span class="c009">file</span><sub>1</sub><span class="c003">.ml</span>[<span class="c003">i</span>], ..., <span class="c009">file</span><sub><span class="c009">n</span></sub><span class="c003">.ml</span>[<span class="c003">i</span>] :
</p><pre>
ocamlc -I +ocamldoc -c <span class="c009">file</span><sub>1</sub>.ml[i]
ocamlc -I +ocamldoc -c <span class="c009">file</span><sub>2</sub>.ml[i]
...
ocamlc -I +ocamldoc -c <span class="c009">file</span><sub><span class="c009">n</span></sub>.ml[i]
ocamlc -o custom.cma -a <span class="c009">file</span><sub>1</sub>.cmo <span class="c009">file</span><sub>2</sub>.cmo ... <span class="c009">file</span><sub><span class="c009">n</span></sub>.cmo
</pre><p>
Then, the following command uses <span class="c003">custom.cma</span> as custom generator:
</p><pre>
        ocamldoc -g custom.cma <span class="c009">other-options source-files</span>
</pre>
<!--TOC chapter id="sec382" Chapter 17  The debugger (ocamldebug)-->
<h1 class="chapter" id="sec382">Chapter 17  The debugger (ocamldebug)</h1><!--SEC END --><p> <a id="c:debugger"></a>
</p><!--NAME debugger.html-->
<p>This chapter describes the OCaml source-level replay debugger
<span class="c003">ocamldebug</span>.</p><blockquote class="quote"><span class="c007">Unix:</span>   The debugger is available on Unix systems that provide
BSD sockets.
</blockquote><blockquote class="quote"><span class="c007">Windows:</span>   The debugger is available under the Cygwin port of
OCaml, but not under the native Win32 ports.
</blockquote>
<!--TOC section id="s:debugger-compilation" 17.1  Compiling for debugging-->
<h2 class="section" id="s:debugger-compilation"><a class="section-anchor" href="#s:debugger-compilation" aria-hidden="true"></a>17.1  Compiling for debugging</h2><!--SEC END --><p>Before the debugger can be used, the program must be compiled and
linked with the <span class="c003">-g</span> option: all <span class="c003">.cmo</span> and <span class="c003">.cma</span> files that are part
of the program should have been created with <span class="c003">ocamlc -g</span>, and they
must be linked together with <span class="c003">ocamlc -g</span>.</p><p>Compiling with <span class="c003">-g</span> entails no penalty on the running time of
programs: object files and bytecode executable files are bigger and
take longer to produce, but the executable files run at
exactly the same speed as if they had been compiled without <span class="c003">-g</span>.</p>
<!--TOC section id="s:debugger-invocation" 17.2  Invocation-->
<h2 class="section" id="s:debugger-invocation"><a class="section-anchor" href="#s:debugger-invocation" aria-hidden="true"></a>17.2  Invocation</h2><!--SEC END -->
<!--TOC subsection id="ss:debugger-start" 17.2.1  Starting the debugger-->
<h3 class="subsection" id="ss:debugger-start"><a class="section-anchor" href="#ss:debugger-start" aria-hidden="true"></a>17.2.1  Starting the debugger</h3><!--SEC END --><p>The OCaml debugger is invoked by running the program
<span class="c003">ocamldebug</span> with the name of the bytecode executable file as first
argument:
</p><pre>
        ocamldebug [<span class="c009">options</span>] <span class="c009">program</span> [<span class="c009">arguments</span>]
</pre><p>
The arguments following <span class="c009">program</span> are optional, and are passed as
command-line arguments to the program being debugged. (See also the
<span class="c003">set arguments</span> command.)</p><p>The following command-line options are recognized:
</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">-c </span> <span class="c009">count</span></span></dt><dd class="dd-description">
Set the maximum number of simultaneously live checkpoints to <span class="c009">count</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-cd </span> <span class="c009">dir</span></span></dt><dd class="dd-description">
Run the debugger program from the working directory <span class="c009">dir</span>,
instead of the current directory. (See also the <span class="c003">cd</span> command.)</dd><dt class="dt-description"><span class="c006">-emacs</span></dt><dd class="dd-description">
Tell the debugger it is executed under Emacs. (See
section <a href="#s%3Ainf-debugger">17.10</a> for information on how to run the
debugger under Emacs.)</dd><dt class="dt-description"><span class="c013"><span class="c003">-I </span><span class="c009">directory</span></span></dt><dd class="dd-description">
Add <span class="c009">directory</span> to the list of directories searched for source
files and compiled files. (See also the <span class="c003">directory</span> command.)</dd><dt class="dt-description"><span class="c013"><span class="c003">-s </span><span class="c009">socket</span></span></dt><dd class="dd-description">
Use <span class="c009">socket</span> for communicating with the debugged program. See the
description of the command <span class="c003">set socket</span> (section <a href="#ss%3Adebugger-communication">17.8.8</a>)
for the format of <span class="c009">socket</span>.</dd><dt class="dt-description"><span class="c006">-version</span></dt><dd class="dd-description">
Print version string and exit.</dd><dt class="dt-description"><span class="c006">-vnum</span></dt><dd class="dd-description">
Print short version number and exit.</dd><dt class="dt-description"><span class="c013"><span class="c003">-help</span> or <span class="c003">--help</span></span></dt><dd class="dd-description">
Display a short usage summary and exit.
</dd></dl>
<!--TOC subsection id="ss:debugger-init-file" 17.2.2  Initialization file-->
<h3 class="subsection" id="ss:debugger-init-file"><a class="section-anchor" href="#ss:debugger-init-file" aria-hidden="true"></a>17.2.2  Initialization file</h3><!--SEC END --><p>On start-up, the debugger will read commands from an initialization
file before giving control to the user. The default file is
<span class="c003">.ocamldebug</span> in the current directory if it exists, otherwise
<span class="c003">.ocamldebug</span> in the user’s home directory.</p>
<!--TOC subsection id="ss:debugger-exut" 17.2.3  Exiting the debugger-->
<h3 class="subsection" id="ss:debugger-exut"><a class="section-anchor" href="#ss:debugger-exut" aria-hidden="true"></a>17.2.3  Exiting the debugger</h3><!--SEC END --><p>The command <span class="c003">quit</span> exits the debugger. You can also exit the debugger
by typing an end-of-file character (usually <span class="c003">ctrl-D</span>).</p><p>Typing an interrupt character (usually <span class="c003">ctrl-C</span>) will not exit the
debugger, but will terminate the action of any debugger command that is in
progress and return to the debugger command level.</p>
<!--TOC section id="s:debugger-commands" 17.3  Commands-->
<h2 class="section" id="s:debugger-commands"><a class="section-anchor" href="#s:debugger-commands" aria-hidden="true"></a>17.3  Commands</h2><!--SEC END --><p>A debugger command is a single line of input. It starts with a command
name, which is followed by arguments depending on this name. Examples:
</p><pre>        run
        goto 1000
        set arguments arg1 arg2
</pre><p>
A command name can be truncated as long as there is no ambiguity. For
instance, <span class="c003">go 1000</span> is understood as <span class="c003">goto 1000</span>, since there are no
other commands whose name starts with <span class="c003">go</span>. For the most frequently
used commands, ambiguous abbreviations are allowed. For instance, <span class="c003">r</span>
stands for <span class="c003">run</span> even though there are others commands starting with
<span class="c003">r</span>. You can test the validity of an abbreviation using the <span class="c003">help</span> command.</p><p>If the previous command has been successful, a blank line (typing just
<span class="c003">RET</span>) will repeat it.</p>
<!--TOC subsection id="ss:debugger-help" 17.3.1  Getting help-->
<h3 class="subsection" id="ss:debugger-help"><a class="section-anchor" href="#ss:debugger-help" aria-hidden="true"></a>17.3.1  Getting help</h3><!--SEC END --><p>The OCaml debugger has a simple on-line help system, which gives
a brief description of each command and variable.</p><dl class="description"><dt class="dt-description">
<span class="c006">help</span></dt><dd class="dd-description">
Print the list of commands.</dd><dt class="dt-description"><span class="c013"><span class="c003">help </span><span class="c009">command</span></span></dt><dd class="dd-description">
Give help about the command <span class="c009">command</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">help set </span><span class="c009">variable</span>, <span class="c003">help show </span><span class="c009">variable</span></span></dt><dd class="dd-description">
Give help about the variable <span class="c009">variable</span>. The list of all debugger
variables can be obtained with <span class="c003">help set</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">help info </span><span class="c009">topic</span></span></dt><dd class="dd-description">
Give help about <span class="c009">topic</span>. Use <span class="c003">help info</span> to get a list of known topics.
</dd></dl>
<!--TOC subsection id="ss:debugger-state" 17.3.2  Accessing the debugger state-->
<h3 class="subsection" id="ss:debugger-state"><a class="section-anchor" href="#ss:debugger-state" aria-hidden="true"></a>17.3.2  Accessing the debugger state</h3><!--SEC END --><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">set </span><span class="c009">variable value</span></span></dt><dd class="dd-description">
Set the debugger variable <span class="c009">variable</span> to the value <span class="c009">value</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">show </span><span class="c009">variable</span></span></dt><dd class="dd-description">
Print the value of the debugger variable <span class="c009">variable</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">info </span><span class="c009">subject</span></span></dt><dd class="dd-description">
Give information about the given subject.
For instance, <span class="c003">info breakpoints</span> will print the list of all breakpoints.
</dd></dl>
<!--TOC section id="s:debugger-execution" 17.4  Executing a program-->
<h2 class="section" id="s:debugger-execution"><a class="section-anchor" href="#s:debugger-execution" aria-hidden="true"></a>17.4  Executing a program</h2><!--SEC END -->
<!--TOC subsection id="ss:debugger-events" 17.4.1  Events-->
<h3 class="subsection" id="ss:debugger-events"><a class="section-anchor" href="#ss:debugger-events" aria-hidden="true"></a>17.4.1  Events</h3><!--SEC END --><p>Events are “interesting” locations in the source code, corresponding
to the beginning or end of evaluation of “interesting”
sub-expressions. Events are the unit of single-stepping (stepping goes
to the next or previous event encountered in the program execution).
Also, breakpoints can only be set at events. Thus, events play the
role of line numbers in debuggers for conventional languages.</p><p>During program execution, a counter is incremented at each event
encountered. The value of this counter is referred as the <em>current
time</em>. Thanks to reverse execution, it is possible to jump back and
forth to any time of the execution.</p><p>Here is where the debugger events (written ǧ) are located in
the source code:
</p><ul class="itemize"><li class="li-itemize">
Following a function application:
<pre>
(f arg)ǧ
</pre>
</li><li class="li-itemize">On entrance to a function:
<pre>
fun x y z -&gt; ǧ ...
</pre>
</li><li class="li-itemize">On each case of a pattern-matching definition (function,
<span class="c003">match</span>…<span class="c003">with</span> construct, <span class="c003">try</span>…<span class="c003">with</span> construct):
<pre>
function pat1 -&gt; ǧ expr1
       | ...
       | patN -&gt; ǧ exprN
</pre>
</li><li class="li-itemize">Between subexpressions of a sequence:
<pre>
expr1; ǧ expr2; ǧ ...; ǧ exprN
</pre>
</li><li class="li-itemize">In the two branches of a conditional expression:
<pre>
if cond then ǧ expr1 else ǧ expr2
</pre>
</li><li class="li-itemize">At the beginning of each iteration of a loop:
<pre>
while cond do ǧ body done
for i = a to b do ǧ body done
</pre>
</li></ul><p>
Exceptions: A function application followed by a function return is replaced
by the compiler by a jump (tail-call optimization). In this case, no
event is put after the function application.
</p>
<!--TOC subsection id="ss:debugger-starting-program" 17.4.2  Starting the debugged program-->
<h3 class="subsection" id="ss:debugger-starting-program"><a class="section-anchor" href="#ss:debugger-starting-program" aria-hidden="true"></a>17.4.2  Starting the debugged program</h3><!--SEC END --><p>The debugger starts executing the debugged program only when needed.
This allows setting breakpoints or assigning debugger variables before
execution starts. There are several ways to start execution:
</p><dl class="description"><dt class="dt-description">
<span class="c006">run</span></dt><dd class="dd-description"> Run the program until a breakpoint is hit, or the program
terminates.
</dd><dt class="dt-description"><span class="c006">goto 0</span></dt><dd class="dd-description"> Load the program and stop on the first event.
</dd><dt class="dt-description"><span class="c013"><span class="c003">goto </span><span class="c009">time</span></span></dt><dd class="dd-description"> Load the program and execute it until the
given time. Useful when you already know approximately at what time
the problem appears. Also useful to set breakpoints on function values
that have not been computed at time 0 (see section <a href="#s%3Abreakpoints">17.5</a>).
</dd></dl><p>The execution of a program is affected by certain information it
receives when the debugger starts it, such as the command-line
arguments to the program and its working directory. The debugger
provides commands to specify this information (<span class="c003">set arguments</span> and <span class="c003">cd</span>).
These commands must be used before program execution starts. If you try
to change the arguments or the working directory after starting your
program, the debugger will kill the program (after asking for confirmation).</p>
<!--TOC subsection id="ss:debugger-running" 17.4.3  Running the program-->
<h3 class="subsection" id="ss:debugger-running"><a class="section-anchor" href="#ss:debugger-running" aria-hidden="true"></a>17.4.3  Running the program</h3><!--SEC END --><p>The following commands execute the program forward or backward,
starting at the current time. The execution will stop either when
specified by the command or when a breakpoint is encountered.</p><dl class="description"><dt class="dt-description">
<span class="c006">run</span></dt><dd class="dd-description"> Execute the program forward from current time. Stops at
next breakpoint or when the program terminates.
</dd><dt class="dt-description"><span class="c006">reverse</span></dt><dd class="dd-description"> Execute the program backward from current time.
Mostly useful to go to the last breakpoint encountered before the
current time.
</dd><dt class="dt-description"><span class="c013"><span class="c003">step </span>[<span class="c009">count</span>]</span></dt><dd class="dd-description"> Run the program and stop at the next
event. With an argument, do it <span class="c009">count</span> times. If <span class="c009">count</span> is 0,
run until the program terminates or a breakpoint is hit.
</dd><dt class="dt-description"><span class="c013"><span class="c003">backstep </span>[<span class="c009">count</span>]</span></dt><dd class="dd-description"> Run the program backward and stop at
the previous event. With an argument, do it <span class="c009">count</span> times.
</dd><dt class="dt-description"><span class="c013"><span class="c003">next </span>[<span class="c009">count</span>]</span></dt><dd class="dd-description"> Run the program and stop at the next
event, skipping over function calls. With an argument, do it
<span class="c009">count</span> times.
</dd><dt class="dt-description"><span class="c013"><span class="c003">previous </span>[<span class="c009">count</span>]</span></dt><dd class="dd-description"> Run the program backward and stop at
the previous event, skipping over function calls. With an argument, do
it <span class="c009">count</span> times.
</dd><dt class="dt-description"><span class="c006">finish</span></dt><dd class="dd-description"> Run the program until the current function returns.
</dd><dt class="dt-description"><span class="c006">start</span></dt><dd class="dd-description"> Run the program backward and stop at the first event
before the current function invocation.
</dd></dl>
<!--TOC subsection id="ss:debugger-time-travel" 17.4.4  Time travel-->
<h3 class="subsection" id="ss:debugger-time-travel"><a class="section-anchor" href="#ss:debugger-time-travel" aria-hidden="true"></a>17.4.4  Time travel</h3><!--SEC END --><p>You can jump directly to a given time, without stopping on
breakpoints, using the <span class="c003">goto</span> command.</p><p>As you move through the program, the debugger maintains an history of
the successive times you stop at. The <span class="c003">last</span> command can be used to
revisit these times: each <span class="c003">last</span> command moves one step back through
the history. That is useful mainly to undo commands such as <span class="c003">step</span>
and <span class="c003">next</span>.</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">goto </span><span class="c009">time</span></span></dt><dd class="dd-description">
Jump to the given time.
</dd><dt class="dt-description"><span class="c013"><span class="c003">last </span>[<span class="c009">count</span>]</span></dt><dd class="dd-description">
Go back to the latest time recorded in the execution history. With an
argument, do it <span class="c009">count</span> times.
</dd><dt class="dt-description"><span class="c013"><span class="c003">set history </span><span class="c009">size</span></span></dt><dd class="dd-description">
Set the size of the execution history.
</dd></dl>
<!--TOC subsection id="ss:debugger-kill" 17.4.5  Killing the program-->
<h3 class="subsection" id="ss:debugger-kill"><a class="section-anchor" href="#ss:debugger-kill" aria-hidden="true"></a>17.4.5  Killing the program</h3><!--SEC END --><dl class="description"><dt class="dt-description">
<span class="c006">kill</span></dt><dd class="dd-description"> Kill the program being executed. This command is mainly
useful if you wish to recompile the program without leaving the debugger.
</dd></dl>
<!--TOC section id="s:breakpoints" 17.5  Breakpoints-->
<h2 class="section" id="s:breakpoints"><a class="section-anchor" href="#s:breakpoints" aria-hidden="true"></a>17.5  Breakpoints</h2><!--SEC END --><p>A breakpoint causes the program to stop whenever a certain point in
the program is reached. It can be set in several ways using the
<span class="c003">break</span> command. Breakpoints are assigned numbers when set, for
further reference. The most comfortable way to set breakpoints is
through the Emacs interface (see section <a href="#s%3Ainf-debugger">17.10</a>).</p><dl class="description"><dt class="dt-description">
<span class="c006">break</span></dt><dd class="dd-description">
Set a breakpoint at the current position in the program execution. The
current position must be on an event (i.e., neither at the beginning,
nor at the end of the program).</dd><dt class="dt-description"><span class="c013"><span class="c003">break </span><span class="c009">function</span></span></dt><dd class="dd-description">
Set a breakpoint at the beginning of <span class="c009">function</span>. This works only
when the functional value of the identifier <span class="c009">function</span> has been
computed and assigned to the identifier. Hence this command cannot be
used at the very beginning of the program execution, when all
identifiers are still undefined; use <span class="c003">goto</span> <span class="c009">time</span> to advance
execution until the functional value is available.</dd><dt class="dt-description"><span class="c013"><span class="c003">break @</span> [<span class="c009">module</span>] <span class="c009">line</span></span></dt><dd class="dd-description">
Set a breakpoint in module <span class="c009">module</span> (or in the current module if
<span class="c009">module</span> is not given), at the first event of line <span class="c009">line</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">break @</span> [<span class="c009">module</span>] <span class="c009">line column</span></span></dt><dd class="dd-description">
Set a breakpoint in module <span class="c009">module</span> (or in the current module if
<span class="c009">module</span> is not given), at the event closest to line <span class="c009">line</span>,
column <span class="c009">column</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">break @</span> [<span class="c009">module</span>] <span class="c003">#</span> <span class="c009">character</span></span></dt><dd class="dd-description">
Set a breakpoint in module <span class="c009">module</span> at the event closest to
character number <span class="c009">character</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">break </span> <span class="c009">frag</span><span class="c003">:</span><span class="c009">pc</span>, <span class="c003">break </span> <span class="c009">pc</span></span></dt><dd class="dd-description">
Set a breakpoint at code address <span class="c009">frag</span><span class="c003">:</span><span class="c009">pc</span>. The integer
<span class="c009">frag</span> is the identifier of a code fragment, a set of modules that
have been loaded at once, either initially or with the <span class="c003">Dynlink</span>
module. The integer <span class="c009">pc</span> is the instruction counter within this
code fragment. If <span class="c009">frag</span> is omitted, it defaults to 0, which is
the code fragment of the program loaded initially.</dd><dt class="dt-description"><span class="c013"><span class="c003">delete </span>[<span class="c009">breakpoint-numbers</span>]</span></dt><dd class="dd-description">
Delete the specified breakpoints. Without argument, all breakpoints
are deleted (after asking for confirmation).</dd><dt class="dt-description"><span class="c006">info breakpoints</span></dt><dd class="dd-description"> Print the list of all breakpoints.
</dd></dl>
<!--TOC section id="s:debugger-callstack" 17.6  The call stack-->
<h2 class="section" id="s:debugger-callstack"><a class="section-anchor" href="#s:debugger-callstack" aria-hidden="true"></a>17.6  The call stack</h2><!--SEC END --><p>Each time the program performs a function application, it saves the
location of the application (the return address) in a block of data
called a stack frame. The frame also contains the local variables of
the caller function. All the frames are allocated in a region of
memory called the call stack. The command <span class="c003">backtrace</span> (or <span class="c003">bt</span>)
displays parts of the call stack.</p><p>At any time, one of the stack frames is “selected” by the debugger; several
debugger commands refer implicitly to the selected frame. In particular,
whenever you ask the debugger for the value of a local variable, the
value is found in the selected frame. The commands <span class="c003">frame</span>, <span class="c003">up</span> and <span class="c003">down</span>
select whichever frame you are interested in.</p><p>When the program stops, the debugger automatically selects the
currently executing frame and describes it briefly as the <span class="c003">frame</span>
command does.</p><dl class="description"><dt class="dt-description">
<span class="c006">frame</span></dt><dd class="dd-description">
Describe the currently selected stack frame.</dd><dt class="dt-description"><span class="c013"><span class="c003">frame</span> <span class="c009">frame-number</span></span></dt><dd class="dd-description">
Select a stack frame by number and describe it. The frame currently
executing when the program stopped has number 0; its caller has number
1; and so on up the call stack.</dd><dt class="dt-description"><span class="c013"><span class="c003">backtrace </span>[<span class="c009">count</span>], <span class="c003">bt </span>[<span class="c009">count</span>]</span></dt><dd class="dd-description">
Print the call stack. This is useful to see which sequence of function
calls led to the currently executing frame. With a positive argument,
print only the innermost <span class="c009">count</span> frames.
With a negative argument, print only the outermost -<span class="c009">count</span> frames.</dd><dt class="dt-description"><span class="c013"><span class="c003">up</span> [<span class="c009">count</span>]</span></dt><dd class="dd-description">
Select and display the stack frame just “above” the selected frame,
that is, the frame that called the selected frame. An argument says how
many frames to go up.</dd><dt class="dt-description"><span class="c013"><span class="c003">down </span>[<span class="c009">count</span>]</span></dt><dd class="dd-description">
Select and display the stack frame just “below” the selected frame,
that is, the frame that was called by the selected frame. An argument
says how many frames to go down.
</dd></dl>
<!--TOC section id="s:debugger-examining-values" 17.7  Examining variable values-->
<h2 class="section" id="s:debugger-examining-values"><a class="section-anchor" href="#s:debugger-examining-values" aria-hidden="true"></a>17.7  Examining variable values</h2><!--SEC END --><p>The debugger can print the current value of simple expressions. The
expressions can involve program variables: all the identifiers that
are in scope at the selected program point can be accessed.</p><p>Expressions that can be printed are a subset of OCaml
expressions, as described by the following grammar:
</p><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" id="simple-expr"><span class="c010">simple-expr</span></a></td><td class="c015">::=</td><td class="c017">
<a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> { <a class="syntax" href="#capitalized-ident"><span class="c010">capitalized-ident</span></a> <span class="c004">.</span> }  <a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">*</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">$</span> <span class="c010">integer</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#simple-expr"><span class="c010">simple-expr</span></a> <span class="c004">.</span>  <a class="syntax" href="#lowercase-ident"><span class="c010">lowercase-ident</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#simple-expr"><span class="c010">simple-expr</span></a> <span class="c004">.(</span>  <span class="c010">integer</span> <span class="c004">)</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <a class="syntax" href="#simple-expr"><span class="c010">simple-expr</span></a> <span class="c004">.[</span>  <span class="c010">integer</span> <span class="c004">]</span>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">!</span> <a class="syntax" href="#simple-expr"><span class="c010">simple-expr</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">(</span> <a class="syntax" href="#simple-expr"><span class="c010">simple-expr</span></a> <span class="c004">)</span>
</td></tr>
</table></td></tr>
</table></div><p>
The first two cases refer to a value identifier, either unqualified or
qualified by the path to the structure that define it.
<span class="c003">*</span> refers to the result just computed (typically, the value of a
function application), and is valid only if the selected event is an
“after” event (typically, a function application).
<span class="c004">$</span> <span class="c010">integer</span> refer to a previously printed value. The remaining four
forms select part of an expression: respectively, a record field, an
array element, a string element, and the current contents of a
reference.</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">print </span><span class="c009">variables</span></span></dt><dd class="dd-description">
Print the values of the given variables. <span class="c003">print</span> can be abbreviated as
<span class="c003">p</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">display </span><span class="c009">variables</span></span></dt><dd class="dd-description">
Same as <span class="c003">print</span>, but limit the depth of printing to 1. Useful to
browse large data structures without printing them in full.
<span class="c003">display</span> can be abbreviated as <span class="c003">d</span>.
</dd></dl><p>When printing a complex expression, a name of the form <span class="c003">$</span><span class="c009">integer</span>
is automatically assigned to its value. Such names are also assigned
to parts of the value that cannot be printed because the maximal
printing depth is exceeded. Named values can be printed later on
with the commands <span class="c003">p $</span><span class="c009">integer</span> or <span class="c003">d $</span><span class="c009">integer</span>.
Named values are valid only as long as the program is stopped. They
are forgotten as soon as the program resumes execution.</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">set print_depth</span> <span class="c009">d</span></span></dt><dd class="dd-description">
Limit the printing of values to a maximal depth of <span class="c009">d</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">set print_length</span> <span class="c009">l</span></span></dt><dd class="dd-description">
Limit the printing of values to at most <span class="c009">l</span> nodes printed.
</dd></dl>
<!--TOC section id="s:debugger-control" 17.8  Controlling the debugger-->
<h2 class="section" id="s:debugger-control"><a class="section-anchor" href="#s:debugger-control" aria-hidden="true"></a>17.8  Controlling the debugger</h2><!--SEC END -->
<!--TOC subsection id="ss:debugger-name-and-arguments" 17.8.1  Setting the program name and arguments-->
<h3 class="subsection" id="ss:debugger-name-and-arguments"><a class="section-anchor" href="#ss:debugger-name-and-arguments" aria-hidden="true"></a>17.8.1  Setting the program name and arguments</h3><!--SEC END --><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">set program</span> <span class="c009">file</span></span></dt><dd class="dd-description">
Set the program name to <span class="c009">file</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">set arguments</span> <span class="c009">arguments</span></span></dt><dd class="dd-description">
Give <span class="c009">arguments</span> as command-line arguments for the program.
</dd></dl><p>A shell is used to pass the arguments to the debugged program. You can
therefore use wildcards, shell variables, and file redirections inside
the arguments. To debug programs that read from standard input, it is
recommended to redirect their input from a file (using
<span class="c003">set arguments &lt; input-file</span>), otherwise input to the program and
input to the debugger are not properly separated, and inputs are not
properly replayed when running the program backwards.</p>
<!--TOC subsection id="ss:debugger-loading" 17.8.2  How programs are loaded-->
<h3 class="subsection" id="ss:debugger-loading"><a class="section-anchor" href="#ss:debugger-loading" aria-hidden="true"></a>17.8.2  How programs are loaded</h3><!--SEC END --><p>The <span class="c003">loadingmode</span> variable controls how the program is executed.</p><dl class="description"><dt class="dt-description">
<span class="c006">set loadingmode direct</span></dt><dd class="dd-description">
The program is run directly by the debugger. This is the default mode.
</dd><dt class="dt-description"><span class="c006">set loadingmode runtime</span></dt><dd class="dd-description">
The debugger execute the OCaml runtime <span class="c003">ocamlrun</span> on the program.
Rarely useful; moreover it prevents the debugging of programs compiled
in “custom runtime” mode.
</dd><dt class="dt-description"><span class="c006">set loadingmode manual</span></dt><dd class="dd-description">
The user starts manually the program, when asked by the debugger.
Allows remote debugging (see section <a href="#ss%3Adebugger-communication">17.8.8</a>).
</dd></dl>
<!--TOC subsection id="ss:debugger-search-path" 17.8.3  Search path for files-->
<h3 class="subsection" id="ss:debugger-search-path"><a class="section-anchor" href="#ss:debugger-search-path" aria-hidden="true"></a>17.8.3  Search path for files</h3><!--SEC END --><p>The debugger searches for source files and compiled interface files in
a list of directories, the search path. The search path initially
contains the current directory <span class="c003">.</span> and the standard library directory.
The <span class="c003">directory</span> command adds directories to the path.</p><p>Whenever the search path is modified, the debugger will clear any
information it may have cached about the files.</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">directory</span> <span class="c009">directorynames</span></span></dt><dd class="dd-description">
Add the given directories to the search path. These directories are
added at the front, and will therefore be searched first.</dd><dt class="dt-description"><span class="c013"><span class="c003">directory</span> <span class="c009">directorynames</span> <span class="c003">for</span> <span class="c009">modulename</span></span></dt><dd class="dd-description">
Same as <span class="c003">directory</span> <span class="c009">directorynames</span>, but the given directories will be
searched only when looking for the source file of a module that has 
been packed into <span class="c009">modulename</span>.</dd><dt class="dt-description"><span class="c006">directory</span></dt><dd class="dd-description">
Reset the search path. This requires confirmation.
</dd></dl>
<!--TOC subsection id="ss:debugger-working-dir" 17.8.4  Working directory-->
<h3 class="subsection" id="ss:debugger-working-dir"><a class="section-anchor" href="#ss:debugger-working-dir" aria-hidden="true"></a>17.8.4  Working directory</h3><!--SEC END --><p>Each time a program is started in the debugger, it inherits its working
directory from the current working directory of the debugger. This
working directory is initially whatever it inherited from its parent
process (typically the shell), but you can specify a new working
directory in the debugger with the <span class="c003">cd</span> command or the <span class="c003">-cd</span>
command-line option.</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">cd</span> <span class="c009">directory</span></span></dt><dd class="dd-description">
Set the working directory for <span class="c003">ocamldebug</span> to <span class="c009">directory</span>.</dd><dt class="dt-description"><span class="c006">pwd</span></dt><dd class="dd-description">
Print the working directory for <span class="c003">ocamldebug</span>.
</dd></dl>
<!--TOC subsection id="ss:debugger-reverse-execution" 17.8.5  Turning reverse execution on and off-->
<h3 class="subsection" id="ss:debugger-reverse-execution"><a class="section-anchor" href="#ss:debugger-reverse-execution" aria-hidden="true"></a>17.8.5  Turning reverse execution on and off</h3><!--SEC END --><p>In some cases, you may want to turn reverse execution off. This speeds
up the program execution, and is also sometimes useful for interactive
programs.</p><p>Normally, the debugger takes checkpoints of the program state from
time to time. That is, it makes a copy of the current state of the
program (using the Unix system call <span class="c003">fork</span>). If the variable
<span class="c009">checkpoints</span> is set to <span class="c003">off</span>, the debugger will not take any
checkpoints.</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">set checkpoints</span> <span class="c009">on/off</span></span></dt><dd class="dd-description">
Select whether the debugger makes checkpoints or not.
</dd></dl>
<!--TOC subsection id="ss:debugger-fork" 17.8.6  Behavior of the debugger with respect to <span class="c003">fork</span>-->
<h3 class="subsection" id="ss:debugger-fork"><a class="section-anchor" href="#ss:debugger-fork" aria-hidden="true"></a>17.8.6  Behavior of the debugger with respect to <span class="c003">fork</span></h3><!--SEC END --><p>When the program issues a call to <span class="c003">fork</span>, the debugger can either
follow the child or the parent. By default, the debugger follows the
parent process. The variable <span class="c009">follow_fork_mode</span> controls this
behavior:</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">set follow_fork_mode</span> <span class="c009">child/parent</span></span></dt><dd class="dd-description">
Select whether to follow the child or the parent in case of a call to
<span class="c003">fork</span>.
</dd></dl>
<!--TOC subsection id="ss:debugger-stop-at-new-load" 17.8.7  Stopping execution when new code is loaded-->
<h3 class="subsection" id="ss:debugger-stop-at-new-load"><a class="section-anchor" href="#ss:debugger-stop-at-new-load" aria-hidden="true"></a>17.8.7  Stopping execution when new code is loaded</h3><!--SEC END --><p>The debugger is compatible with the <span class="c003">Dynlink</span> module. However, when an
external module is not yet loaded, it is impossible to set a
breakpoint in its code. In order to facilitate setting breakpoints in
dynamically loaded code, the debugger stops the program each time new
modules are loaded. This behavior can be disabled using the
<span class="c009">break_on_load</span> variable:</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">set break_on_load</span> <span class="c009">on/off</span></span></dt><dd class="dd-description">
Select whether to stop after loading new code.
</dd></dl>
<!--TOC subsection id="ss:debugger-communication" 17.8.8  Communication between the debugger and the program-->
<h3 class="subsection" id="ss:debugger-communication"><a class="section-anchor" href="#ss:debugger-communication" aria-hidden="true"></a>17.8.8  Communication between the debugger and the program</h3><!--SEC END --><p>The debugger communicate with the program being debugged through a
Unix socket. You may need to change the socket name, for example if
you need to run the debugger on a machine and your program on another.</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">set socket</span> <span class="c009">socket</span></span></dt><dd class="dd-description">
Use <span class="c009">socket</span> for communication with the program. <span class="c009">socket</span> can be
either a file name, or an Internet port specification
<span class="c009">host</span>:<span class="c009">port</span>, where <span class="c009">host</span> is a host name or an Internet
address in dot notation, and <span class="c009">port</span> is a port number on the host.
</dd></dl><p>On the debugged program side, the socket name is passed through the
<span class="c003">CAML_DEBUG_SOCKET</span> environment variable.</p>
<!--TOC subsection id="ss:debugger-fine-tuning" 17.8.9  Fine-tuning the debugger-->
<h3 class="subsection" id="ss:debugger-fine-tuning"><a class="section-anchor" href="#ss:debugger-fine-tuning" aria-hidden="true"></a>17.8.9  Fine-tuning the debugger</h3><!--SEC END --><p>Several variables enables to fine-tune the debugger. Reasonable
defaults are provided, and you should normally not have to change them.</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">set processcount</span> <span class="c009">count</span></span></dt><dd class="dd-description">
Set the maximum number of checkpoints to <span class="c009">count</span>. More checkpoints
facilitate going far back in time, but use more memory and create more
Unix processes.
</dd></dl><p>As checkpointing is quite expensive, it must not be done too often. On
the other hand, backward execution is faster when checkpoints are
taken more often. In particular, backward single-stepping is more
responsive when many checkpoints have been taken just before the
current time. To fine-tune the checkpointing strategy, the debugger
does not take checkpoints at the same frequency for long displacements
(e.g. <span class="c003">run</span>) and small ones (e.g. <span class="c003">step</span>). The two variables <span class="c003">bigstep</span>
and <span class="c003">smallstep</span> contain the number of events between two checkpoints
in each case.</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">set bigstep</span> <span class="c009">count</span></span></dt><dd class="dd-description">
Set the number of events between two checkpoints for long displacements.
</dd><dt class="dt-description"><span class="c013"><span class="c003">set smallstep</span> <span class="c009">count</span></span></dt><dd class="dd-description">
Set the number of events between two checkpoints for small
displacements.
</dd></dl><p>The following commands display information on checkpoints and events:</p><dl class="description"><dt class="dt-description">
<span class="c006">info checkpoints</span></dt><dd class="dd-description">
Print a list of checkpoints.
</dd><dt class="dt-description"><span class="c013"><span class="c003">info events</span> [<span class="c009">module</span>]</span></dt><dd class="dd-description">
Print the list of events in the given module (the current module, by default).
</dd></dl>
<!--TOC subsection id="ss:debugger-printers" 17.8.10  User-defined printers-->
<h3 class="subsection" id="ss:debugger-printers"><a class="section-anchor" href="#ss:debugger-printers" aria-hidden="true"></a>17.8.10  User-defined printers</h3><!--SEC END --><p>Just as in the toplevel system (section <a href="#s%3Atoplevel-directives">10.2</a>),
the user can register functions for printing values of certain types.
For technical reasons, the debugger cannot call printing functions
that reside in the program being debugged. The code for the printing
functions must therefore be loaded explicitly in the debugger.</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">load_printer "</span><span class="c009">file-name</span><span class="c003">"</span></span></dt><dd class="dd-description">
Load in the debugger the indicated <span class="c003">.cmo</span> or <span class="c003">.cma</span> object file. The
file is loaded in an environment consisting only of the OCaml
standard library plus the definitions provided by object files
previously loaded using <span class="c003">load_printer</span>. If this file depends on other
object files not yet loaded, the debugger automatically loads them if
it is able to find them in the search path. The loaded file does not
have direct access to the modules of the program being debugged.</dd><dt class="dt-description"><span class="c013"><span class="c003">install_printer </span><span class="c009">printer-name</span></span></dt><dd class="dd-description">
Register the function named <span class="c009">printer-name</span> (a
value path) as a printer for objects whose types match the argument
type of the function. That is, the debugger will call
<span class="c009">printer-name</span> when it has such an object to print.
The printing function <span class="c009">printer-name</span> must use the <span class="c003">Format</span> library
module to produce its output, otherwise its output will not be
correctly located in the values printed by the toplevel loop.<p>The value path <span class="c009">printer-name</span> must refer to one of the functions
defined by the object files loaded using <span class="c003">load_printer</span>. It cannot
reference the functions of the program being debugged.</p></dd><dt class="dt-description"><span class="c013"><span class="c003">remove_printer </span><span class="c009">printer-name</span></span></dt><dd class="dd-description">
Remove the named function from the table of value printers.
</dd></dl>
<!--TOC section id="s:debugger-misc-cmds" 17.9  Miscellaneous commands-->
<h2 class="section" id="s:debugger-misc-cmds"><a class="section-anchor" href="#s:debugger-misc-cmds" aria-hidden="true"></a>17.9  Miscellaneous commands</h2><!--SEC END --><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">list</span> [<span class="c009">module</span>] [<span class="c009">beginning</span>] [<span class="c009">end</span>]</span></dt><dd class="dd-description">
List the source of module <span class="c009">module</span>, from line number
<span class="c009">beginning</span> to line number <span class="c009">end</span>. By default, 20 lines of the
current module are displayed, starting 10 lines before the current
position.
</dd><dt class="dt-description"><span class="c013"><span class="c003">source</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Read debugger commands from the script <span class="c009">filename</span>.
</dd></dl>
<!--TOC section id="s:inf-debugger" 17.10  Running the debugger under Emacs-->
<h2 class="section" id="s:inf-debugger"><a class="section-anchor" href="#s:inf-debugger" aria-hidden="true"></a>17.10  Running the debugger under Emacs</h2><!--SEC END --><p>The most user-friendly way to use the debugger is to run it under Emacs.
See the file <span class="c003">emacs/README</span> in the distribution for information on how
to load the Emacs Lisp files for OCaml support.</p><p>The OCaml debugger is started under Emacs by the command <span class="c003">M-x camldebug</span>, with argument the name of the executable file
<span class="c009">progname</span> to debug. Communication with the debugger takes place
in an Emacs buffer named <span class="c003">*camldebug-</span><span class="c009">progname</span><span class="c003">*</span>. The editing
and history facilities of Shell mode are available for interacting
with the debugger.</p><p>In addition, Emacs displays the source files containing the current
event (the current position in the program execution) and highlights
the location of the event. This display is updated synchronously with
the debugger action.</p><p>The following bindings for the most common debugger commands are
available in the <span class="c003">*camldebug-</span><span class="c009">progname</span><span class="c003">*</span> buffer:</p><dl class="description"><dt class="dt-description">
<span class="c006">C-c C-s</span></dt><dd class="dd-description"> (command <span class="c003">step</span>): execute the program one step forward.
</dd><dt class="dt-description"><span class="c006">C-c C-k</span></dt><dd class="dd-description"> (command <span class="c003">backstep</span>): execute the program one step backward.
</dd><dt class="dt-description"><span class="c006">C-c C-n</span></dt><dd class="dd-description"> (command <span class="c003">next</span>): execute the program one step
forward, skipping over function calls.
</dd><dt class="dt-description"><span class="c013">Middle mouse button</span></dt><dd class="dd-description"> (command <span class="c003">display</span>): display named value.
<span class="c003">$</span><span class="c009">n</span> under mouse cursor (support incremental browsing of large
data structures).
</dd><dt class="dt-description"><span class="c006">C-c C-p</span></dt><dd class="dd-description"> (command <span class="c003">print</span>): print value of identifier at point.
</dd><dt class="dt-description"><span class="c006">C-c C-d</span></dt><dd class="dd-description"> (command <span class="c003">display</span>): display value of identifier at point.
</dd><dt class="dt-description"><span class="c006">C-c C-r</span></dt><dd class="dd-description"> (command <span class="c003">run</span>): execute the program forward to next
breakpoint.
</dd><dt class="dt-description"><span class="c006">C-c C-v</span></dt><dd class="dd-description"> (command <span class="c003">reverse</span>): execute the program backward to
latest breakpoint.
</dd><dt class="dt-description"><span class="c006">C-c C-l</span></dt><dd class="dd-description"> (command <span class="c003">last</span>): go back one step in the command history.
</dd><dt class="dt-description"><span class="c006">C-c C-t</span></dt><dd class="dd-description"> (command <span class="c003">backtrace</span>): display backtrace of function calls.
</dd><dt class="dt-description"><span class="c006">C-c C-f</span></dt><dd class="dd-description"> (command <span class="c003">finish</span>): run forward till the current
function returns.
</dd><dt class="dt-description"><span class="c006">C-c &lt;</span></dt><dd class="dd-description"> (command <span class="c003">up</span>): select the stack frame below the
current frame.
</dd><dt class="dt-description"><span class="c006">C-c &gt;</span></dt><dd class="dd-description"> (command <span class="c003">down</span>): select the stack frame above the
current frame.
</dd></dl><p>In all buffers in OCaml editing mode, the following debugger commands
are also available:</p><dl class="description"><dt class="dt-description">
<span class="c006">C-x C-a C-b</span></dt><dd class="dd-description"> (command <span class="c003">break</span>): set a breakpoint at event closest
to point
</dd><dt class="dt-description"><span class="c006">C-x C-a C-p</span></dt><dd class="dd-description"> (command <span class="c003">print</span>): print value of identifier at point
</dd><dt class="dt-description"><span class="c006">C-x C-a C-d</span></dt><dd class="dd-description"> (command <span class="c003">display</span>): display value of identifier at point
</dd></dl>
<!--TOC chapter id="sec413" Chapter 18  Profiling (ocamlprof)-->
<h1 class="chapter" id="sec413">Chapter 18  Profiling (ocamlprof)</h1><!--SEC END --><p> <a id="c:profiler"></a>
</p><!--NAME profil.html-->
<p>This chapter describes how the execution of OCaml
programs can be profiled, by recording how many times functions are
called, branches of conditionals are taken, …</p>
<!--TOC section id="s:ocamlprof-compiling" 18.1  Compiling for profiling-->
<h2 class="section" id="s:ocamlprof-compiling"><a class="section-anchor" href="#s:ocamlprof-compiling" aria-hidden="true"></a>18.1  Compiling for profiling</h2><!--SEC END --><p>Before profiling an execution, the program must be compiled in
profiling mode, using the <span class="c003">ocamlcp</span> front-end to the <span class="c003">ocamlc</span> compiler
(see chapter <a href="#c%3Acamlc">9</a>) or the <span class="c003">ocamloptp</span> front-end to the
<span class="c003">ocamlopt</span> compiler (see chapter <a href="#c%3Anativecomp">12</a>). When compiling
modules separately, <span class="c003">ocamlcp</span> or <span class="c003">ocamloptp</span> must be used when
compiling the modules (production of <span class="c003">.cmo</span> or <span class="c003">.cmx</span> files), and can
also be used (though this is not strictly necessary) when linking them
together.</p>
<!--TOC paragraph id="p:ocamlprof-warning" Note-->
<h5 class="paragraph" id="p:ocamlprof-warning"><a class="section-anchor" href="#p:ocamlprof-warning" aria-hidden="true"></a>Note</h5><!--SEC END --><p> If a module (<span class="c003">.ml</span> file) doesn’t have a corresponding
interface (<span class="c003">.mli</span> file), then compiling it with <span class="c003">ocamlcp</span> will produce
object files (<span class="c003">.cmi</span> and <span class="c003">.cmo</span>) that are not compatible with the ones
produced by <span class="c003">ocamlc</span>, which may lead to problems (if the <span class="c003">.cmi</span> or
<span class="c003">.cmo</span> is still around) when switching between profiling and
non-profiling compilations. To avoid this problem, you should always
have a <span class="c003">.mli</span> file for each <span class="c003">.ml</span> file. The same problem exists with
<span class="c003">ocamloptp</span>.</p>
<!--TOC paragraph id="p:ocamlprof-reserved" Note-->
<h5 class="paragraph" id="p:ocamlprof-reserved"><a class="section-anchor" href="#p:ocamlprof-reserved" aria-hidden="true"></a>Note</h5><!--SEC END --><p> To make sure your programs can be compiled in
profiling mode, avoid using any identifier that begins with
<span class="c003">__ocaml_prof</span>.</p><p>The amount of profiling information can be controlled through the <span class="c003">-P</span>
option to <span class="c003">ocamlcp</span> or <span class="c003">ocamloptp</span>, followed by one or several letters
indicating which parts of the program should be profiled:</p><dl class="description"><dt class="dt-description">
<span class="c006">a</span></dt><dd class="dd-description"> all options
</dd><dt class="dt-description"><span class="c006">f</span></dt><dd class="dd-description"> function calls : a count point is set at the beginning of
each function body
</dd><dt class="dt-description"><span class="c006">i</span></dt><dd class="dd-description"> <span class="c013">if …then …else …</span> : count points are set in
both <span class="c013">then</span> branch and <span class="c013">else</span> branch
</dd><dt class="dt-description"><span class="c006">l</span></dt><dd class="dd-description"> <span class="c013">while, for</span> loops: a count point is set at the beginning of
the loop body
</dd><dt class="dt-description"><span class="c006">m</span></dt><dd class="dd-description"> <span class="c013">match</span> branches: a count point is set at the beginning of the
body of each branch
</dd><dt class="dt-description"><span class="c006">t</span></dt><dd class="dd-description"> <span class="c013">try …with …</span> branches: a count point is set at the
beginning of the body of each branch
</dd></dl><p>For instance, compiling with <span class="c003">ocamlcp -P film</span> profiles function calls,
if…then…else…, loops and pattern matching.</p><p>Calling <span class="c003">ocamlcp</span> or <span class="c003">ocamloptp</span> without the <span class="c003">-P</span> option defaults to
<span class="c003">-P fm</span>, meaning that only function calls and pattern matching are
profiled.</p>
<!--TOC paragraph id="sec417" Note-->
<h5 class="paragraph" id="sec417"><a class="section-anchor" href="#sec417" aria-hidden="true"></a>Note</h5><!--SEC END --><p> For compatibility with previous releases, <span class="c003">ocamlcp</span>
also accepts the <span class="c003">-p</span> option, with the same arguments and behaviour as
<span class="c003">-P</span>.</p><p>The <span class="c003">ocamlcp</span> and <span class="c003">ocamloptp</span> commands also accept all the options of
the corresponding <span class="c003">ocamlc</span> or <span class="c003">ocamlopt</span> compiler, except the <span class="c003">-pp</span>
(preprocessing) option.</p>
<!--TOC section id="s:ocamlprof-profiling" 18.2  Profiling an execution-->
<h2 class="section" id="s:ocamlprof-profiling"><a class="section-anchor" href="#s:ocamlprof-profiling" aria-hidden="true"></a>18.2  Profiling an execution</h2><!--SEC END --><p>Running an executable that has been compiled with <span class="c003">ocamlcp</span> or
<span class="c003">ocamloptp</span> records the execution counts for the specified parts of
the program and saves them in a file called <span class="c003">ocamlprof.dump</span> in the
current directory.</p><p>If the environment variable <span class="c003">OCAMLPROF_DUMP</span> is set when the program
exits, its value is used as the file name instead of <span class="c003">ocamlprof.dump</span>.</p><p>The dump file is written only if the program terminates
normally (by calling <span class="c003">exit</span> or by falling through). It is not written
if the program terminates with an uncaught exception.</p><p>If a compatible dump file already exists in the current directory, then the
profiling information is accumulated in this dump file. This allows, for
instance, the profiling of several executions of a program on
different inputs. Note that dump files produced by byte-code
executables (compiled with <span class="c003">ocamlcp</span>) are compatible with the dump
files produced by native executables (compiled with <span class="c003">ocamloptp</span>).</p>
<!--TOC section id="s:ocamlprof-printing" 18.3  Printing profiling information-->
<h2 class="section" id="s:ocamlprof-printing"><a class="section-anchor" href="#s:ocamlprof-printing" aria-hidden="true"></a>18.3  Printing profiling information</h2><!--SEC END --><p>The <span class="c003">ocamlprof</span> command produces a source listing of the program modules
where execution counts have been inserted as comments. For instance,
</p><pre>        ocamlprof foo.ml
</pre><p>prints the source code for the <span class="c003">foo</span> module, with comments indicating
how many times the functions in this module have been called. Naturally,
this information is accurate only if the source file has not been modified
after it was compiled.</p><p>The following options are recognized by <span class="c003">ocamlprof</span>:</p><dl class="description"><dt class="dt-description"><span class="c013"><span class="c003">-args</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Read additional newline-terminated command line arguments from <span class="c009">filename</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-args0</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Read additional null character terminated command line arguments from <span class="c009">filename</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-f</span> <span class="c009">dumpfile</span></span></dt><dd class="dd-description">
Specifies an alternate dump file of profiling information to be read.</dd><dt class="dt-description"><span class="c013"><span class="c003">-F</span> <span class="c009">string</span></span></dt><dd class="dd-description">
Specifies an additional string to be output with profiling information.
By default, <span class="c003">ocamlprof</span> will annotate programs with comments of the form
<span class="c003">(* <span class="c009">n</span> *)</span> where <span class="c009">n</span> is the counter value for a profiling
point. With option <span class="c003">-F <span class="c009">s</span></span>, the annotation will be
<span class="c003">(* <span class="c009">sn</span> *)</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-impl</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Process the file <span class="c009">filename</span> as an implementation file, even if its
extension is not <span class="c003">.ml</span>.</dd><dt class="dt-description"><span class="c013"><span class="c003">-intf</span> <span class="c009">filename</span></span></dt><dd class="dd-description">
Process the file <span class="c009">filename</span> as an interface file, even if its
extension is not <span class="c003">.mli</span>.</dd><dt class="dt-description"><span class="c006">-version</span></dt><dd class="dd-description">
Print version string and exit.</dd><dt class="dt-description"><span class="c006">-vnum</span></dt><dd class="dd-description">
Print short version number and exit.</dd><dt class="dt-description"><span class="c013"><span class="c003">-help</span> or <span class="c003">--help</span></span></dt><dd class="dd-description">
Display a short usage summary and exit.
</dd></dl>
<!--TOC section id="s:ocamlprof-time-profiling" 18.4  Time profiling-->
<h2 class="section" id="s:ocamlprof-time-profiling"><a class="section-anchor" href="#s:ocamlprof-time-profiling" aria-hidden="true"></a>18.4  Time profiling</h2><!--SEC END --><p>Profiling with <span class="c003">ocamlprof</span> only records execution counts, not the actual
time spent within each function. There is currently no way to perform
time profiling on bytecode programs generated by <span class="c003">ocamlc</span>. For time
profiling of native code, users are recommended to use standard tools
such as perf (on Linux), Instruments (on macOS) and DTrace. Profiling
with <span class="c003">gprof</span> is no longer supported.

</p>
<!--TOC chapter id="sec421" Chapter 19  The ocamlbuild compilation manager-->
<h1 class="chapter" id="sec421">Chapter 19  The ocamlbuild compilation manager</h1><!--SEC END --><p> <a id="c:ocamlbuild"></a></p><p>Since OCaml version 4.03, the ocamlbuild compilation manager is
distributed separately from the OCaml compiler. The project is now
hosted at <a href="https://github.com/ocaml/ocamlbuild/"><span class="c003">https://github.com/ocaml/ocamlbuild/</span></a>.

</p>
<!--TOC chapter id="c:intf-c" Chapter 20  Interfacing C with OCaml-->
<h1 class="chapter" id="c:intf-c">Chapter 20  Interfacing C with OCaml</h1><!--SEC END --><!--NAME intfc.html-->
<p>This chapter describes how user-defined primitives, written in C, can
be linked with OCaml code and called from OCaml functions, and how
these C functions can call back to OCaml code.</p>
<!--TOC section id="s:c-overview" 20.1  Overview and compilation information-->
<h2 class="section" id="s:c-overview"><a class="section-anchor" href="#s:c-overview" aria-hidden="true"></a>20.1  Overview and compilation information</h2><!--SEC END -->
<!--TOC subsection id="ss:c-prim-decl" 20.1.1  Declaring primitives-->
<h3 class="subsection" id="ss:c-prim-decl"><a class="section-anchor" href="#ss:c-prim-decl" aria-hidden="true"></a>20.1.1  Declaring primitives</h3><!--SEC END --><div class="syntax"><table class="display dcenter"><tr class="c019"><td class="dcell"><table class="c001 cellpading0"><tr><td class="c018">
<a class="syntax" href="#definition"><span class="c010">definition</span></a></td><td class="c015">::=</td><td class="c017"> ...
 </td></tr>
<tr><td class="c018">&nbsp;</td><td class="c015">∣</td><td class="c017"> <span class="c004">external</span> <a class="syntax" href="#value-name"><span class="c010">value-name</span></a> <span class="c004">:</span>  <a class="syntax" href="#typexpr"><span class="c010">typexpr</span></a> <span class="c004">=</span>  <a class="syntax" href="#external-declaration"><span class="c010">external-declaration</span></a>
 </td></tr>
<tr><td class="c018">&nbsp;</td></tr>
<tr><td class="c018">
<a class="syntax" id="external-declaration"><span class="c010">external-declaration</span></a></td><td class="c015">::=</td><td class="c017"> <a class="syntax" href="#string-literal"><span class="c010">string-literal</span></a>  [ <a class="syntax" href="#string-literal"><span class="c010">string-literal</span></a>  [ <a class="syntax" href="#string-literal"><span class="c010">string-literal</span></a> ] ]
</td></tr>
</table></td></tr>
</table></div><p>User primitives are declared in an implementation file or
<span class="c004">struct</span>…<span class="c004">end</span> module expression using the <span class="c004">external</span> keyword:
</p><pre>
        external <span class="c009">name</span> : <span class="c009">type</span> = <span class="c009">C-function-name</span>
</pre><p>
This defines the value name <span class="c009">name</span> as a function with type
<span class="c009">type</span> that executes by calling the given C function.
For instance, here is how the <span class="c003">int_of_string</span> primitive is declared in the
standard library module <span class="c003">Stdlib</span>:
</p><pre>        external int_of_string : string -&gt; int = "caml_int_of_string"
</pre><p>Primitives with several arguments are always curried. The C function
does not necessarily have the same name as the ML function.</p><p>External functions thus defined can be specified in interface files or
<span class="c004">sig</span>…<span class="c004">end</span> signatures either as regular values
</p><pre>
        val <span class="c009">name</span> : <span class="c009">type</span>
</pre><p>
thus hiding their implementation as C functions, or explicitly as
“manifest” external functions
</p><pre>
        external <span class="c009">name</span> : <span class="c009">type</span> = <span class="c009">C-function-name</span>
</pre><p>
The latter is slightly more efficient, as it allows clients of the
module to call directly the C function instead of going through the
corresponding OCaml function. On the other hand, it should not be used
in library modules if they have side-effects at toplevel, as this
direct call interferes with the linker’s algorithm for removing unused
modules from libraries at link-time.</p><p>The arity (number of arguments) of a primitive is automatically
determined from its OCaml type in the <span class="c003">external</span> declaration, by
counting the number of function arrows in the type. For instance,
<span class="c003">input</span> above has arity 4, and the <span class="c003">input</span> C function is called with
four arguments. Similarly,
</p><pre>    external input2 : in_channel * bytes * int * int -&gt; int = "input2"
</pre><p>has arity 1, and the <span class="c003">input2</span> C function receives one argument (which
is a quadruple of OCaml values).</p><p>Type abbreviations are not expanded when determining the arity of a
primitive. For instance,
</p><pre>        type int_endo = int -&gt; int
        external f : int_endo -&gt; int_endo = "f"
        external g : (int -&gt; int) -&gt; (int -&gt; int) = "f"
</pre><p><span class="c003">f</span> has arity 1, but <span class="c003">g</span> has arity 2. This allows a primitive to
return a functional value (as in the <span class="c003">f</span> example above): just remember
to name the functional return type in a type abbreviation.</p><p>The language accepts external declarations with one or two
flag strings in addition to the C function’s name. These flags are
reserved for the implementation of the standard library.</p>
<!--TOC subsection id="ss:c-prim-impl" 20.1.2  Implementing primitives-->
<h3 class="subsection" id="ss:c-prim-impl"><a class="section-anchor" href="#ss:c-prim-impl" aria-hidden="true"></a>20.1.2  Implementing primitives</h3><!--SEC END --><p>User primitives with arity <span class="c009">n</span> ≤ 5 are implemented by C functions
that take <span class="c009">n</span> arguments of type <span class="c003">value</span>, and return a result of type
<span class="c003">value</span>. The type <span class="c003">value</span> is the type of the representations for OCaml
values. It encodes objects of several base types (integers,
floating-point numbers, strings, …) as well as OCaml data
structures. The type <span class="c003">value</span> and the associated conversion
functions and macros are described in detail below. For instance,
here is the declaration for the C function implementing the <span class="c003">input</span>
primitive:
</p><pre>CAMLprim value input(value channel, value buffer, value offset, value length)
{
  ...
}
</pre><p>When the primitive function is applied in an OCaml program, the C
function is called with the values of the expressions to which the
primitive is applied as arguments. The value returned by the function is
passed back to the OCaml program as the result of the function
application.</p><p>User primitives with arity greater than 5 should be implemented by two
C functions. The first function, to be used in conjunction with the
bytecode compiler <span class="c003">ocamlc</span>, receives two arguments: a pointer to an
array of OCaml values (the values for the arguments), and an
integer which is the number of arguments provided. The other function,
to be used in conjunction with the native-code compiler <span class="c003">ocamlopt</span>,
takes its arguments directly. For instance, here are the two C
functions for the 7-argument primitive <span class="c003">Nat.add_nat</span>:
</p><pre>CAMLprim value add_nat_native(value nat1, value ofs1, value len1,
                              value nat2, value ofs2, value len2,
                              value carry_in)
{
  ...
}
CAMLprim value add_nat_bytecode(value * argv, int argn)
{
  return add_nat_native(argv[0], argv[1], argv[2], argv[3],
                        argv[4], argv[5], argv[6]);
}
</pre><p>The names of the two C functions must be given in the primitive
declaration, as follows:
</p><pre>
        external <span class="c009">name</span> : <span class="c009">type</span> =
                 <span class="c009">bytecode-C-function-name native-code-C-function-name</span>
</pre><p>
For instance, in the case of <span class="c003">add_nat</span>, the declaration is:
</p><pre>        external add_nat: nat -&gt; int -&gt; int -&gt; nat -&gt; int -&gt; int -&gt; int -&gt; int
                        = "add_nat_bytecode" "add_nat_native"
</pre><p>
Implementing a user primitive is actually two separate tasks: on the
one hand, decoding the arguments to extract C values from the given
OCaml values, and encoding the return value as an OCaml
value; on the other hand, actually computing the result from the arguments.
Except for very simple primitives, it is often preferable to have two
distinct C functions to implement these two tasks. The first function
actually implements the primitive, taking native C values as
arguments and returning a native C value. The second function,
often called the “stub code”, is a simple wrapper around the first
function that converts its arguments from OCaml values to C values,
call the first function, and convert the returned C value to OCaml
value. For instance, here is the stub code for the <span class="c003">input</span>
primitive:
</p><pre>CAMLprim value input(value channel, value buffer, value offset, value length)
{
  return Val_long(getblock((struct channel *) channel,
                           &amp;Byte(buffer, Long_val(offset)),
                           Long_val(length)));
}
</pre><p>(Here, <span class="c003">Val_long</span>, <span class="c003">Long_val</span> and so on are conversion macros for the
type <span class="c003">value</span>, that will be described later. The <span class="c003">CAMLprim</span> macro
expands to the required compiler directives to ensure that the
function is exported and accessible from OCaml.)
The hard work is performed by the function <span class="c003">getblock</span>, which is
declared as:
</p><pre>long getblock(struct channel * channel, char * p, long n)
{
  ...
}
</pre><p>
To write C code that operates on OCaml values, the following
include files are provided:
</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Include file</span></td><td class="c014"><span class="c013">Provides</span> </td></tr>
<tr><td class="c022">
<span class="c003">caml/mlvalues.h</span></td><td class="c021">definition of the <span class="c003">value</span> type, and conversion
macros </td></tr>
<tr><td class="c022"><span class="c003">caml/alloc.h</span></td><td class="c021">allocation functions (to create structured OCaml
objects) </td></tr>
<tr><td class="c022"><span class="c003">caml/memory.h</span></td><td class="c021">miscellaneous memory-related functions
and macros (for GC interface, in-place modification of structures, etc). </td></tr>
<tr><td class="c022"><span class="c003">caml/fail.h</span></td><td class="c021">functions for raising exceptions
(see section <a href="#ss%3Ac-exceptions">20.4.5</a>) </td></tr>
<tr><td class="c022"><span class="c003">caml/callback.h</span></td><td class="c021">callback from C to OCaml (see
section <a href="#s%3Ac-callback">20.7</a>). </td></tr>
<tr><td class="c022"><span class="c003">caml/custom.h</span></td><td class="c021">operations on custom blocks (see
section <a href="#s%3Ac-custom">20.9</a>). </td></tr>
<tr><td class="c022"><span class="c003">caml/intext.h</span></td><td class="c021">operations for writing user-defined
serialization and deserialization functions for custom blocks
(see section <a href="#s%3Ac-custom">20.9</a>). </td></tr>
<tr><td class="c022"><span class="c003">caml/threads.h</span></td><td class="c021">operations for interfacing in the presence
of multiple threads (see section <a href="#s%3AC-multithreading">20.12</a>). </td></tr>
</table></div></div><p>
Before including any of these files, you should define the <span class="c003">OCAML_NAME_SPACE</span>
macro. For instance,
</p><pre>#define CAML_NAME_SPACE
#include "caml/mlvalues.h"
#include "caml/fail.h"
</pre><p>These files reside in the <span class="c003">caml/</span> subdirectory of the OCaml
standard library directory, which is returned by the command
<span class="c003">ocamlc -where</span> (usually <span class="c003">/usr/local/lib/ocaml</span> or <span class="c003">/usr/lib/ocaml</span>).</p><p><span class="c013">Note:</span>
Including the header files without first defining <span class="c003">CAML_NAME_SPACE</span>
introduces in scope short names for most functions.
Those short names are deprecated, and may be removed in the future
because they usually produce clashes with names defined by other
C libraries.</p>
<!--TOC subsection id="ss:staticlink-c-code" 20.1.3  Statically linking C code with OCaml code-->
<h3 class="subsection" id="ss:staticlink-c-code"><a class="section-anchor" href="#ss:staticlink-c-code" aria-hidden="true"></a>20.1.3  Statically linking C code with OCaml code</h3><!--SEC END --><p>The OCaml runtime system comprises three main parts: the bytecode
interpreter, the memory manager, and a set of C functions that
implement the primitive operations. Some bytecode instructions are
provided to call these C functions, designated by their offset in a
table of functions (the table of primitives).</p><p>In the default mode, the OCaml linker produces bytecode for the
standard runtime system, with a standard set of primitives. References
to primitives that are not in this standard set result in the
“unavailable C primitive” error. (Unless dynamic loading of C
libraries is supported – see section <a href="#ss%3Adynlink-c-code">20.1.4</a> below.)</p><p>In the “custom runtime” mode, the OCaml linker scans the
object files and determines the set of required primitives. Then, it
builds a suitable runtime system, by calling the native code linker with:
</p><ul class="itemize"><li class="li-itemize">
the table of the required primitives;
</li><li class="li-itemize">a library that provides the bytecode interpreter, the
memory manager, and the standard primitives;
</li><li class="li-itemize">libraries and object code files (<span class="c003">.o</span> files) mentioned on the
command line for the OCaml linker, that provide implementations
for the user’s primitives.
</li></ul><p>
This builds a runtime system with the required primitives. The OCaml
linker generates bytecode for this custom runtime system. The
bytecode is appended to the end of the custom runtime system, so that
it will be automatically executed when the output file (custom
runtime + bytecode) is launched.</p><p>To link in “custom runtime” mode, execute the <span class="c003">ocamlc</span> command with:
</p><ul class="itemize"><li class="li-itemize">
the <span class="c003">-custom</span> option;
</li><li class="li-itemize">the names of the desired OCaml object files (<span class="c003">.cmo</span> and <span class="c003">.cma</span> files) ;
</li><li class="li-itemize">the names of the C object files and libraries (<span class="c003">.o</span> and <span class="c003">.a</span>
files) that implement the required primitives. Under Unix and Windows,
a library named <span class="c003">lib</span><span class="c009">name</span><span class="c003">.a</span> (respectively, <span class="c003">.lib</span>) residing in one of
the standard library directories can also be specified as <span class="c003">-cclib -l</span><span class="c009">name</span>.
</li></ul><p>If you are using the native-code compiler <span class="c003">ocamlopt</span>, the <span class="c003">-custom</span>
flag is not needed, as the final linking phase of <span class="c003">ocamlopt</span> always
builds a standalone executable. To build a mixed OCaml/C executable,
execute the <span class="c003">ocamlopt</span> command with:
</p><ul class="itemize"><li class="li-itemize">
the names of the desired OCaml native object files (<span class="c003">.cmx</span> and
<span class="c003">.cmxa</span> files);
</li><li class="li-itemize">the names of the C object files and libraries (<span class="c003">.o</span>, <span class="c003">.a</span>,
<span class="c003">.so</span> or <span class="c003">.dll</span> files) that implement the required primitives.
</li></ul><p>Starting with Objective Caml 3.00, it is possible to record the
<span class="c003">-custom</span> option as well as the names of C libraries in an OCaml
library file <span class="c003">.cma</span> or <span class="c003">.cmxa</span>. For instance, consider an OCaml library
<span class="c003">mylib.cma</span>, built from the OCaml object files <span class="c003">a.cmo</span> and <span class="c003">b.cmo</span>,
which reference C code in <span class="c003">libmylib.a</span>. If the library is
built as follows:
</p><pre>
        ocamlc -a -o mylib.cma -custom a.cmo b.cmo -cclib -lmylib
</pre><p>
users of the library can simply link with <span class="c003">mylib.cma</span>:
</p><pre>
        ocamlc -o myprog mylib.cma ...
</pre><p>
and the system will automatically add the <span class="c003">-custom</span> and <span class="c003">-cclib -lmylib</span> options, achieving the same effect as
</p><pre>
        ocamlc -o myprog -custom a.cmo b.cmo ... -cclib -lmylib
</pre><p>
The alternative is of course to build the library without extra
options:
</p><pre>
        ocamlc -a -o mylib.cma a.cmo b.cmo
</pre><p>
and then ask users to provide the <span class="c003">-custom</span> and <span class="c003">-cclib -lmylib</span>
options themselves at link-time:
</p><pre>
        ocamlc -o myprog -custom mylib.cma ... -cclib -lmylib
</pre><p>
The former alternative is more convenient for the final users of the
library, however.</p>
<!--TOC subsection id="ss:dynlink-c-code" 20.1.4  Dynamically linking C code with OCaml code-->
<h3 class="subsection" id="ss:dynlink-c-code"><a class="section-anchor" href="#ss:dynlink-c-code" aria-hidden="true"></a>20.1.4  Dynamically linking C code with OCaml code</h3><!--SEC END --><p>Starting with Objective Caml 3.03, an alternative to static linking of C code
using the <span class="c003">-custom</span> code is provided. In this mode, the OCaml linker
generates a pure bytecode executable (no embedded custom runtime
system) that simply records the names of dynamically-loaded libraries
containing the C code. The standard OCaml runtime system <span class="c003">ocamlrun</span>
then loads dynamically these libraries, and resolves references to the
required primitives, before executing the bytecode.</p><p>This facility is currently available on all platforms supported by
OCaml except Cygwin 64 bits.</p><p>To dynamically link C code with OCaml code, the C code must first be
compiled into a shared library (under Unix) or DLL (under Windows).
This involves 1- compiling the C files with appropriate C compiler
flags for producing position-independent code (when required by the
operating system), and 2- building a
shared library from the resulting object files. The resulting shared
library or DLL file must be installed in a place where <span class="c003">ocamlrun</span> can
find it later at program start-up time (see
section <a href="#s%3Aocamlrun-dllpath">11.3</a>).
Finally (step 3), execute the <span class="c003">ocamlc</span> command with
</p><ul class="itemize"><li class="li-itemize">
the names of the desired OCaml object files (<span class="c003">.cmo</span> and <span class="c003">.cma</span> files) ;
</li><li class="li-itemize">the names of the C shared libraries (<span class="c003">.so</span> or <span class="c003">.dll</span> files) that
implement the required primitives. Under Unix and Windows,
a library named <span class="c003">dll</span><span class="c009">name</span><span class="c003">.so</span> (respectively, <span class="c003">.dll</span>) residing
in one of the standard library directories can also be specified as
<span class="c003">-dllib -l</span><span class="c009">name</span>.
</li></ul><p>
Do <em>not</em> set the <span class="c003">-custom</span> flag, otherwise you’re back to static linking
as described in section <a href="#ss%3Astaticlink-c-code">20.1.3</a>.
The <span class="c003">ocamlmklib</span> tool (see section <a href="#s%3Aocamlmklib">20.14</a>)
automates steps 2 and 3.</p><p>As in the case of static linking, it is possible (and recommended) to
record the names of C libraries in an OCaml <span class="c003">.cma</span> library archive.
Consider again an OCaml library
<span class="c003">mylib.cma</span>, built from the OCaml object files <span class="c003">a.cmo</span> and <span class="c003">b.cmo</span>,
which reference C code in <span class="c003">dllmylib.so</span>. If the library is
built as follows:
</p><pre>
        ocamlc -a -o mylib.cma a.cmo b.cmo -dllib -lmylib
</pre><p>
users of the library can simply link with <span class="c003">mylib.cma</span>:
</p><pre>
        ocamlc -o myprog mylib.cma ...
</pre><p>
and the system will automatically add the <span class="c003">-dllib -lmylib</span> option,
achieving the same effect as
</p><pre>
        ocamlc -o myprog a.cmo b.cmo ... -dllib -lmylib
</pre><p>
Using this mechanism, users of the library <span class="c003">mylib.cma</span> do not need to
known that it references C code, nor whether this C code must be
statically linked (using <span class="c003">-custom</span>) or dynamically linked.</p>
<!--TOC subsection id="ss:c-static-vs-dynamic" 20.1.5  Choosing between static linking and dynamic linking-->
<h3 class="subsection" id="ss:c-static-vs-dynamic"><a class="section-anchor" href="#ss:c-static-vs-dynamic" aria-hidden="true"></a>20.1.5  Choosing between static linking and dynamic linking</h3><!--SEC END --><p>After having described two different ways of linking C code with OCaml
code, we now review the pros and cons of each, to help developers of
mixed OCaml/C libraries decide.</p><p>The main advantage of dynamic linking is that it preserves the
platform-independence of bytecode executables. That is, the bytecode
executable contains no machine code, and can therefore be compiled on
platform <span class="c009">A</span> and executed on other platforms <span class="c009">B</span>, <span class="c009">C</span>, …, as long
as the required shared libraries are available on all these
platforms. In contrast, executables generated by <span class="c003">ocamlc -custom</span> run
only on the platform on which they were created, because they embark a
custom-tailored runtime system specific to that platform. In
addition, dynamic linking results in smaller executables.</p><p>Another advantage of dynamic linking is that the final users of the
library do not need to have a C compiler, C linker, and C runtime
libraries installed on their machines. This is no big deal under
Unix and Cygwin, but many Windows users are reluctant to install
Microsoft Visual C just to be able to do <span class="c003">ocamlc -custom</span>.</p><p>There are two drawbacks to dynamic linking. The first is that the
resulting executable is not stand-alone: it requires the shared
libraries, as well as <span class="c003">ocamlrun</span>, to be installed on the machine
executing the code. If you wish to distribute a stand-alone
executable, it is better to link it statically, using <span class="c003">ocamlc -custom -ccopt -static</span> or <span class="c003">ocamlopt -ccopt -static</span>. Dynamic linking also
raises the “DLL hell” problem: some care must be taken to ensure
that the right versions of the shared libraries are found at start-up
time.</p><p>The second drawback of dynamic linking is that it complicates the
construction of the library. The C compiler and linker flags to
compile to position-independent code and build a shared library vary
wildly between different Unix systems. Also, dynamic linking is not
supported on all Unix systems, requiring a fall-back case to static
linking in the Makefile for the library. The <span class="c003">ocamlmklib</span> command
(see section <a href="#s%3Aocamlmklib">20.14</a>) tries to hide some of these system
dependencies.</p><p>In conclusion: dynamic linking is highly recommended under the native
Windows port, because there are no portability problems and it is much
more convenient for the end users. Under Unix, dynamic linking should
be considered for mature, frequently used libraries because it
enhances platform-independence of bytecode executables. For new or
rarely-used libraries, static linking is much simpler to set up in a
portable way.</p>
<!--TOC subsection id="ss:custom-runtime" 20.1.6  Building standalone custom runtime systems-->
<h3 class="subsection" id="ss:custom-runtime"><a class="section-anchor" href="#ss:custom-runtime" aria-hidden="true"></a>20.1.6  Building standalone custom runtime systems</h3><!--SEC END --><p>It is sometimes inconvenient to build a custom runtime system each
time OCaml code is linked with C libraries, like <span class="c003">ocamlc -custom</span> does.
For one thing, the building of the runtime system is slow on some
systems (that have bad linkers or slow remote file systems); for
another thing, the platform-independence of bytecode files is lost,
forcing to perform one <span class="c003">ocamlc -custom</span> link per platform of interest.</p><p>An alternative to <span class="c003">ocamlc -custom</span> is to build separately a custom
runtime system integrating the desired C libraries, then generate
“pure” bytecode executables (not containing their own runtime
system) that can run on this custom runtime. This is achieved by the
<span class="c003">-make-runtime</span> and <span class="c003">-use-runtime</span> flags to <span class="c003">ocamlc</span>. For example,
to build a custom runtime system integrating the C parts of the
“Unix” and “Threads” libraries, do:
</p><pre>        ocamlc -make-runtime -o /home/me/ocamlunixrun unix.cma threads.cma
</pre><p>To generate a bytecode executable that runs on this runtime system,
do:
</p><pre>
        ocamlc -use-runtime /home/me/ocamlunixrun -o myprog \
                unix.cma threads.cma <span class="c009">your .cmo and .cma files</span>
</pre><p>
The bytecode executable <span class="c003">myprog</span> can then be launched as usual:
<span class="c003">myprog</span> <span class="c009">args</span> or <span class="c003">/home/me/ocamlunixrun myprog</span> <span class="c009">args</span>.</p><p>Notice that the bytecode libraries <span class="c003">unix.cma</span> and <span class="c003">threads.cma</span> must
be given twice: when building the runtime system (so that <span class="c003">ocamlc</span>
knows which C primitives are required) and also when building the
bytecode executable (so that the bytecode from <span class="c003">unix.cma</span> and
<span class="c003">threads.cma</span> is actually linked in).</p>
<!--TOC section id="s:c-value" 20.2  The <span class="c003">value</span> type-->
<h2 class="section" id="s:c-value"><a class="section-anchor" href="#s:c-value" aria-hidden="true"></a>20.2  The <span class="c003">value</span> type</h2><!--SEC END --><p>All OCaml objects are represented by the C type <span class="c003">value</span>,
defined in the include file <span class="c003">caml/mlvalues.h</span>, along with macros to
manipulate values of that type. An object of type <span class="c003">value</span> is either:
</p><ul class="itemize"><li class="li-itemize">
an unboxed integer;
</li><li class="li-itemize">or a pointer to a block inside the heap,
allocated through one of the <code>caml_alloc_*</code> functions described
in section <a href="#ss%3Ac-block-allocation">20.4.4</a>.
</li></ul>
<!--TOC subsection id="ss:c-int" 20.2.1  Integer values-->
<h3 class="subsection" id="ss:c-int"><a class="section-anchor" href="#ss:c-int" aria-hidden="true"></a>20.2.1  Integer values</h3><!--SEC END --><p>Integer values encode 63-bit signed integers (31-bit on 32-bit
architectures). They are unboxed (unallocated).</p>
<!--TOC subsection id="ss:c-blocks" 20.2.2  Blocks-->
<h3 class="subsection" id="ss:c-blocks"><a class="section-anchor" href="#ss:c-blocks" aria-hidden="true"></a>20.2.2  Blocks</h3><!--SEC END --><p>Blocks in the heap are garbage-collected, and therefore have strict
structure constraints. Each block includes a header containing the
size of the block (in words), and the tag of the block.
The tag governs how the contents of the blocks are structured. A tag
lower than <span class="c003">No_scan_tag</span> indicates a structured block, containing
well-formed values, which is recursively traversed by the garbage
collector. A tag greater than or equal to <span class="c003">No_scan_tag</span> indicates a
raw block, whose contents are not scanned by the garbage collector.
For the benefit of ad-hoc polymorphic primitives such as equality and
structured input-output, structured and raw blocks are further
classified according to their tags as follows:
</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Tag</span></td><td class="c014"><span class="c013">Contents of the block</span> </td></tr>
<tr><td class="c022">
0 to <span class="c003">No_scan_tag</span>−1</td><td class="c021">A structured block (an array of
OCaml objects). Each field is a <span class="c003">value</span>. </td></tr>
<tr><td class="c022"><span class="c003">Closure_tag</span></td><td class="c021">A closure representing a functional value. The first
word is a pointer to a piece of code, the remaining words are
<span class="c003">value</span> containing the environment. </td></tr>
<tr><td class="c022"><span class="c003">String_tag</span></td><td class="c021">A character string or a byte sequence. </td></tr>
<tr><td class="c022"><span class="c003">Double_tag</span></td><td class="c021">A double-precision floating-point number. </td></tr>
<tr><td class="c022"><span class="c003">Double_array_tag</span></td><td class="c021">An array or record of double-precision
floating-point numbers. </td></tr>
<tr><td class="c022"><span class="c003">Abstract_tag</span></td><td class="c021">A block representing an abstract datatype. </td></tr>
<tr><td class="c022"><span class="c003">Custom_tag</span></td><td class="c021">A block representing an abstract datatype
with user-defined finalization, comparison, hashing,
serialization and deserialization functions attached. </td></tr>
</table></div></div>
<!--TOC subsection id="ss:c-outside-head" 20.2.3  Pointers outside the heap-->
<h3 class="subsection" id="ss:c-outside-head"><a class="section-anchor" href="#ss:c-outside-head" aria-hidden="true"></a>20.2.3  Pointers outside the heap</h3><!--SEC END --><p>In earlier versions of OCaml, it was possible to use
word-aligned pointers to addresses outside the heap as OCaml values,
just by casting the pointer to type <span class="c003">value</span>. Starting with OCaml
4.11, this usage is deprecated and will stop being supported in OCaml 5.00.</p><p>A correct way to manipulate pointers to out-of-heap blocks from
OCaml is to store those pointers in OCaml blocks with tag
<span class="c003">Abstract_tag</span> or <span class="c003">Custom_tag</span>, then use the blocks as the OCaml
values.</p><p>Here is an example of encapsulation of out-of-heap pointers of C type
<span class="c003">ty *</span> inside <span class="c003">Abstract_tag</span> blocks. Section <a href="#s%3Ac-intf-example">20.6</a>
gives a more complete example using <span class="c003">Custom_tag</span> blocks.
</p><pre>/* Create an OCaml value encapsulating the pointer p */
static value val_of_typtr(ty * p)
{
  value v = caml_alloc(1, Abstract_tag);
  *((ty **) Data_abstract_val(v)) = p;
  return v;
}

/* Extract the pointer encapsulated in the given OCaml value */
static ty * typtr_of_val(value v)
{
  return *((ty **) Data_abstract_val(v));
}
</pre><p>Alternatively, out-of-heap pointers can be treated as “native”
integers, that is, boxed 32-bit integers on a 32-bit platform and
boxed 64-bit integers on a 64-bit platform.
</p><pre>/* Create an OCaml value encapsulating the pointer p */
static value val_of_typtr(ty * p)
{
  return caml_copy_nativeint((intnat) p);
}

/* Extract the pointer encapsulated in the given OCaml value */
static ty * typtr_of_val(value v)
{
  return (ty *) Nativeint_val(v);
}
</pre><p>For pointers that are at least 2-aligned (the low bit is guaranteed to
be zero), we have yet another valid representation as an OCaml tagged
integer.
</p><pre>/* Create an OCaml value encapsulating the pointer p */
static value val_of_typtr(ty * p)
{
  assert (((uintptr_t) p &amp; 1) == 0);  /* check correct alignment */
  return (value) p | 1;
}

/* Extract the pointer encapsulated in the given OCaml value */
static ty * typtr_of_val(value v)
{
  return (ty *) (v &amp; ~1);
}
</pre>
<!--TOC section id="s:c-ocaml-datatype-repr" 20.3  Representation of OCaml data types-->
<h2 class="section" id="s:c-ocaml-datatype-repr"><a class="section-anchor" href="#s:c-ocaml-datatype-repr" aria-hidden="true"></a>20.3  Representation of OCaml data types</h2><!--SEC END --><p>This section describes how OCaml data types are encoded in the
<span class="c003">value</span> type.</p>
<!--TOC subsection id="ss:c-atomic" 20.3.1  Atomic types-->
<h3 class="subsection" id="ss:c-atomic"><a class="section-anchor" href="#ss:c-atomic" aria-hidden="true"></a>20.3.1  Atomic types</h3><!--SEC END --><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">OCaml type</span></td><td class="c014"><span class="c013">Encoding</span> </td></tr>
<tr><td class="c016">
<span class="c003">int</span></td><td class="c016">Unboxed integer values. </td></tr>
<tr><td class="c016"><span class="c003">char</span></td><td class="c016">Unboxed integer values (ASCII code). </td></tr>
<tr><td class="c016"><span class="c003">float</span></td><td class="c016">Blocks with tag <span class="c003">Double_tag</span>. </td></tr>
<tr><td class="c016"><span class="c003">bytes</span></td><td class="c016">Blocks with tag <span class="c003">String_tag</span>. </td></tr>
<tr><td class="c016"><span class="c003">string</span></td><td class="c016">Blocks with tag <span class="c003">String_tag</span>. </td></tr>
<tr><td class="c016"><span class="c003">int32</span></td><td class="c016">Blocks with tag <span class="c003">Custom_tag</span>. </td></tr>
<tr><td class="c016"><span class="c003">int64</span></td><td class="c016">Blocks with tag <span class="c003">Custom_tag</span>. </td></tr>
<tr><td class="c016"><span class="c003">nativeint</span></td><td class="c016">Blocks with tag <span class="c003">Custom_tag</span>. </td></tr>
</table></div></div>
<!--TOC subsection id="ss:c-tuples-and-records" 20.3.2  Tuples and records-->
<h3 class="subsection" id="ss:c-tuples-and-records"><a class="section-anchor" href="#ss:c-tuples-and-records" aria-hidden="true"></a>20.3.2  Tuples and records</h3><!--SEC END --><p>Tuples are represented by pointers to blocks, with tag 0.</p><p>Records are also represented by zero-tagged blocks. The ordering of
labels in the record type declaration determines the layout of
the record fields: the value associated to the label
declared first is stored in field 0 of the block, the value associated
to the second label goes in field 1, and so on.</p><p>As an optimization, records whose fields all have static type <span class="c003">float</span>
are represented as arrays of floating-point numbers, with tag
<span class="c003">Double_array_tag</span>. (See the section below on arrays.)</p><p>As another optimization, unboxable record types are represented
specially; unboxable record types are the immutable record types that
have only one field. An unboxable type will be represented in one of
two ways: boxed or unboxed. Boxed record types are represented as
described above (by a block with tag 0 or <span class="c003">Double_array_tag</span>). An
unboxed record type is represented directly by the value of its field
(i.e. there is no block to represent the record itself).</p><p>The representation is chosen according to the following, in decreasing
order of priority:
</p><ul class="itemize"><li class="li-itemize">
An attribute (<span class="c003">[@@boxed]</span> or <span class="c003">[@@unboxed]</span>) on the type declaration.
</li><li class="li-itemize">A compiler option (<span class="c003">-unboxed-types</span> or <span class="c003">-no-unboxed-types</span>).
</li><li class="li-itemize">The default representation. In the present version of OCaml, the
default is the boxed representation.
</li></ul>
<!--TOC subsection id="ss:c-arrays" 20.3.3  Arrays-->
<h3 class="subsection" id="ss:c-arrays"><a class="section-anchor" href="#ss:c-arrays" aria-hidden="true"></a>20.3.3  Arrays</h3><!--SEC END --><p>Arrays of integers and pointers are represented like tuples,
that is, as pointers to blocks tagged 0. They are accessed with the
<span class="c003">Field</span> macro for reading and the <span class="c003">caml_modify</span> function for writing.</p><p>Arrays of floating-point numbers (type <span class="c003">float array</span>)
have a special, unboxed, more efficient representation.
These arrays are represented by pointers to blocks with tag
<span class="c003">Double_array_tag</span>. They should be accessed with the <span class="c003">Double_field</span>
and <span class="c003">Store_double_field</span> macros.</p>
<!--TOC subsection id="ss:c-concrete-datatypes" 20.3.4  Concrete data types-->
<h3 class="subsection" id="ss:c-concrete-datatypes"><a class="section-anchor" href="#ss:c-concrete-datatypes" aria-hidden="true"></a>20.3.4  Concrete data types</h3><!--SEC END --><p>Constructed terms are represented either by unboxed integers (for
constant constructors) or by blocks whose tag encode the constructor
(for non-constant constructors). The constant constructors and the
non-constant constructors for a given concrete type are numbered
separately, starting from 0, in the order in which they appear in the
concrete type declaration. A constant constructor is represented by
the unboxed integer equal to its constructor number. A non-constant
constructor declared with <span class="c009">n</span> arguments is represented by
a block of size <span class="c009">n</span>, tagged with the constructor number; the <span class="c009">n</span>
fields contain its arguments. Example:</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Constructed term</span></td><td class="c014"><span class="c013">Representation</span> </td></tr>
<tr><td class="c022">
<span class="c003">()</span></td><td class="c021"><span class="c003">Val_int(0)</span> </td></tr>
<tr><td class="c022"><span class="c003">false</span></td><td class="c021"><span class="c003">Val_int(0)</span> </td></tr>
<tr><td class="c022"><span class="c003">true</span></td><td class="c021"><span class="c003">Val_int(1)</span> </td></tr>
<tr><td class="c022"><span class="c003">[]</span></td><td class="c021"><span class="c003">Val_int(0)</span> </td></tr>
<tr><td class="c022"><span class="c003">h::t</span></td><td class="c021">Block with size = 2 and tag = 0; first field
contains <span class="c003">h</span>, second field <span class="c003">t</span>. </td></tr>
</table></div></div><p>As a convenience, <span class="c003">caml/mlvalues.h</span> defines the macros <span class="c003">Val_unit</span>,
<span class="c003">Val_false</span> and <span class="c003">Val_true</span> to refer to <span class="c003">()</span>, <span class="c003">false</span> and <span class="c003">true</span>.</p><p>The following example illustrates the assignment of
integers and block tags to constructors:
</p><pre>type t =
  | A             (* First constant constructor -&gt; integer "Val_int(0)" *)
  | B of string   (* First non-constant constructor -&gt; block with tag 0 *)
  | C             (* Second constant constructor -&gt; integer "Val_int(1)" *)
  | D of bool     (* Second non-constant constructor -&gt; block with tag 1 *)
  | E of t * t    (* Third non-constant constructor -&gt; block with tag 2 *)
</pre><p>As an optimization, unboxable concrete data types are represented
specially; a concrete data type is unboxable if it has exactly one
constructor and this constructor has exactly one argument. Unboxable
concrete data types are represented in the same ways as unboxable
record types: see the description in
section <a href="#ss%3Ac-tuples-and-records">20.3.2</a>.</p>
<!--TOC subsection id="ss:c-objects" 20.3.5  Objects-->
<h3 class="subsection" id="ss:c-objects"><a class="section-anchor" href="#ss:c-objects" aria-hidden="true"></a>20.3.5  Objects</h3><!--SEC END --><p>Objects are represented as blocks with tag <span class="c003">Object_tag</span>. The first
field of the block refers to the object’s class and associated method
suite, in a format that cannot easily be exploited from C. The second
field contains a unique object ID, used for comparisons. The remaining
fields of the object contain the values of the instance variables of
the object. It is unsafe to access directly instance variables, as the
type system provides no guarantee about the instance variables
contained by an object.
</p><p>One may extract a public method from an object using the C function
<span class="c003">caml_get_public_method</span> (declared in <span class="c003">&lt;caml/mlvalues.h&gt;</span>.)
Since public method tags are hashed in the same way as variant tags,
and methods are functions taking self as first argument, if you want
to do the method call <span class="c003">foo#bar</span> from the C side, you should call:
</p><pre>  callback(caml_get_public_method(foo, hash_variant("bar")), foo);
</pre>
<!--TOC subsection id="ss:c-polyvar" 20.3.6  Polymorphic variants-->
<h3 class="subsection" id="ss:c-polyvar"><a class="section-anchor" href="#ss:c-polyvar" aria-hidden="true"></a>20.3.6  Polymorphic variants</h3><!--SEC END --><p>Like constructed terms, polymorphic variant values are represented either
as integers (for polymorphic variants without argument), or as blocks
(for polymorphic variants with an argument). Unlike constructed
terms, variant constructors are not numbered starting from 0, but
identified by a hash value (an OCaml integer), as computed by the C function
<span class="c003">hash_variant</span> (declared in <span class="c003">&lt;caml/mlvalues.h&gt;</span>):
the hash value for a variant constructor named, say, <span class="c003">VConstr</span>
is <span class="c003">hash_variant("VConstr")</span>.</p><p>The variant value <span class="c003">`VConstr</span> is represented by
<span class="c003">hash_variant("VConstr")</span>. The variant value <span class="c003">`VConstr(</span><span class="c009">v</span><span class="c003">)</span> is
represented by a block of size 2 and tag 0, with field number 0
containing <span class="c003">hash_variant("VConstr")</span> and field number 1 containing
<span class="c009">v</span>.</p><p>Unlike constructed values, polymorphic variant values taking several
arguments are not flattened.
That is, <span class="c003">`VConstr(</span><span class="c009">v</span><span class="c003">, </span><span class="c009">w</span><span class="c003">)</span> is represented by a block
of size 2, whose field number 1 contains the representation of the
pair <span class="c003">(</span><span class="c009">v</span><span class="c003">, </span><span class="c009">w</span><span class="c003">)</span>, rather than a block of size 3
containing <span class="c009">v</span> and <span class="c009">w</span> in fields 1 and 2.</p>
<!--TOC section id="s:c-ops-on-values" 20.4  Operations on values-->
<h2 class="section" id="s:c-ops-on-values"><a class="section-anchor" href="#s:c-ops-on-values" aria-hidden="true"></a>20.4  Operations on values</h2><!--SEC END -->
<!--TOC subsection id="ss:c-kind-tests" 20.4.1  Kind tests-->
<h3 class="subsection" id="ss:c-kind-tests"><a class="section-anchor" href="#ss:c-kind-tests" aria-hidden="true"></a>20.4.1  Kind tests</h3><!--SEC END --><ul class="itemize"><li class="li-itemize">
<span class="c003">Is_long(</span><span class="c009">v</span><span class="c003">)</span> is true if value <span class="c009">v</span> is an immediate integer,
false otherwise
</li><li class="li-itemize"><span class="c003">Is_block(</span><span class="c009">v</span><span class="c003">)</span> is true if value <span class="c009">v</span> is a pointer to a block,
and false if it is an immediate integer.
</li></ul>
<!--TOC subsection id="ss:c-int-ops" 20.4.2  Operations on integers-->
<h3 class="subsection" id="ss:c-int-ops"><a class="section-anchor" href="#ss:c-int-ops" aria-hidden="true"></a>20.4.2  Operations on integers</h3><!--SEC END --><ul class="itemize"><li class="li-itemize">
<span class="c003">Val_long(</span><span class="c009">l</span><span class="c003">)</span> returns the value encoding the <span class="c003">long int</span> <span class="c009">l</span>.
</li><li class="li-itemize"><span class="c003">Long_val(</span><span class="c009">v</span><span class="c003">)</span> returns the <span class="c003">long int</span> encoded in value <span class="c009">v</span>.
</li><li class="li-itemize"><span class="c003">Val_int(</span><span class="c009">i</span><span class="c003">)</span> returns the value encoding the <span class="c003">int</span> <span class="c009">i</span>.
</li><li class="li-itemize"><span class="c003">Int_val(</span><span class="c009">v</span><span class="c003">)</span> returns the <span class="c003">int</span> encoded in value <span class="c009">v</span>.
</li><li class="li-itemize"><span class="c003">Val_bool(</span><span class="c009">x</span><span class="c003">)</span> returns the OCaml boolean representing the
truth value of the C integer <span class="c009">x</span>.
</li><li class="li-itemize"><span class="c003">Bool_val(</span><span class="c009">v</span><span class="c003">)</span> returns 0 if <span class="c009">v</span> is the OCaml boolean
<span class="c003">false</span>, 1 if <span class="c009">v</span> is <span class="c003">true</span>.
</li><li class="li-itemize"><span class="c003">Val_true</span>, <span class="c003">Val_false</span> represent the OCaml booleans <span class="c003">true</span> and <span class="c003">false</span>.
</li></ul>
<!--TOC subsection id="ss:c-block-access" 20.4.3  Accessing blocks-->
<h3 class="subsection" id="ss:c-block-access"><a class="section-anchor" href="#ss:c-block-access" aria-hidden="true"></a>20.4.3  Accessing blocks</h3><!--SEC END --><ul class="itemize"><li class="li-itemize">
<span class="c003">Wosize_val(</span><span class="c009">v</span><span class="c003">)</span> returns the size of the block <span class="c009">v</span>, in words,
excluding the header.
</li><li class="li-itemize"><span class="c003">Tag_val(</span><span class="c009">v</span><span class="c003">)</span> returns the tag of the block <span class="c009">v</span>.
</li><li class="li-itemize"><span class="c003">Field(</span><span class="c009">v</span><span class="c003">, </span><span class="c009">n</span><span class="c003">)</span> returns the value contained in the
<span class="c009">n</span><sup><span class="c008">th</span></sup> field of the structured block <span class="c009">v</span>. Fields are numbered from 0 to
<span class="c003">Wosize_val</span>(<span class="c009">v</span>)−1.
</li><li class="li-itemize"><span class="c003">Store_field(</span><span class="c009">b</span><span class="c003">, </span><span class="c009">n</span><span class="c003">, </span><span class="c009">v</span><span class="c003">)</span> stores the value
<span class="c009">v</span> in the field number <span class="c009">n</span> of value <span class="c009">b</span>, which must be a
structured block.
</li><li class="li-itemize"><span class="c003">Code_val(</span><span class="c009">v</span><span class="c003">)</span> returns the code part of the closure <span class="c009">v</span>.
</li><li class="li-itemize"><span class="c003">caml_string_length(</span><span class="c009">v</span><span class="c003">)</span> returns the length (number of bytes)
of the string or byte sequence <span class="c009">v</span>.
</li><li class="li-itemize"><span class="c003">Byte(</span><span class="c009">v</span><span class="c003">, </span><span class="c009">n</span><span class="c003">)</span> returns the <span class="c009">n</span><sup><span class="c008">th</span></sup> byte of the string
or byte sequence <span class="c009">v</span>, with type <span class="c003">char</span>. Bytes are numbered from 0 to
<span class="c003">string_length</span>(<span class="c009">v</span>)−1.
</li><li class="li-itemize"><span class="c003">Byte_u(</span><span class="c009">v</span><span class="c003">, </span><span class="c009">n</span><span class="c003">)</span> returns the <span class="c009">n</span><sup><span class="c008">th</span></sup> byte of the string
or byte sequence <span class="c009">v</span>, with type <span class="c003">unsigned char</span>. Bytes are
numbered from 0 to <span class="c003">string_length</span>(<span class="c009">v</span>)−1.
</li><li class="li-itemize"><span class="c003">String_val(</span><span class="c009">v</span><span class="c003">)</span> returns a pointer to the first byte of the string
<span class="c009">v</span>, with type <span class="c003">char *</span> or, when OCaml is configured with
<span class="c003">-force-safe-string</span>, with type <span class="c003">const char *</span>.
This pointer is a valid C string: there is a null byte after the last
byte in the string. However, OCaml strings can contain embedded null bytes,
which will confuse the usual C functions over strings.
</li><li class="li-itemize"><span class="c003">Bytes_val(</span><span class="c009">v</span><span class="c003">)</span> returns a pointer to the first byte of the
byte sequence <span class="c009">v</span>, with type <span class="c003">unsigned char *</span>.
</li><li class="li-itemize"><span class="c003">Double_val(</span><span class="c009">v</span><span class="c003">)</span> returns the floating-point number contained in
value <span class="c009">v</span>, with type <span class="c003">double</span>.
</li><li class="li-itemize"><span class="c003">Double_field(</span><span class="c009">v</span><span class="c003">, </span><span class="c009">n</span><span class="c003">)</span> returns
the <span class="c009">n</span><sup><span class="c008">th</span></sup> element of the array of floating-point numbers <span class="c009">v</span> (a
block tagged <span class="c003">Double_array_tag</span>).
</li><li class="li-itemize"><span class="c003">Store_double_field(</span><span class="c009">v</span><span class="c003">, </span><span class="c009">n</span><span class="c003">, </span><span class="c009">d</span><span class="c003">)</span> stores the double precision floating-point number <span class="c009">d</span>
in the <span class="c009">n</span><sup><span class="c008">th</span></sup> element of the array of floating-point numbers <span class="c009">v</span>.
</li><li class="li-itemize"><span class="c003">Data_custom_val(</span><span class="c009">v</span><span class="c003">)</span> returns a pointer to the data part
of the custom block <span class="c009">v</span>. This pointer has type <span class="c003">void *</span> and must
be cast to the type of the data contained in the custom block.
</li><li class="li-itemize"><span class="c003">Int32_val(</span><span class="c009">v</span><span class="c003">)</span> returns the 32-bit integer contained
in the <span class="c003">int32</span> <span class="c009">v</span>.
</li><li class="li-itemize"><span class="c003">Int64_val(</span><span class="c009">v</span><span class="c003">)</span> returns the 64-bit integer contained
in the <span class="c003">int64</span> <span class="c009">v</span>.
</li><li class="li-itemize"><span class="c003">Nativeint_val(</span><span class="c009">v</span><span class="c003">)</span> returns the long integer contained
in the <span class="c003">nativeint</span> <span class="c009">v</span>.
</li><li class="li-itemize"><span class="c003">caml_field_unboxed(</span><span class="c009">v</span><span class="c003">)</span> returns the value of the field
of a value <span class="c009">v</span> of any unboxed type (record or concrete data type).
</li><li class="li-itemize"><span class="c003">caml_field_boxed(</span><span class="c009">v</span><span class="c003">)</span> returns the value of the field
of a value <span class="c009">v</span> of any boxed type (record or concrete data type).
</li><li class="li-itemize"><span class="c003">caml_field_unboxable(</span><span class="c009">v</span><span class="c003">)</span> calls either
<span class="c003">caml_field_unboxed</span> or <span class="c003">caml_field_boxed</span> according to the default
representation of unboxable types in the current version of OCaml.
</li></ul><p>
The expressions <span class="c003">Field(</span><span class="c009">v</span><span class="c003">, </span><span class="c009">n</span><span class="c003">)</span>,
<span class="c003">Byte(</span><span class="c009">v</span><span class="c003">, </span><span class="c009">n</span><span class="c003">)</span> and
<span class="c003">Byte_u(</span><span class="c009">v</span><span class="c003">, </span><span class="c009">n</span><span class="c003">)</span>
are valid l-values. Hence, they can be assigned to, resulting in an
in-place modification of value <span class="c009">v</span>.
Assigning directly to <span class="c003">Field(</span><span class="c009">v</span><span class="c003">, </span><span class="c009">n</span><span class="c003">)</span> must
be done with care to avoid confusing the garbage collector (see
below).</p>
<!--TOC subsection id="ss:c-block-allocation" 20.4.4  Allocating blocks-->
<h3 class="subsection" id="ss:c-block-allocation"><a class="section-anchor" href="#ss:c-block-allocation" aria-hidden="true"></a>20.4.4  Allocating blocks</h3><!--SEC END -->
<!--TOC subsubsection id="sss:c-simple-allocation" Simple interface-->
<h4 class="subsubsection" id="sss:c-simple-allocation"><a class="section-anchor" href="#sss:c-simple-allocation" aria-hidden="true"></a>Simple interface</h4><!--SEC END --><ul class="itemize"><li class="li-itemize">
<span class="c003">Atom(</span><span class="c009">t</span><span class="c003">)</span> returns an “atom” (zero-sized block) with tag <span class="c009">t</span>.
Zero-sized blocks are preallocated outside of the heap. It is
incorrect to try and allocate a zero-sized block using the functions below.
For instance, <span class="c003">Atom(0)</span> represents the empty array.
</li><li class="li-itemize"><span class="c003">caml_alloc(</span><span class="c009">n</span><span class="c003">, </span><span class="c009">t</span><span class="c003">)</span> returns a fresh block of size <span class="c009">n</span>
with tag <span class="c009">t</span>. If <span class="c009">t</span> is less than <span class="c003">No_scan_tag</span>, then the
fields of the block are initialized with a valid value in order to
satisfy the GC constraints.
</li><li class="li-itemize"><span class="c003">caml_alloc_tuple(</span><span class="c009">n</span><span class="c003">)</span> returns a fresh block of size
<span class="c009">n</span> words, with tag 0.
</li><li class="li-itemize"><span class="c003">caml_alloc_string(</span><span class="c009">n</span><span class="c003">)</span> returns a byte sequence (or string) value of
length <span class="c009">n</span> bytes. The sequence initially contains uninitialized bytes.
</li><li class="li-itemize"><span class="c003">caml_alloc_initialized_string(</span><span class="c009">n</span><span class="c003">, </span><span class="c009">p</span><span class="c003">)</span> returns a byte sequence
(or string) value of length <span class="c009">n</span> bytes. The value is initialized from the
<span class="c009">n</span> bytes starting at address <span class="c009">p</span>.
</li><li class="li-itemize"><span class="c003">caml_copy_string(</span><span class="c009">s</span><span class="c003">)</span> returns a string or byte sequence value
containing a copy of the null-terminated C string <span class="c009">s</span> (a <span class="c003">char *</span>).
</li><li class="li-itemize"><span class="c003">caml_copy_double(</span><span class="c009">d</span><span class="c003">)</span> returns a floating-point value initialized
with the <span class="c003">double</span> <span class="c009">d</span>.
</li><li class="li-itemize"><span class="c003">caml_copy_int32(</span><span class="c009">i</span><span class="c003">)</span>, <span class="c003">caml_copy_int64(</span><span class="c009">i</span><span class="c003">)</span> and
<span class="c003">caml_copy_nativeint(</span><span class="c009">i</span><span class="c003">)</span> return a value of OCaml type <span class="c003">int32</span>,
<span class="c003">int64</span> and <span class="c003">nativeint</span>, respectively, initialized with the integer
<span class="c009">i</span>.
</li><li class="li-itemize"><span class="c003">caml_alloc_array(</span><span class="c009">f</span><span class="c003">, </span><span class="c009">a</span><span class="c003">)</span> allocates an array of values, calling
function <span class="c009">f</span> over each element of the input array <span class="c009">a</span> to transform it
into a value. The array <span class="c009">a</span> is an array of pointers terminated by the
null pointer. The function <span class="c009">f</span> receives each pointer as argument, and
returns a value. The zero-tagged block returned by
<span class="c003">alloc_array(</span><span class="c009">f</span><span class="c003">, </span><span class="c009">a</span><span class="c003">)</span> is filled with the values returned by the
successive calls to <span class="c009">f</span>. (This function must not be used to build
an array of floating-point numbers.)
</li><li class="li-itemize"><span class="c003">caml_copy_string_array(</span><span class="c009">p</span><span class="c003">)</span> allocates an array of strings or byte
sequences, copied from the pointer to a string array <span class="c009">p</span>
(a <span class="c003">char **</span>). <span class="c009">p</span> must be NULL-terminated.
</li><li class="li-itemize"><span class="c003">caml_alloc_float_array(</span><span class="c009">n</span><span class="c003">)</span> allocates an array of floating point
numbers of size <span class="c009">n</span>. The array initially contains uninitialized values.
</li><li class="li-itemize"><span class="c003">caml_alloc_unboxed(</span><span class="c009">v</span><span class="c003">)</span> returns the value (of any unboxed
type) whose field is the value <span class="c009">v</span>.
</li><li class="li-itemize"><span class="c003">caml_alloc_boxed(</span><span class="c009">v</span><span class="c003">)</span> allocates and returns a value (of
any boxed type) whose field is the value <span class="c009">v</span>.
</li><li class="li-itemize"><span class="c003">caml_alloc_unboxable(</span><span class="c009">v</span><span class="c003">)</span> calls either
<span class="c003">caml_alloc_unboxed</span> or <span class="c003">caml_alloc_boxed</span> according to the default
representation of unboxable types in the current version of OCaml.
</li></ul>
<!--TOC subsubsection id="sss:c-low-level-alloc" Low-level interface-->
<h4 class="subsubsection" id="sss:c-low-level-alloc"><a class="section-anchor" href="#sss:c-low-level-alloc" aria-hidden="true"></a>Low-level interface</h4><!--SEC END --><p>The following functions are slightly more efficient than <span class="c003">caml_alloc</span>, but
also much more difficult to use.</p><p>From the standpoint of the allocation functions, blocks are divided
according to their size as zero-sized blocks, small blocks (with size
less than or equal to <code>Max_young_wosize</code>), and large blocks (with
size greater than <code>Max_young_wosize</code>). The constant
<code>Max_young_wosize</code> is declared in the include file <span class="c003">mlvalues.h</span>. It
is guaranteed to be at least 64 (words), so that any block with
constant size less than or equal to 64 can be assumed to be small. For
blocks whose size is computed at run-time, the size must be compared
against <code>Max_young_wosize</code> to determine the correct allocation procedure.</p><ul class="itemize"><li class="li-itemize">
<span class="c003">caml_alloc_small(</span><span class="c009">n</span><span class="c003">, </span><span class="c009">t</span><span class="c003">)</span> returns a fresh small block of size
<span class="c009">n</span> ≤ <span class="c003">Max_young_wosize</span> words, with tag <span class="c009">t</span>.
If this block is a structured block (i.e. if <span class="c009">t</span> &lt; <span class="c003">No_scan_tag</span>), then
the fields of the block (initially containing garbage) must be initialized
with legal values (using direct assignment to the fields of the block)
before the next allocation.
</li><li class="li-itemize"><span class="c003">caml_alloc_shr(</span><span class="c009">n</span><span class="c003">, </span><span class="c009">t</span><span class="c003">)</span> returns a fresh block of size
<span class="c009">n</span>, with tag <span class="c009">t</span>.
The size of the block can be greater than <code>Max_young_wosize</code>. (It
can also be smaller, but in this case it is more efficient to call
<span class="c003">caml_alloc_small</span> instead of <span class="c003">caml_alloc_shr</span>.)
If this block is a structured block (i.e. if <span class="c009">t</span> &lt; <span class="c003">No_scan_tag</span>), then
the fields of the block (initially containing garbage) must be initialized
with legal values (using the <span class="c003">caml_initialize</span> function described below)
before the next allocation.
</li></ul>
<!--TOC subsection id="ss:c-exceptions" 20.4.5  Raising exceptions-->
<h3 class="subsection" id="ss:c-exceptions"><a class="section-anchor" href="#ss:c-exceptions" aria-hidden="true"></a>20.4.5  Raising exceptions</h3><!--SEC END --><p>Two functions are provided to raise two standard exceptions:
</p><ul class="itemize"><li class="li-itemize">
<span class="c003">caml_failwith(</span><span class="c009">s</span><span class="c003">)</span>, where <span class="c009">s</span> is a null-terminated C string (with
type <code>char *</code>), raises exception <span class="c003">Failure</span> with argument <span class="c009">s</span>.
</li><li class="li-itemize"><span class="c003">caml_invalid_argument(</span><span class="c009">s</span><span class="c003">)</span>, where <span class="c009">s</span> is a null-terminated C
string (with type <code>char *</code>), raises exception <span class="c003">Invalid_argument</span>
with argument <span class="c009">s</span>.
</li></ul><p>Raising arbitrary exceptions from C is more delicate: the
exception identifier is dynamically allocated by the OCaml program, and
therefore must be communicated to the C function using the
registration facility described below in section <a href="#ss%3Ac-register-exn">20.7.3</a>.
Once the exception identifier is recovered in C, the following
functions actually raise the exception:
</p><ul class="itemize"><li class="li-itemize">
<span class="c003">caml_raise_constant(</span><span class="c009">id</span><span class="c003">)</span> raises the exception <span class="c009">id</span> with
no argument;
</li><li class="li-itemize"><span class="c003">caml_raise_with_arg(</span><span class="c009">id</span><span class="c003">, </span><span class="c009">v</span><span class="c003">)</span> raises the exception
<span class="c009">id</span> with the OCaml value <span class="c009">v</span> as argument;
</li><li class="li-itemize"><span class="c003">caml_raise_with_args(</span><span class="c009">id</span><span class="c003">, </span><span class="c009">n</span><span class="c003">, </span><span class="c009">v</span><span class="c003">)</span>
raises the exception <span class="c009">id</span> with the OCaml values
<span class="c009">v</span><span class="c003">[0]</span>, …, <span class="c009">v</span><span class="c003">[</span><span class="c009">n</span><span class="c003">-1]</span> as arguments;
</li><li class="li-itemize"><span class="c003">caml_raise_with_string(</span><span class="c009">id</span><span class="c003">, </span><span class="c009">s</span><span class="c003">)</span>, where <span class="c009">s</span> is a
null-terminated C string, raises the exception <span class="c009">id</span> with a copy of
the C string <span class="c009">s</span> as argument.
</li></ul>
<!--TOC section id="s:c-gc-harmony" 20.5  Living in harmony with the garbage collector-->
<h2 class="section" id="s:c-gc-harmony"><a class="section-anchor" href="#s:c-gc-harmony" aria-hidden="true"></a>20.5  Living in harmony with the garbage collector</h2><!--SEC END --><p>Unused blocks in the heap are automatically reclaimed by the garbage
collector. This requires some cooperation from C code that
manipulates heap-allocated blocks.</p>
<!--TOC subsection id="ss:c-simple-gc-harmony" 20.5.1  Simple interface-->
<h3 class="subsection" id="ss:c-simple-gc-harmony"><a class="section-anchor" href="#ss:c-simple-gc-harmony" aria-hidden="true"></a>20.5.1  Simple interface</h3><!--SEC END --><p>All the macros described in this section are declared in the
<span class="c003">memory.h</span> header file.</p><div class="theorem"><span class="c013">Rule 1</span>  <em>
A function that has parameters or local variables of type <span class="c003">value</span> must
begin with a call to one of the <span class="c003">CAMLparam</span> macros and return with
<span class="c003">CAMLreturn</span>, <span class="c003">CAMLreturn0</span>, or <span class="c003">CAMLreturnT</span>. In particular, <span class="c003">CAMLlocal</span>
and <span class="c003">CAMLxparam</span> can only be called </em>after <em><span class="c003">CAMLparam</span>.
</em></div><p>There are six <span class="c003">CAMLparam</span> macros: <span class="c003">CAMLparam0</span> to <span class="c003">CAMLparam5</span>, which
take zero to five arguments respectively. If your function has no more
than 5 parameters of type <span class="c003">value</span>, use the corresponding macros
with these parameters as arguments. If your function has more than 5
parameters of type <span class="c003">value</span>, use <span class="c003">CAMLparam5</span> with five of these
parameters, and use one or more calls to the <span class="c003">CAMLxparam</span> macros for
the remaining parameters (<span class="c003">CAMLxparam1</span> to <span class="c003">CAMLxparam5</span>).</p><p>The macros <span class="c003">CAMLreturn</span>, <span class="c003">CAMLreturn0</span>, and <span class="c003">CAMLreturnT</span> are used to
replace the C
keyword <span class="c003">return</span>. Every occurrence of <span class="c003">return x</span> must be replaced by
<span class="c003">CAMLreturn (x)</span> if <span class="c003">x</span> has type <span class="c003">value</span>, or <span class="c003">CAMLreturnT (t, x)</span>
(where <span class="c003">t</span> is the type of <span class="c003">x</span>); every occurrence of <span class="c003">return</span> without
argument must be
replaced by <span class="c003">CAMLreturn0</span>. If your C function is a procedure (i.e. if
it returns void), you must insert <span class="c003">CAMLreturn0</span> at the end (to replace
C’s implicit <span class="c003">return</span>).</p>
<!--TOC paragraph id="sec451" Note:-->
<h5 class="paragraph" id="sec451"><a class="section-anchor" href="#sec451" aria-hidden="true"></a>Note:</h5><!--SEC END --><p> some C compilers give bogus warnings about unused
variables <span class="c003">caml__dummy_xxx</span> at each use of <span class="c003">CAMLparam</span> and
<span class="c003">CAMLlocal</span>. You should ignore them.</p><p> <br>
</p><p>Example:
</p><pre>void foo (value v1, value v2, value v3)
{
  CAMLparam3 (v1, v2, v3);
  ...
  CAMLreturn0;
}
</pre>
<!--TOC paragraph id="sec452" Note:-->
<h5 class="paragraph" id="sec452"><a class="section-anchor" href="#sec452" aria-hidden="true"></a>Note:</h5><!--SEC END --><p> if your function is a primitive with more than 5 arguments
for use with the byte-code runtime, its arguments are not <span class="c003">value</span>s and
must not be declared (they have types <span class="c003">value *</span> and <span class="c003">int</span>).</p><div class="theorem"><span class="c013">Rule 2</span>  <em>
Local variables of type <span class="c003">value</span> must be declared with one of the
<span class="c003">CAMLlocal</span> macros. Arrays of <span class="c003">value</span>s are declared with
<span class="c003">CAMLlocalN</span>. These macros must be used at the beginning of the
function, not in a nested block.
</em></div><p>The macros <span class="c003">CAMLlocal1</span> to <span class="c003">CAMLlocal5</span> declare and initialize one to
five local variables of type <span class="c003">value</span>. The variable names are given as
arguments to the macros. <span class="c003">CAMLlocalN(</span><span class="c009">x</span><span class="c003">, </span><span class="c009">n</span><span class="c003">)</span> declares
and initializes a local variable of type <span class="c003">value [</span><span class="c009">n</span><span class="c003">]</span>. You can
use several calls to these macros if you have more than 5 local
variables.</p><p>Example:
</p><pre>value bar (value v1, value v2, value v3)
{
  CAMLparam3 (v1, v2, v3);
  CAMLlocal1 (result);
  result = caml_alloc (3, 0);
  ...
  CAMLreturn (result);
}
</pre><div class="theorem"><span class="c013">Rule 3</span>  <em>
Assignments to the fields of structured blocks must be done with the
<span class="c003">Store_field</span> macro (for normal blocks) or <span class="c003">Store_double_field</span> macro
(for arrays and records of floating-point numbers). Other assignments
must not use <span class="c003">Store_field</span> nor <span class="c003">Store_double_field</span>.
</em></div><p><span class="c003">Store_field (</span><span class="c009">b</span><span class="c003">, </span><span class="c009">n</span><span class="c003">, </span><span class="c009">v</span><span class="c003">)</span> stores the value
<span class="c009">v</span> in the field number <span class="c009">n</span> of value <span class="c009">b</span>, which must be a
block (i.e. <span class="c003">Is_block(</span><span class="c009">b</span><span class="c003">)</span> must be true).</p><p>Example:
</p><pre>value bar (value v1, value v2, value v3)
{
  CAMLparam3 (v1, v2, v3);
  CAMLlocal1 (result);
  result = caml_alloc (3, 0);
  Store_field (result, 0, v1);
  Store_field (result, 1, v2);
  Store_field (result, 2, v3);
  CAMLreturn (result);
}
</pre>
<!--TOC paragraph id="sec453" Warning:-->
<h5 class="paragraph" id="sec453"><a class="section-anchor" href="#sec453" aria-hidden="true"></a>Warning:</h5><!--SEC END --><p> The first argument of <span class="c003">Store_field</span> and
<span class="c003">Store_double_field</span> must be a variable declared by <span class="c003">CAMLparam*</span> or
a parameter declared by <span class="c003">CAMLlocal*</span> to ensure that a garbage
collection triggered by the evaluation of the other arguments will not
invalidate the first argument after it is computed.</p>
<!--TOC paragraph id="sec454" Use with CAMLlocalN:-->
<h5 class="paragraph" id="sec454"><a class="section-anchor" href="#sec454" aria-hidden="true"></a>Use with CAMLlocalN:</h5><!--SEC END --><p> Arrays of values declared using
<span class="c003">CAMLlocalN</span> must not be written to using <span class="c003">Store_field</span>.
Use the normal C array syntax instead.</p><div class="theorem"><span class="c013">Rule 4</span>  <em> Global variables containing values must be registered
with the garbage collector using the <span class="c003">caml_register_global_root</span> function,
save that global variables and locations that will only ever contain OCaml
integers (and never pointers) do not have to be registered.</em><p><em>The same is true for any memory location outside the OCaml heap that contains a
value and is not guaranteed to be reachable—for as long as it contains such
value—from either another registered global variable or location, local
variable declared with <span class="c003">CAMLlocal</span> or function parameter declared with
<span class="c003">CAMLparam</span>.
</em></p></div><p>Registration of a global variable <span class="c003">v</span> is achieved by calling
<span class="c003">caml_register_global_root(&amp;v)</span> just before or just after a valid value is
stored in <span class="c003">v</span> for the first time; likewise, registration of an arbitrary
location <span class="c003">p</span> is achieved by calling <span class="c003">caml_register_global_root(p)</span>.</p><p>You must not call any of the OCaml runtime functions or macros between
registering and storing the value. Neither must you store anything in the
variable <span class="c003">v</span> (likewise, the location <span class="c003">p</span>) that is not a valid value.</p><p>The registration causes the contents of the variable or memory location to be
updated by the garbage collector whenever the value in such variable or location
is moved within the OCaml heap. In the presence of threads care must be taken to
ensure appropriate synchronisation with the OCaml runtime to avoid a race
condition against the garbage collector when reading or writing the value. (See
section
<a href="#ss%3Aparallel-execution-long-running-c-code">20.12.2</a>.)</p><p>A registered global variable <span class="c003">v</span> can be un-registered by calling
<span class="c003">caml_remove_global_root(&amp;v)</span>.</p><p>If the contents of the global variable <span class="c003">v</span> are seldom modified after
registration, better performance can be achieved by calling
<span class="c003">caml_register_generational_global_root(&amp;v)</span> to register <span class="c003">v</span> (after
its initialization with a valid <span class="c003">value</span>, but before any allocation or
call to the GC functions),
and <span class="c003">caml_remove_generational_global_root(&amp;v)</span> to un-register it. In
this case, you must not modify the value of <span class="c003">v</span> directly, but you must
use <span class="c003">caml_modify_generational_global_root(&amp;v,x)</span> to set it to <span class="c003">x</span>.
The garbage collector takes advantage of the guarantee that <span class="c003">v</span> is not
modified between calls to <span class="c003">caml_modify_generational_global_root</span> to scan it
less often. This improves performance if the
modifications of <span class="c003">v</span> happen less often than minor collections.</p>
<!--TOC paragraph id="sec455" Note:-->
<h5 class="paragraph" id="sec455"><a class="section-anchor" href="#sec455" aria-hidden="true"></a>Note:</h5><!--SEC END --><p> The <span class="c003">CAML</span> macros use identifiers (local variables, type
identifiers, structure tags) that start with <span class="c003">caml__</span>. Do not use any
identifier starting with <span class="c003">caml__</span> in your programs.</p>
<!--TOC subsection id="ss:c-low-level-gc-harmony" 20.5.2  Low-level interface-->
<h3 class="subsection" id="ss:c-low-level-gc-harmony"><a class="section-anchor" href="#ss:c-low-level-gc-harmony" aria-hidden="true"></a>20.5.2  Low-level interface</h3><!--SEC END --><p>We now give the GC rules corresponding to the low-level allocation
functions <span class="c003">caml_alloc_small</span> and <span class="c003">caml_alloc_shr</span>. You can ignore those rules
if you stick to the simplified allocation function <span class="c003">caml_alloc</span>.</p><div class="theorem"><span class="c013">Rule 5</span>  <em> After a structured block (a block with tag less than
<span class="c003">No_scan_tag</span>) is allocated with the low-level functions, all fields
of this block must be filled with well-formed values before the next
allocation operation. If the block has been allocated with
<span class="c003">caml_alloc_small</span>, filling is performed by direct assignment to the fields
of the block:
</em><pre><em>
        Field(<span class="c009">v</span>, <span class="c009">n</span>) = </em><span class="c009">v</span><sub><span class="c009">n</span></sub><em>;
</em></pre><em>
If the block has been allocated with <span class="c003">caml_alloc_shr</span>, filling is performed
through the <span class="c003">caml_initialize</span> function:
</em><pre><em>
        caml_initialize(&amp;Field(<span class="c009">v</span>, <span class="c009">n</span>), </em><span class="c009">v</span><sub><span class="c009">n</span></sub><em>);
</em></pre>
</div><p>The next allocation can trigger a garbage collection. The garbage
collector assumes that all structured blocks contain well-formed
values. Newly created blocks contain random data, which generally do
not represent well-formed values.</p><p>If you really need to allocate before the fields can receive their
final value, first initialize with a constant value (e.g.
<span class="c003">Val_unit</span>), then allocate, then modify the fields with the correct
value (see rule 6).</p><div class="theorem"><span class="c013">Rule 6</span>  <em> Direct assignment to a field of a block, as in
</em><pre><em>
        Field(<span class="c009">v</span>, <span class="c009">n</span>) = <span class="c009">w</span>;
</em></pre><em>
is safe only if <span class="c009">v</span> is a block newly allocated by <span class="c003">caml_alloc_small</span>;
that is, if no allocation took place between the
allocation of <span class="c009">v</span> and the assignment to the field. In all other cases,
never assign directly. If the block has just been allocated by <span class="c003">caml_alloc_shr</span>,
use <span class="c003">caml_initialize</span> to assign a value to a field for the first time:
</em><pre><em>
        caml_initialize(&amp;Field(<span class="c009">v</span>, <span class="c009">n</span>), <span class="c009">w</span>);
</em></pre><em>
Otherwise, you are updating a field that previously contained a
well-formed value; then, call the <span class="c003">caml_modify</span> function:
</em><pre><em>
        caml_modify(&amp;Field(<span class="c009">v</span>, <span class="c009">n</span>), <span class="c009">w</span>);
</em></pre>
</div><p>To illustrate the rules above, here is a C function that builds and
returns a list containing the two integers given as parameters.
First, we write it using the simplified allocation functions:
</p><pre>value alloc_list_int(int i1, int i2)
{
  CAMLparam0 ();
  CAMLlocal2 (result, r);

  r = caml_alloc(2, 0);                   /* Allocate a cons cell */
  Store_field(r, 0, Val_int(i2));         /* car = the integer i2 */
  Store_field(r, 1, Val_int(0));          /* cdr = the empty list [] */
  result = caml_alloc(2, 0);              /* Allocate the other cons cell */
  Store_field(result, 0, Val_int(i1));    /* car = the integer i1 */
  Store_field(result, 1, r);              /* cdr = the first cons cell */
  CAMLreturn (result);
}
</pre><p>Here, the registering of <span class="c003">result</span> is not strictly needed, because no
allocation takes place after it gets its value, but it’s easier and
safer to simply register all the local variables that have type <span class="c003">value</span>.</p><p>Here is the same function written using the low-level allocation
functions. We notice that the cons cells are small blocks and can be
allocated with <span class="c003">caml_alloc_small</span>, and filled by direct assignments on
their fields.
</p><pre>value alloc_list_int(int i1, int i2)
{
  CAMLparam0 ();
  CAMLlocal2 (result, r);

  r = caml_alloc_small(2, 0);             /* Allocate a cons cell */
  Field(r, 0) = Val_int(i2);              /* car = the integer i2 */
  Field(r, 1) = Val_int(0);               /* cdr = the empty list [] */
  result = caml_alloc_small(2, 0);        /* Allocate the other cons cell */
  Field(result, 0) = Val_int(i1);         /* car = the integer i1 */
  Field(result, 1) = r;                   /* cdr = the first cons cell */
  CAMLreturn (result);
}
</pre><p>In the two examples above, the list is built bottom-up. Here is an
alternate way, that proceeds top-down. It is less efficient, but
illustrates the use of <span class="c003">caml_modify</span>.
</p><pre>value alloc_list_int(int i1, int i2)
{
  CAMLparam0 ();
  CAMLlocal2 (tail, r);

  r = caml_alloc_small(2, 0);             /* Allocate a cons cell */
  Field(r, 0) = Val_int(i1);              /* car = the integer i1 */
  Field(r, 1) = Val_int(0);               /* A dummy value
  tail = caml_alloc_small(2, 0);          /* Allocate the other cons cell */
  Field(tail, 0) = Val_int(i2);           /* car = the integer i2 */
  Field(tail, 1) = Val_int(0);            /* cdr = the empty list [] */
  caml_modify(&amp;Field(r, 1), tail);        /* cdr of the result = tail */
  CAMLreturn (r);
}
</pre><p>It would be incorrect to perform
<span class="c003">Field(r, 1) = tail</span> directly, because the allocation of <span class="c003">tail</span>
has taken place since <span class="c003">r</span> was allocated.</p>
<!--TOC subsection id="ss:c-process-pending-actions" 20.5.3  Pending actions and asynchronous exceptions-->
<h3 class="subsection" id="ss:c-process-pending-actions"><a class="section-anchor" href="#ss:c-process-pending-actions" aria-hidden="true"></a>20.5.3  Pending actions and asynchronous exceptions</h3><!--SEC END --><p>Since 4.10, allocation functions are guaranteed not to call any OCaml
callbacks from C, including finalisers and signal handlers, and delay
their execution instead.</p><p>The function <code>caml_process_pending_actions</code> from
<span class="c003">&lt;caml/signals.h&gt;</span> executes any pending signal handlers and
finalisers, Memprof callbacks, and requested minor and major garbage
collections. In particular, it can raise asynchronous exceptions. It
is recommended to call it regularly at safe points inside long-running
non-blocking C code.</p><p>The variant <code>caml_process_pending_actions_exn</code> is provided, that
returns the exception instead of raising it directly into OCaml code.
Its result must be tested using <span class="c003">Is_exception_result</span>, and
followed by <span class="c003">Extract_exception</span> if appropriate. It is typically
used for clean up before re-raising:</p><pre>    CAMLlocal1(exn);
    ...
    exn = caml_process_pending_actions_exn();
    if(Is_exception_result(exn)) {
      exn = Extract_exception(exn);
      ...cleanup...
      caml_raise(exn);
    }
</pre><p>
Correct use of exceptional return, in particular in the presence of
garbage collection, is further detailed in Section <a href="#ss%3Ac-callbacks">20.7.1</a>.</p>
<!--TOC section id="s:c-intf-example" 20.6  A complete example-->
<h2 class="section" id="s:c-intf-example"><a class="section-anchor" href="#s:c-intf-example" aria-hidden="true"></a>20.6  A complete example</h2><!--SEC END --><p>This section outlines how the functions from the Unix <span class="c003">curses</span> library
can be made available to OCaml programs. First of all, here is
the interface <span class="c003">curses.ml</span> that declares the <span class="c003">curses</span> primitives and
data types:
</p><pre>(* File curses.ml -- declaration of primitives and data types *)
type window                   (* The type "window" remains abstract *)
external initscr: unit -&gt; window = "caml_curses_initscr"
external endwin: unit -&gt; unit = "caml_curses_endwin"
external refresh: unit -&gt; unit = "caml_curses_refresh"
external wrefresh : window -&gt; unit = "caml_curses_wrefresh"
external newwin: int -&gt; int -&gt; int -&gt; int -&gt; window = "caml_curses_newwin"
external addch: char -&gt; unit = "caml_curses_addch"
external mvwaddch: window -&gt; int -&gt; int -&gt; char -&gt; unit = "caml_curses_mvwaddch"
external addstr: string -&gt; unit = "caml_curses_addstr"
external mvwaddstr: window -&gt; int -&gt; int -&gt; string -&gt; unit
         = "caml_curses_mvwaddstr"
(* lots more omitted *)
</pre><p>To compile this interface:
</p><pre>        ocamlc -c curses.ml
</pre><p>
To implement these functions, we just have to provide the stub code;
the core functions are already implemented in the <span class="c003">curses</span> library.
The stub code file, <span class="c003">curses_stubs.c</span>, looks like this:
</p><pre>/* File curses_stubs.c -- stub code for curses */
#include &lt;curses.h&gt;
#define CAML_NAME_SPACE
#include &lt;caml/mlvalues.h&gt;
#include &lt;caml/memory.h&gt;
#include &lt;caml/alloc.h&gt;
#include &lt;caml/custom.h&gt;

/* Encapsulation of opaque window handles (of type WINDOW *)
   as OCaml custom blocks. */

static struct custom_operations curses_window_ops = {
  "fr.inria.caml.curses_windows",
  custom_finalize_default,
  custom_compare_default,
  custom_hash_default,
  custom_serialize_default,
  custom_deserialize_default,
  custom_compare_ext_default,
  custom_fixed_length_default
};

/* Accessing the WINDOW * part of an OCaml custom block */
#define Window_val(v) (*((WINDOW **) Data_custom_val(v)))

/* Allocating an OCaml custom block to hold the given WINDOW * */
static value alloc_window(WINDOW * w)
{
  value v = caml_alloc_custom(&amp;curses_window_ops, sizeof(WINDOW *), 0, 1);
  Window_val(v) = w;
  return v;
}

value caml_curses_initscr(value unit)
{
  CAMLparam1 (unit);
  CAMLreturn (alloc_window(initscr()));
}

value caml_curses_endwin(value unit)
{
  CAMLparam1 (unit);
  endwin();
  CAMLreturn (Val_unit);
}

value caml_curses_refresh(value unit)
{
  CAMLparam1 (unit);
  refresh();
  CAMLreturn (Val_unit);
}

value caml_curses_wrefresh(value win)
{
  CAMLparam1 (win);
  wrefresh(Window_val(win));
  CAMLreturn (Val_unit);
}

value caml_curses_newwin(value nlines, value ncols, value x0, value y0)
{
  CAMLparam4 (nlines, ncols, x0, y0);
  CAMLreturn (alloc_window(newwin(Int_val(nlines), Int_val(ncols),
                                  Int_val(x0), Int_val(y0))));
}

value caml_curses_addch(value c)
{
  CAMLparam1 (c);
  addch(Int_val(c));            /* Characters are encoded like integers */
  CAMLreturn (Val_unit);
}

value caml_curses_mvwaddch(value win, value x, value y, value c)
{
  CAMLparam4 (win, x, y, c);
  mvwaddch(Window_val(win), Int_val(x), Int_val(y), Int_val(c));
  CAMLreturn (Val_unit);
}

value caml_curses_addstr(value s)
{
  CAMLparam1 (s);
  addstr(String_val(s));
  CAMLreturn (Val_unit);
}

value caml_curses_mvwaddstr(value win, value x, value y, value s)
{
  CAMLparam4 (win, x, y, s);
  mvwaddstr(Window_val(win), Int_val(x), Int_val(y), String_val(s));
  CAMLreturn (Val_unit);
}

/* This goes on for pages. */
</pre><p>
The file <span class="c003">curses_stubs.c</span> can be compiled with:
</p><pre>        cc -c -I`ocamlc -where` curses_stubs.c
</pre><p>or, even simpler,
</p><pre>        ocamlc -c curses_stubs.c
</pre><p>(When passed a <span class="c003">.c</span> file, the <span class="c003">ocamlc</span> command simply calls the C
compiler on that file, with the right <span class="c003">-I</span> option.)</p><p>Now, here is a sample OCaml program <span class="c003">prog.ml</span> that uses the <span class="c003">curses</span>
module:
</p><pre>(* File prog.ml -- main program using curses *)
open Curses;;
let main_window = initscr () in
let small_window = newwin 10 5 20 10 in
  mvwaddstr main_window 10 2 "Hello";
  mvwaddstr small_window 4 3 "world";
  refresh();
  Unix.sleep 5;
  endwin()
</pre><p>To compile and link this program, run:
</p><pre>       ocamlc -custom -o prog unix.cma curses.cmo prog.ml curses_stubs.o -cclib -lcurses
</pre><p>(On some machines, you may need to put
<span class="c003">-cclib -lcurses -cclib -ltermcap</span> or <span class="c003">-cclib -ltermcap</span>
instead of <span class="c003">-cclib -lcurses</span>.)</p>
<!--TOC section id="s:c-callback" 20.7  Advanced topic: callbacks from C to OCaml-->
<h2 class="section" id="s:c-callback"><a class="section-anchor" href="#s:c-callback" aria-hidden="true"></a>20.7  Advanced topic: callbacks from C to OCaml</h2><!--SEC END --><p>So far, we have described how to call C functions from OCaml. In this
section, we show how C functions can call OCaml functions, either as
callbacks (OCaml calls C which calls OCaml), or with the main program
written in C.</p>
<!--TOC subsection id="ss:c-callbacks" 20.7.1  Applying OCaml closures from C-->
<h3 class="subsection" id="ss:c-callbacks"><a class="section-anchor" href="#ss:c-callbacks" aria-hidden="true"></a>20.7.1  Applying OCaml closures from C</h3><!--SEC END --><p>C functions can apply OCaml function values (closures) to OCaml values.
The following functions are provided to perform the applications:
</p><ul class="itemize"><li class="li-itemize">
<span class="c003">caml_callback(</span><span class="c009">f, a</span><span class="c003">)</span> applies the functional value <span class="c009">f</span> to
the value <span class="c009">a</span> and returns the value returned by <span class="c009">f</span>.
</li><li class="li-itemize"><span class="c003">caml_callback2(</span><span class="c009">f, a, b</span><span class="c003">)</span> applies the functional value <span class="c009">f</span>
(which is assumed to be a curried OCaml function with two arguments) to
<span class="c009">a</span> and <span class="c009">b</span>.
</li><li class="li-itemize"><span class="c003">caml_callback3(</span><span class="c009">f, a, b, c</span><span class="c003">)</span> applies the functional value <span class="c009">f</span>
(a curried OCaml function with three arguments) to <span class="c009">a</span>, <span class="c009">b</span> and <span class="c009">c</span>.
</li><li class="li-itemize"><span class="c003">caml_callbackN(</span><span class="c009">f, n, args</span><span class="c003">)</span> applies the functional value <span class="c009">f</span>
to the <span class="c009">n</span> arguments contained in the array of values <span class="c009">args</span>.
</li></ul><p>
If the function <span class="c009">f</span> does not return, but raises an exception that
escapes the scope of the application, then this exception is
propagated to the next enclosing OCaml code, skipping over the C
code. That is, if an OCaml function <span class="c009">f</span> calls a C function <span class="c009">g</span> that
calls back an OCaml function <span class="c009">h</span> that raises a stray exception, then the
execution of <span class="c009">g</span> is interrupted and the exception is propagated back
into <span class="c009">f</span>.</p><p>If the C code wishes to catch exceptions escaping the OCaml function,
it can use the functions <span class="c003">caml_callback_exn</span>, <span class="c003">caml_callback2_exn</span>,
<span class="c003">caml_callback3_exn</span>, <span class="c003">caml_callbackN_exn</span>. These functions take the same
arguments as their non-<span class="c003">_exn</span> counterparts, but catch escaping
exceptions and return them to the C code. The return value <span class="c009">v</span> of the
<span class="c003">caml_callback*_exn</span> functions must be tested with the macro
<span class="c003">Is_exception_result(</span><span class="c009">v</span><span class="c003">)</span>. If the macro returns “false”, no
exception occurred, and <span class="c009">v</span> is the value returned by the OCaml
function. If <span class="c003">Is_exception_result(</span><span class="c009">v</span><span class="c003">)</span> returns “true”,
an exception escaped, and its value (the exception descriptor) can be
recovered using <span class="c003">Extract_exception(</span><span class="c009">v</span><span class="c003">)</span>.</p>
<!--TOC paragraph id="sec461" Warning:-->
<h5 class="paragraph" id="sec461"><a class="section-anchor" href="#sec461" aria-hidden="true"></a>Warning:</h5><!--SEC END --><p> If the OCaml function returned with an exception,
<span class="c003">Extract_exception</span> should be applied to the exception result prior
to calling a function that may trigger garbage collection.
Otherwise, if <span class="c009">v</span> is reachable during garbage collection, the runtime
can crash since <span class="c009">v</span> does not contain a valid value.</p><p>Example:
</p><pre>    value call_caml_f_ex(value closure, value arg)
    {
      CAMLparam2(closure, arg);
      CAMLlocal2(res, tmp);
      res = caml_callback_exn(closure, arg);
      if(Is_exception_result(res)) {
        res = Extract_exception(res);
        tmp = caml_alloc(3, 0); /* Safe to allocate: res contains valid value. */
        ...
      }
      CAMLreturn (res);
    }
</pre>
<!--TOC subsection id="ss:c-closures" 20.7.2  Obtaining or registering OCaml closures for use in C functions-->
<h3 class="subsection" id="ss:c-closures"><a class="section-anchor" href="#ss:c-closures" aria-hidden="true"></a>20.7.2  Obtaining or registering OCaml closures for use in C functions</h3><!--SEC END --><p>There are two ways to obtain OCaml function values (closures) to
be passed to the <span class="c003">callback</span> functions described above. One way is to
pass the OCaml function as an argument to a primitive function. For
example, if the OCaml code contains the declaration
</p><pre>    external apply : ('a -&gt; 'b) -&gt; 'a -&gt; 'b = "caml_apply"
</pre><p>the corresponding C stub can be written as follows:
</p><pre>    CAMLprim value caml_apply(value vf, value vx)
    {
      CAMLparam2(vf, vx);
      CAMLlocal1(vy);
      vy = caml_callback(vf, vx);
      CAMLreturn(vy);
    }
</pre><p>
Another possibility is to use the registration mechanism provided by
OCaml. This registration mechanism enables OCaml code to register
OCaml functions under some global name, and C code to retrieve the
corresponding closure by this global name.</p><p>On the OCaml side, registration is performed by evaluating
<span class="c003">Callback.register</span> <span class="c009">n v</span>. Here, <span class="c009">n</span> is the global name
(an arbitrary string) and <span class="c009">v</span> the OCaml value. For instance:
</p><pre>    let f x = print_string "f is applied to "; print_int x; print_newline()
    let _ = Callback.register "test function" f
</pre><p>
On the C side, a pointer to the value registered under name <span class="c009">n</span> is
obtained by calling <span class="c003">caml_named_value(</span><span class="c009">n</span><span class="c003">)</span>. The returned
pointer must then be dereferenced to recover the actual OCaml value.
If no value is registered under the name <span class="c009">n</span>, the null pointer is
returned. For example, here is a C wrapper that calls the OCaml function <span class="c003">f</span>
above:
</p><pre>    void call_caml_f(int arg)
    {
        caml_callback(*caml_named_value("test function"), Val_int(arg));
    }
</pre><p>
The pointer returned by <span class="c003">caml_named_value</span> is constant and can safely
be cached in a C variable to avoid repeated name lookups. The value
pointed to cannot be changed from C. However, it might change during
garbage collection, so must always be recomputed at the point of
use. Here is a more efficient variant of <span class="c003">call_caml_f</span> above that
calls <span class="c003">caml_named_value</span> only once:
</p><pre>    void call_caml_f(int arg)
    {
        static const value * closure_f = NULL;
        if (closure_f == NULL) {
            /* First time around, look up by name */
            closure_f = caml_named_value("test function");
        }
        caml_callback(*closure_f, Val_int(arg));
    }
</pre>
<!--TOC subsection id="ss:c-register-exn" 20.7.3  Registering OCaml exceptions for use in C functions-->
<h3 class="subsection" id="ss:c-register-exn"><a class="section-anchor" href="#ss:c-register-exn" aria-hidden="true"></a>20.7.3  Registering OCaml exceptions for use in C functions</h3><!--SEC END --><p>The registration mechanism described above can also be used to
communicate exception identifiers from OCaml to C. The OCaml code
registers the exception by evaluating
<span class="c003">Callback.register_exception</span> <span class="c009">n exn</span>, where <span class="c009">n</span> is an
arbitrary name and <span class="c009">exn</span> is an exception value of the
exception to register. For example:
</p><pre>    exception Error of string
    let _ = Callback.register_exception "test exception" (Error "any string")
</pre><p>The C code can then recover the exception identifier using
<span class="c003">caml_named_value</span> and pass it as first argument to the functions
<span class="c003">raise_constant</span>, <span class="c003">raise_with_arg</span>, and <span class="c003">raise_with_string</span> (described
in section <a href="#ss%3Ac-exceptions">20.4.5</a>) to actually raise the exception. For
example, here is a C function that raises the <span class="c003">Error</span> exception with
the given argument:
</p><pre>    void raise_error(char * msg)
    {
        caml_raise_with_string(*caml_named_value("test exception"), msg);
    }
</pre>
<!--TOC subsection id="ss:main-c" 20.7.4  Main program in C-->
<h3 class="subsection" id="ss:main-c"><a class="section-anchor" href="#ss:main-c" aria-hidden="true"></a>20.7.4  Main program in C</h3><!--SEC END --><p>In normal operation, a mixed OCaml/C program starts by executing the
OCaml initialization code, which then may proceed to call C
functions. We say that the main program is the OCaml code. In some
applications, it is desirable that the C code plays the role of the
main program, calling OCaml functions when needed. This can be achieved as
follows:
</p><ul class="itemize"><li class="li-itemize">
The C part of the program must provide a <span class="c003">main</span> function,
which will override the default <span class="c003">main</span> function provided by the OCaml
runtime system. Execution will start in the user-defined <span class="c003">main</span> function
just like for a regular C program.</li><li class="li-itemize">At some point, the C code must call <span class="c003">caml_main(argv)</span> to
initialize the OCaml code. The <span class="c003">argv</span> argument is a C array of strings
(type <span class="c003">char **</span>), terminated with a <span class="c003">NULL</span> pointer,
which represents the command-line arguments, as
passed as second argument to <span class="c003">main</span>. The OCaml array <span class="c003">Sys.argv</span> will
be initialized from this parameter. For the bytecode compiler,
<span class="c003">argv[0]</span> and <span class="c003">argv[1]</span> are also consulted to find the file containing
the bytecode.</li><li class="li-itemize">The call to <span class="c003">caml_main</span> initializes the OCaml runtime system,
loads the bytecode (in the case of the bytecode compiler), and
executes the initialization code of the OCaml program. Typically, this
initialization code registers callback functions using <span class="c003">Callback.register</span>.
Once the OCaml initialization code is complete, control returns to the
C code that called <span class="c003">caml_main</span>.</li><li class="li-itemize">The C code can then invoke OCaml functions using the callback
mechanism (see section <a href="#ss%3Ac-callbacks">20.7.1</a>).
</li></ul>
<!--TOC subsection id="ss:c-embedded-code" 20.7.5  Embedding the OCaml code in the C code-->
<h3 class="subsection" id="ss:c-embedded-code"><a class="section-anchor" href="#ss:c-embedded-code" aria-hidden="true"></a>20.7.5  Embedding the OCaml code in the C code</h3><!--SEC END --><p>The bytecode compiler in custom runtime mode (<span class="c003">ocamlc -custom</span>)
normally appends the bytecode to the executable file containing the
custom runtime. This has two consequences. First, the final linking
step must be performed by <span class="c003">ocamlc</span>. Second, the OCaml runtime library
must be able to find the name of the executable file from the
command-line arguments. When using <span class="c003">caml_main(argv)</span> as in
section <a href="#ss%3Amain-c">20.7.4</a>, this means that <span class="c003">argv[0]</span> or <span class="c003">argv[1]</span> must
contain the executable file name.</p><p>An alternative is to embed the bytecode in the C code. The
<span class="c003">-output-obj</span> option to <span class="c003">ocamlc</span> is provided for this purpose. It
causes the <span class="c003">ocamlc</span> compiler to output a C object file (<span class="c003">.o</span> file,
<span class="c003">.obj</span> under Windows) containing the bytecode for the OCaml part of the
program, as well as a <span class="c003">caml_startup</span> function. The C object file
produced by <span class="c003">ocamlc -output-obj</span> can then be linked with C code using
the standard C compiler, or stored in a C library.</p><p>The <span class="c003">caml_startup</span> function must be called from the main C program in
order to initialize the OCaml runtime and execute the OCaml
initialization code. Just like <span class="c003">caml_main</span>, it takes one <span class="c003">argv</span>
parameter containing the command-line parameters. Unlike <span class="c003">caml_main</span>,
this <span class="c003">argv</span> parameter is used only to initialize <span class="c003">Sys.argv</span>, but not
for finding the name of the executable file.</p><p>The <span class="c003">caml_startup</span> function calls the uncaught exception handler (or
enters the debugger, if running under ocamldebug) if an exception escapes
from a top-level module initialiser. Such exceptions may be caught in the
C code by instead using the <span class="c003">caml_startup_exn</span> function and testing the result
using <span class="c003">Is_exception_result</span> (followed by <span class="c003">Extract_exception</span> if
appropriate).</p><p>The <span class="c003">-output-obj</span> option can also be used to obtain the C source file.
More interestingly, the same option can also produce directly a shared
library (<span class="c003">.so</span> file, <span class="c003">.dll</span> under Windows) that contains the OCaml
code, the OCaml runtime system and any other static C code given to
<span class="c003">ocamlc</span> (<span class="c003">.o</span>, <span class="c003">.a</span>, respectively, <span class="c003">.obj</span>, <span class="c003">.lib</span>). This use of
<span class="c003">-output-obj</span> is very similar to a normal linking step, but instead of
producing a main program that automatically runs the OCaml code, it
produces a shared library that can run the OCaml code on demand. The
three possible behaviors of <span class="c003">-output-obj</span> are selected according
to the extension of the resulting file (given with <span class="c003">-o</span>).</p><p>The native-code compiler <span class="c003">ocamlopt</span> also supports the <span class="c003">-output-obj</span>
option, causing it to output a C object file or a shared library
containing the native code for all OCaml modules on the command-line,
as well as the OCaml startup code. Initialization is performed by
calling <span class="c003">caml_startup</span> (or <span class="c003">caml_startup_exn</span>) as in the case of the
bytecode compiler.</p><p>For the final linking phase, in addition to the object file produced
by <span class="c003">-output-obj</span>, you will have to provide the OCaml runtime
library (<span class="c003">libcamlrun.a</span> for bytecode, <span class="c003">libasmrun.a</span> for native-code),
as well as all C libraries that are required by the OCaml libraries
used. For instance, assume the OCaml part of your program uses the
Unix library. With <span class="c003">ocamlc</span>, you should do:
</p><pre>
        ocamlc -output-obj -o camlcode.o unix.cma <span class="c009">other</span> .cmo <span class="c009">and</span> .cma <span class="c009">files</span>
        cc -o myprog <span class="c009">C objects and libraries</span> \
           camlcode.o -L‘ocamlc -where‘ -lunix -lcamlrun
</pre><p>
With <span class="c003">ocamlopt</span>, you should do:
</p><pre>
        ocamlopt -output-obj -o camlcode.o unix.cmxa <span class="c009">other</span> .cmx <span class="c009">and</span> .cmxa <span class="c009">files</span>
        cc -o myprog <span class="c009">C objects and libraries</span> \
           camlcode.o -L‘ocamlc -where‘ -lunix -lasmrun
</pre>
<!--TOC paragraph id="sec466" Warning:-->
<h5 class="paragraph" id="sec466"><a class="section-anchor" href="#sec466" aria-hidden="true"></a>Warning:</h5><!--SEC END --><p> On some ports, special options are required on the final
linking phase that links together the object file produced by the
<span class="c003">-output-obj</span> option and the remainder of the program. Those options
are shown in the configuration file <span class="c003">Makefile.config</span> generated during
compilation of OCaml, as the variable <span class="c003">OC_LDFLAGS</span>.
</p><ul class="itemize"><li class="li-itemize">
Windows with the MSVC compiler: the object file produced by
OCaml have been compiled with the <span class="c003">/MD</span> flag, and therefore
all other object files linked with it should also be compiled with
<span class="c003">/MD</span>.
</li><li class="li-itemize">other systems: you may have to add one or more of <span class="c003">-lcurses</span>,
<span class="c003">-lm</span>, <span class="c003">-ldl</span>, depending on your OS and C compiler.
</li></ul>
<!--TOC paragraph id="sec467" Stack backtraces.-->
<h5 class="paragraph" id="sec467"><a class="section-anchor" href="#sec467" aria-hidden="true"></a>Stack backtraces.</h5><!--SEC END --><p> When OCaml bytecode produced by
<span class="c003">ocamlc -g</span> is embedded in a C program, no debugging information is
included, and therefore it is impossible to print stack backtraces on
uncaught exceptions. This is not the case when native code produced
by <span class="c003">ocamlopt -g</span> is embedded in a C program: stack backtrace
information is available, but the backtrace mechanism needs to be
turned on programmatically. This can be achieved from the OCaml side
by calling <span class="c003">Printexc.record_backtrace true</span> in the initialization of
one of the OCaml modules. This can also be achieved from the C side
by calling <span class="c003">caml_record_backtrace(Val_int(1));</span> in the OCaml-C glue code.</p>
<!--TOC paragraph id="sec468" Unloading the runtime.-->
<h5 class="paragraph" id="sec468"><a class="section-anchor" href="#sec468" aria-hidden="true"></a>Unloading the runtime.</h5><!--SEC END --><p>In case the shared library produced with <span class="c003">-output-obj</span> is to be loaded and
unloaded repeatedly by a single process, care must be taken to unload the
OCaml runtime explicitly, in order to avoid various system resource leaks.</p><p>Since 4.05, <span class="c003">caml_shutdown</span> function can be used to shut the runtime down
gracefully, which equals the following:
</p><ul class="itemize"><li class="li-itemize">
Running the functions that were registered with <span class="c003">Stdlib.at_exit</span>.
</li><li class="li-itemize">Triggering finalization of allocated custom blocks (see
section <a href="#s%3Ac-custom">20.9</a>). For example, <span class="c003">Stdlib.in_channel</span> and
<span class="c003">Stdlib.out_channel</span> are represented by custom blocks that enclose file
descriptors, which are to be released.
</li><li class="li-itemize">Unloading the dependent shared libraries that were loaded by the runtime,
including <span class="c003">dynlink</span> plugins.
</li><li class="li-itemize">Freeing the memory blocks that were allocated by the runtime with
<span class="c003">malloc</span>. Inside C primitives, it is advised to use <span class="c003">caml_stat_*</span> functions
from <span class="c003">memory.h</span> for managing static (that is, non-moving) blocks of heap
memory, as all the blocks allocated with these functions are automatically
freed by <span class="c003">caml_shutdown</span>. For ensuring compatibility with legacy C stubs that
have used <span class="c003">caml_stat_*</span> incorrectly, this behaviour is only enabled if the
runtime is started with a specialized <span class="c003">caml_startup_pooled</span> function.
</li></ul><p>As a shared library may have several clients simultaneously, it is made for
convenience that <span class="c003">caml_startup</span> (and <span class="c003">caml_startup_pooled</span>) may be called
multiple times, given that each such call is paired with a corresponding call
to <span class="c003">caml_shutdown</span> (in a nested fashion). The runtime will be unloaded once
there are no outstanding calls to <span class="c003">caml_startup</span>.</p><p>Once a runtime is unloaded, it cannot be started up again without reloading the
shared library and reinitializing its static data. Therefore, at the moment, the
facility is only useful for building reloadable shared libraries.</p>
<!--TOC section id="s:c-advexample" 20.8  Advanced example with callbacks-->
<h2 class="section" id="s:c-advexample"><a class="section-anchor" href="#s:c-advexample" aria-hidden="true"></a>20.8  Advanced example with callbacks</h2><!--SEC END --><p>This section illustrates the callback facilities described in
section <a href="#s%3Ac-callback">20.7</a>. We are going to package some OCaml functions
in such a way that they can be linked with C code and called from C
just like any C functions. The OCaml functions are defined in the
following <span class="c003">mod.ml</span> OCaml source:</p><pre>(* File mod.ml -- some "useful" OCaml functions *)

let rec fib n = if n &lt; 2 then 1 else fib(n-1) + fib(n-2)

let format_result n = Printf.sprintf "Result is: %d\n" n

(* Export those two functions to C *)

let _ = Callback.register "fib" fib
let _ = Callback.register "format_result" format_result
</pre><p>
Here is the C stub code for calling these functions from C:</p><pre>/* File modwrap.c -- wrappers around the OCaml functions */

#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#include &lt;caml/mlvalues.h&gt;
#include &lt;caml/callback.h&gt;

int fib(int n)
{
  static const value * fib_closure = NULL;
  if (fib_closure == NULL) fib_closure = caml_named_value("fib");
  return Int_val(caml_callback(*fib_closure, Val_int(n)));
}

char * format_result(int n)
{
  static const value * format_result_closure = NULL;
  if (format_result_closure == NULL)
    format_result_closure = caml_named_value("format_result");
  return strdup(String_val(caml_callback(*format_result_closure, Val_int(n))));
  /* We copy the C string returned by String_val to the C heap
     so that it remains valid after garbage collection. */
}
</pre><p>
We now compile the OCaml code to a C object file and put it in a C
library along with the stub code in <span class="c003">modwrap.c</span> and the OCaml runtime system:
</p><pre>        ocamlc -custom -output-obj -o modcaml.o mod.ml
        ocamlc -c modwrap.c
        cp `ocamlc -where`/libcamlrun.a mod.a &amp;&amp; chmod +w mod.a
        ar r mod.a modcaml.o modwrap.o
</pre><p>(One can also use <span class="c003">ocamlopt -output-obj</span> instead of <span class="c003">ocamlc -custom -output-obj</span>. In this case, replace <span class="c003">libcamlrun.a</span> (the bytecode
runtime library) by <span class="c003">libasmrun.a</span> (the native-code runtime library).)</p><p>Now, we can use the two functions <span class="c003">fib</span> and <span class="c003">format_result</span> in any C
program, just like regular C functions. Just remember to call
<span class="c003">caml_startup</span> (or <span class="c003">caml_startup_exn</span>) once before.</p><pre>/* File main.c -- a sample client for the OCaml functions */

#include &lt;stdio.h&gt;
#include &lt;caml/callback.h&gt;

extern int fib(int n);
extern char * format_result(int n);

int main(int argc, char ** argv)
{
  int result;

  /* Initialize OCaml code */
  caml_startup(argv);
  /* Do some computation */
  result = fib(10);
  printf("fib(10) = %s\n", format_result(result));
  return 0;
}
</pre><p>
To build the whole program, just invoke the C compiler as follows:
</p><pre>        cc -o prog -I `ocamlc -where` main.c mod.a -lcurses
</pre><p>(On some machines, you may need to put <span class="c003">-ltermcap</span> or
<span class="c003">-lcurses -ltermcap</span> instead of <span class="c003">-lcurses</span>.)</p>
<!--TOC section id="s:c-custom" 20.9  Advanced topic: custom blocks-->
<h2 class="section" id="s:c-custom"><a class="section-anchor" href="#s:c-custom" aria-hidden="true"></a>20.9  Advanced topic: custom blocks</h2><!--SEC END --><p>Blocks with tag <span class="c003">Custom_tag</span> contain both arbitrary user data and a
pointer to a C struct, with type <span class="c003">struct custom_operations</span>, that
associates user-provided finalization, comparison, hashing,
serialization and deserialization functions to this block.</p>
<!--TOC subsection id="ss:c-custom-ops" 20.9.1  The <span class="c003">struct custom</span><span class="c003">_</span><span class="c003">operations</span>-->
<h3 class="subsection" id="ss:c-custom-ops"><a class="section-anchor" href="#ss:c-custom-ops" aria-hidden="true"></a>20.9.1  The <span class="c003">struct custom_operations</span></h3><!--SEC END --><p>The <span class="c003">struct custom_operations</span> is defined in <span class="c003">&lt;caml/custom.h&gt;</span> and
contains the following fields:
</p><ul class="itemize"><li class="li-itemize">
<span class="c003">char *identifier</span> <br>
A zero-terminated character string serving as an identifier for
serialization and deserialization operations.</li><li class="li-itemize"><span class="c003">void  (*finalize)(value v)</span> <br>
The <span class="c003">finalize</span> field contains a pointer to a C function that is called
when the block becomes unreachable and is about to be reclaimed.
The block is passed as first argument to the function.
The <span class="c003">finalize</span> field can also be <span class="c003">custom_finalize_default</span> to indicate that no
finalization function is associated with the block.</li><li class="li-itemize"><span class="c003">int (*compare)(value v1, value v2)</span> <br>
The <span class="c003">compare</span> field contains a pointer to a C function that is
called whenever two custom blocks are compared using OCaml’s generic
comparison operators (<span class="c003">=</span>, <span class="c003">&lt;&gt;</span>, <span class="c003">&lt;=</span>, <span class="c003">&gt;=</span>, <span class="c003">&lt;</span>, <span class="c003">&gt;</span> and
<span class="c003">compare</span>). The C function should return 0 if the data contained in
the two blocks are structurally equal, a negative integer if the data
from the first block is less than the data from the second block, and
a positive integer if the data from the first block is greater than
the data from the second block.<p>The <span class="c003">compare</span> field can be set to <span class="c003">custom_compare_default</span>; this
default comparison function simply raises <span class="c003">Failure</span>.</p></li><li class="li-itemize"><span class="c003">int (*compare_ext)(value v1, value v2)</span> <br>
(Since 3.12.1)
The <span class="c003">compare_ext</span> field contains a pointer to a C function that is
called whenever one custom block and one unboxed integer are compared using OCaml’s generic
comparison operators (<span class="c003">=</span>, <span class="c003">&lt;&gt;</span>, <span class="c003">&lt;=</span>, <span class="c003">&gt;=</span>, <span class="c003">&lt;</span>, <span class="c003">&gt;</span> and
<span class="c003">compare</span>). As in the case of the <span class="c003">compare</span> field, the C function
should return 0 if the two arguments are structurally equal, a
negative integer if the first argument compares less than the second
argument, and a positive integer if the first argument compares
greater than the second argument.<p>The <span class="c003">compare_ext</span> field can be set to <span class="c003">custom_compare_ext_default</span>; this
default comparison function simply raises <span class="c003">Failure</span>.</p></li><li class="li-itemize"><span class="c003">intnat (*hash)(value v)</span> <br>
The <span class="c003">hash</span> field contains a pointer to a C function that is called
whenever OCaml’s generic hash operator (see module <a href="libref/Hashtbl.html"><span class="c003">Hashtbl</span></a>) is
applied to a custom block. The C function can return an arbitrary
integer representing the hash value of the data contained in the
given custom block. The hash value must be compatible with the
<span class="c003">compare</span> function, in the sense that two structurally equal data
(that is, two custom blocks for which <span class="c003">compare</span> returns 0) must have
the same hash value.<p>The <span class="c003">hash</span> field can be set to <span class="c003">custom_hash_default</span>, in which case
the custom block is ignored during hash computation.</p></li><li class="li-itemize"><span class="c003">void (*serialize)(value v, uintnat * bsize_32, uintnat * bsize_64)</span> <br>
The <span class="c003">serialize</span> field contains a pointer to a C function that is
called whenever the custom block needs to be serialized (marshaled)
using the OCaml functions <span class="c003">output_value</span> or <span class="c003">Marshal.to_...</span>.
For a custom block, those functions first write the identifier of the
block (as given by the <span class="c003">identifier</span> field) to the output stream,
then call the user-provided <span class="c003">serialize</span> function. That function is
responsible for writing the data contained in the custom block, using
the <span class="c003">serialize_...</span> functions defined in <span class="c003">&lt;caml/intext.h&gt;</span> and listed
below. The user-provided <span class="c003">serialize</span> function must then store in its
<span class="c003">bsize_32</span> and <span class="c003">bsize_64</span> parameters the sizes in bytes of the data
part of the custom block on a 32-bit architecture and on a 64-bit
architecture, respectively.<p>The <span class="c003">serialize</span> field can be set to <span class="c003">custom_serialize_default</span>,
in which case the <span class="c003">Failure</span> exception is raised when attempting to
serialize the custom block.</p></li><li class="li-itemize"><span class="c003">uintnat (*deserialize)(void * dst)</span> <br>
The <span class="c003">deserialize</span> field contains a pointer to a C function that is
called whenever a custom block with identifier <span class="c003">identifier</span> needs to
be deserialized (un-marshaled) using the OCaml functions <span class="c003">input_value</span>
or <span class="c003">Marshal.from_...</span>. This user-provided function is responsible for
reading back the data written by the <span class="c003">serialize</span> operation, using the
<span class="c003">deserialize_...</span> functions defined in <span class="c003">&lt;caml/intext.h&gt;</span> and listed
below. It must then rebuild the data part of the custom block
and store it at the pointer given as the <span class="c003">dst</span> argument. Finally, it
returns the size in bytes of the data part of the custom block.
This size must be identical to the <span class="c003">wsize_32</span> result of
the <span class="c003">serialize</span> operation if the architecture is 32 bits, or
<span class="c003">wsize_64</span> if the architecture is 64 bits.<p>The <span class="c003">deserialize</span> field can be set to <span class="c003">custom_deserialize_default</span>
to indicate that deserialization is not supported. In this case,
do not register the <span class="c003">struct custom_operations</span> with the deserializer
using <span class="c003">register_custom_operations</span> (see below).</p></li><li class="li-itemize"><span class="c003">const struct custom_fixed_length* fixed_length</span> <br>
(Since 4.08.0)
Normally, space in the serialized output is reserved to write the
<span class="c003">bsize_32</span> and <span class="c003">bsize_64</span> fields returned by <span class="c003">serialize</span>. However, for
very short custom blocks, this space can be larger than the data
itself! As a space optimisation, if <span class="c003">serialize</span> always returns the
same values for <span class="c003">bsize_32</span> and <span class="c003">bsize_64</span>, then these values may be
specified in the <span class="c003">fixed_length</span> structure, and do not consume space in
the serialized output.
</li></ul><p>Note: the <span class="c003">finalize</span>, <span class="c003">compare</span>, <span class="c003">hash</span>, <span class="c003">serialize</span> and <span class="c003">deserialize</span>
functions attached to custom block descriptors must never trigger a
garbage collection. Within these functions, do not call any of the
OCaml allocation functions, and do not perform a callback into OCaml
code. Do not use <span class="c003">CAMLparam</span> to register the parameters to these
functions, and do not use <span class="c003">CAMLreturn</span> to return the result.</p>
<!--TOC subsection id="ss:c-custom-alloc" 20.9.2  Allocating custom blocks-->
<h3 class="subsection" id="ss:c-custom-alloc"><a class="section-anchor" href="#ss:c-custom-alloc" aria-hidden="true"></a>20.9.2  Allocating custom blocks</h3><!--SEC END --><p>Custom blocks must be allocated via <span class="c003">caml_alloc_custom</span> or
<span class="c003">caml_alloc_custom_mem</span>:
</p><div class="center">
<span class="c003">caml_alloc_custom(</span><span class="c009">ops</span><span class="c003">, </span><span class="c009">size</span><span class="c003">, </span><span class="c009">used</span><span class="c003">, </span><span class="c009">max</span><span class="c003">)</span>
</div><p>
returns a fresh custom block, with room for <span class="c009">size</span> bytes of user
data, and whose associated operations are given by <span class="c009">ops</span> (a
pointer to a <span class="c003">struct custom_operations</span>, usually statically allocated
as a C global variable).</p><p>The two parameters <span class="c009">used</span> and <span class="c009">max</span> are used to control the
speed of garbage collection when the finalized object contains
pointers to out-of-heap resources. Generally speaking, the
OCaml incremental major collector adjusts its speed relative to the
allocation rate of the program. The faster the program allocates, the
harder the GC works in order to reclaim quickly unreachable blocks
and avoid having large amount of “floating garbage” (unreferenced
objects that the GC has not yet collected).</p><p>Normally, the allocation rate is measured by counting the in-heap size
of allocated blocks. However, it often happens that finalized
objects contain pointers to out-of-heap memory blocks and other resources
(such as file descriptors, X Windows bitmaps, etc.). For those
blocks, the in-heap size of blocks is not a good measure of the
quantity of resources allocated by the program.</p><p>The two arguments <span class="c009">used</span> and <span class="c009">max</span> give the GC an idea of how
much out-of-heap resources are consumed by the finalized block
being allocated: you give the amount of resources allocated to this
object as parameter <span class="c009">used</span>, and the maximum amount that you want
to see in floating garbage as parameter <span class="c009">max</span>. The units are
arbitrary: the GC cares only about the ratio <span class="c009">used</span> / <span class="c009">max</span>.</p><p>For instance, if you are allocating a finalized block holding an X
Windows bitmap of <span class="c009">w</span> by <span class="c009">h</span> pixels, and you’d rather not
have more than 1 mega-pixels of unreclaimed bitmaps, specify
<span class="c009">used</span> = <span class="c009">w</span> * <span class="c009">h</span> and <span class="c009">max</span> = 1000000.</p><p>Another way to describe the effect of the <span class="c009">used</span> and <span class="c009">max</span>
parameters is in terms of full GC cycles. If you allocate many custom
blocks with <span class="c009">used</span> / <span class="c009">max</span> = 1 / <span class="c009">N</span>, the GC will then do one
full cycle (examining every object in the heap and calling
finalization functions on those that are unreachable) every <span class="c009">N</span>
allocations. For instance, if <span class="c009">used</span> = 1 and <span class="c009">max</span> = 1000,
the GC will do one full cycle at least every 1000 allocations of
custom blocks.</p><p>If your finalized blocks contain no pointers to out-of-heap resources,
or if the previous discussion made little sense to you, just take
<span class="c009">used</span> = 0 and <span class="c009">max</span> = 1. But if you later find that the
finalization functions are not called “often enough”, consider
increasing the <span class="c009">used</span> / <span class="c009">max</span> ratio.</p><div class="center">
<span class="c003">caml_alloc_custom_mem(</span><span class="c009">ops</span><span class="c003">, </span><span class="c009">size</span><span class="c003">, </span><span class="c009">used</span><span class="c003">)</span>
</div><p>
Use this function when your custom block holds only out-of-heap memory
(memory allocated with <span class="c003">malloc</span> or <span class="c003">caml_stat_alloc</span>) and no other
resources. <span class="c003">used</span> should be the number of bytes of out-of-heap
memory that are held by your custom block. This function works like
<span class="c003">caml_alloc_custom</span> except that the <span class="c003">max</span> parameter is under the
control of the user (via the <span class="c003">custom_major_ratio</span>,
<span class="c003">custom_minor_ratio</span>, and <span class="c003">custom_minor_max_size</span> parameters) and
proportional to the heap sizes.</p>
<!--TOC subsection id="ss:c-custom-access" 20.9.3  Accessing custom blocks-->
<h3 class="subsection" id="ss:c-custom-access"><a class="section-anchor" href="#ss:c-custom-access" aria-hidden="true"></a>20.9.3  Accessing custom blocks</h3><!--SEC END --><p>The data part of a custom block <span class="c009">v</span> can be
accessed via the pointer <span class="c003">Data_custom_val(</span><span class="c009">v</span><span class="c003">)</span>. This pointer
has type <span class="c003">void *</span> and should be cast to the actual type of the data
stored in the custom block.</p><p>The contents of custom blocks are not scanned by the garbage
collector, and must therefore not contain any pointer inside the OCaml
heap. In other terms, never store an OCaml <span class="c003">value</span> in a custom block,
and do not use <span class="c003">Field</span>, <span class="c003">Store_field</span> nor <span class="c003">caml_modify</span> to access the data
part of a custom block. Conversely, any C data structure (not
containing heap pointers) can be stored in a custom block.</p>
<!--TOC subsection id="ss:c-custom-serialization" 20.9.4  Writing custom serialization and deserialization functions-->
<h3 class="subsection" id="ss:c-custom-serialization"><a class="section-anchor" href="#ss:c-custom-serialization" aria-hidden="true"></a>20.9.4  Writing custom serialization and deserialization functions</h3><!--SEC END --><p>The following functions, defined in <span class="c003">&lt;caml/intext.h&gt;</span>, are provided to
write and read back the contents of custom blocks in a portable way.
Those functions handle endianness conversions when e.g. data is
written on a little-endian machine and read back on a big-endian machine.</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Function</span></td><td class="c014"><span class="c013">Action</span> </td></tr>
<tr><td class="c022">
<span class="c003">caml_serialize_int_1</span></td><td class="c021">Write a 1-byte integer </td></tr>
<tr><td class="c022"><span class="c003">caml_serialize_int_2</span></td><td class="c021">Write a 2-byte integer </td></tr>
<tr><td class="c022"><span class="c003">caml_serialize_int_4</span></td><td class="c021">Write a 4-byte integer </td></tr>
<tr><td class="c022"><span class="c003">caml_serialize_int_8</span></td><td class="c021">Write a 8-byte integer </td></tr>
<tr><td class="c022"><span class="c003">caml_serialize_float_4</span></td><td class="c021">Write a 4-byte float </td></tr>
<tr><td class="c022"><span class="c003">caml_serialize_float_8</span></td><td class="c021">Write a 8-byte float </td></tr>
<tr><td class="c022"><span class="c003">caml_serialize_block_1</span></td><td class="c021">Write an array of 1-byte quantities </td></tr>
<tr><td class="c022"><span class="c003">caml_serialize_block_2</span></td><td class="c021">Write an array of 2-byte quantities </td></tr>
<tr><td class="c022"><span class="c003">caml_serialize_block_4</span></td><td class="c021">Write an array of 4-byte quantities </td></tr>
<tr><td class="c022"><span class="c003">caml_serialize_block_8</span></td><td class="c021">Write an array of 8-byte quantities </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_uint_1</span></td><td class="c021">Read an unsigned 1-byte integer </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_sint_1</span></td><td class="c021">Read a signed 1-byte integer </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_uint_2</span></td><td class="c021">Read an unsigned 2-byte integer </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_sint_2</span></td><td class="c021">Read a signed 2-byte integer </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_uint_4</span></td><td class="c021">Read an unsigned 4-byte integer </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_sint_4</span></td><td class="c021">Read a signed 4-byte integer </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_uint_8</span></td><td class="c021">Read an unsigned 8-byte integer </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_sint_8</span></td><td class="c021">Read a signed 8-byte integer </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_float_4</span></td><td class="c021">Read a 4-byte float </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_float_8</span></td><td class="c021">Read an 8-byte float </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_block_1</span></td><td class="c021">Read an array of 1-byte quantities </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_block_2</span></td><td class="c021">Read an array of 2-byte quantities </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_block_4</span></td><td class="c021">Read an array of 4-byte quantities </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_block_8</span></td><td class="c021">Read an array of 8-byte quantities </td></tr>
<tr><td class="c022"><span class="c003">caml_deserialize_error</span></td><td class="c021">Signal an error during deserialization;
<span class="c003">input_value</span> or <span class="c003">Marshal.from_...</span> raise a <span class="c003">Failure</span> exception after
cleaning up their internal data structures </td></tr>
</table></div></div><p>Serialization functions are attached to the custom blocks to which
they apply. Obviously, deserialization functions cannot be attached
this way, since the custom block does not exist yet when
deserialization begins! Thus, the <span class="c003">struct custom_operations</span> that
contain deserialization functions must be registered with the
deserializer in advance, using the <span class="c003">register_custom_operations</span>
function declared in <span class="c003">&lt;caml/custom.h&gt;</span>. Deserialization proceeds by
reading the identifier off the input stream, allocating a custom block
of the size specified in the input stream, searching the registered
<span class="c003">struct custom_operation</span> blocks for one with the same identifier, and
calling its <span class="c003">deserialize</span> function to fill the data part of the custom block.</p>
<!--TOC subsection id="ss:c-custom-idents" 20.9.5  Choosing identifiers-->
<h3 class="subsection" id="ss:c-custom-idents"><a class="section-anchor" href="#ss:c-custom-idents" aria-hidden="true"></a>20.9.5  Choosing identifiers</h3><!--SEC END --><p>Identifiers in <span class="c003">struct custom_operations</span> must be chosen carefully,
since they must identify uniquely the data structure for serialization
and deserialization operations. In particular, consider including a
version number in the identifier; this way, the format of the data can
be changed later, yet backward-compatible deserialisation functions
can be provided.</p><p>Identifiers starting with <span class="c003">_</span> (an underscore character) are reserved
for the OCaml runtime system; do not use them for your custom
data. We recommend to use a URL
(<span class="c003">http://mymachine.mydomain.com/mylibrary/version-number</span>)
or a Java-style package name
(<span class="c003">com.mydomain.mymachine.mylibrary.version-number</span>)
as identifiers, to minimize the risk of identifier collision.</p>
<!--TOC subsection id="ss:c-finalized" 20.9.6  Finalized blocks-->
<h3 class="subsection" id="ss:c-finalized"><a class="section-anchor" href="#ss:c-finalized" aria-hidden="true"></a>20.9.6  Finalized blocks</h3><!--SEC END --><p>Custom blocks generalize the finalized blocks that were present in
OCaml prior to version 3.00. For backward compatibility, the
format of custom blocks is compatible with that of finalized blocks,
and the <span class="c003">alloc_final</span> function is still available to allocate a custom
block with a given finalization function, but default comparison,
hashing and serialization functions. <span class="c003">caml_alloc_final(</span><span class="c009">n</span><span class="c003">, </span><span class="c009">f</span><span class="c003">, </span><span class="c009">used</span><span class="c003">, </span><span class="c009">max</span><span class="c003">)</span> returns a fresh custom block of
size <span class="c009">n</span>+1 words, with finalization function <span class="c009">f</span>. The first
word is reserved for storing the custom operations; the other
<span class="c009">n</span> words are available for your data. The two parameters
<span class="c009">used</span> and <span class="c009">max</span> are used to control the speed of garbage
collection, as described for <span class="c003">caml_alloc_custom</span>.</p>
<!--TOC section id="s:C-Bigarrays" 20.10  Advanced topic: Bigarrays and the OCaml-C interface-->
<h2 class="section" id="s:C-Bigarrays"><a class="section-anchor" href="#s:C-Bigarrays" aria-hidden="true"></a>20.10  Advanced topic: Bigarrays and the OCaml-C interface</h2><!--SEC END --><p>This section explains how C stub code that interfaces C or Fortran
code with OCaml code can use Bigarrays.</p>
<!--TOC subsection id="ss:C-Bigarrays-include" 20.10.1  Include file-->
<h3 class="subsection" id="ss:C-Bigarrays-include"><a class="section-anchor" href="#ss:C-Bigarrays-include" aria-hidden="true"></a>20.10.1  Include file</h3><!--SEC END --><p>The include file <span class="c003">&lt;caml/bigarray.h&gt;</span> must be included in the C stub
file. It declares the functions, constants and macros discussed
below.</p>
<!--TOC subsection id="ss:C-Bigarrays-access" 20.10.2  Accessing an OCaml bigarray from C or Fortran-->
<h3 class="subsection" id="ss:C-Bigarrays-access"><a class="section-anchor" href="#ss:C-Bigarrays-access" aria-hidden="true"></a>20.10.2  Accessing an OCaml bigarray from C or Fortran</h3><!--SEC END --><p>If <span class="c009">v</span> is a OCaml <span class="c003">value</span> representing a Bigarray, the expression
<span class="c003">Caml_ba_data_val(</span><span class="c009">v</span><span class="c003">)</span> returns a pointer to the data part of the array.
This pointer is of type <span class="c003">void *</span> and can be cast to the appropriate C
type for the array (e.g. <span class="c003">double []</span>, <span class="c003">char [][10]</span>, etc).</p><p>Various characteristics of the OCaml Bigarray can be consulted from C
as follows:
</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">C expression</span></td><td class="c014"><span class="c013">Returns</span> </td></tr>
<tr><td class="c016">
<span class="c003">Caml_ba_array_val(</span><span class="c009">v</span><span class="c003">)-&gt;num_dims</span></td><td class="c016">number of dimensions </td></tr>
<tr><td class="c016"><span class="c003">Caml_ba_array_val(</span><span class="c009">v</span><span class="c003">)-&gt;dim[</span><span class="c009">i</span><span class="c003">]</span></td><td class="c016"><span class="c009">i</span>-th dimension </td></tr>
<tr><td class="c016"><span class="c003">Caml_ba_array_val(</span><span class="c009">v</span><span class="c003">)-&gt;flags &amp; BIGARRAY_KIND_MASK</span></td><td class="c016">kind of array elements </td></tr>
</table></div></div><p>
The kind of array elements is one of the following constants:
</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Constant</span></td><td class="c014"><span class="c013">Element kind</span> </td></tr>
<tr><td class="c016">
<span class="c003">CAML_BA_FLOAT32</span></td><td class="c016">32-bit single-precision floats </td></tr>
<tr><td class="c016"><span class="c003">CAML_BA_FLOAT64</span></td><td class="c016">64-bit double-precision floats </td></tr>
<tr><td class="c016"><span class="c003">CAML_BA_SINT8</span></td><td class="c016">8-bit signed integers </td></tr>
<tr><td class="c016"><span class="c003">CAML_BA_UINT8</span></td><td class="c016">8-bit unsigned integers </td></tr>
<tr><td class="c016"><span class="c003">CAML_BA_SINT16</span></td><td class="c016">16-bit signed integers </td></tr>
<tr><td class="c016"><span class="c003">CAML_BA_UINT16</span></td><td class="c016">16-bit unsigned integers </td></tr>
<tr><td class="c016"><span class="c003">CAML_BA_INT32</span></td><td class="c016">32-bit signed integers </td></tr>
<tr><td class="c016"><span class="c003">CAML_BA_INT64</span></td><td class="c016">64-bit signed integers </td></tr>
<tr><td class="c016"><span class="c003">CAML_BA_CAML_INT</span></td><td class="c016">31- or 63-bit signed integers </td></tr>
<tr><td class="c016"><span class="c003">CAML_BA_NATIVE_INT</span></td><td class="c016">32- or 64-bit (platform-native) integers </td></tr>
</table></div></div><p>
The following example shows the passing of a two-dimensional Bigarray
to a C function and a Fortran function.
</p><pre>    extern void my_c_function(double * data, int dimx, int dimy);
    extern void my_fortran_function_(double * data, int * dimx, int * dimy);

    value caml_stub(value bigarray)
    {
      int dimx = Caml_ba_array_val(bigarray)-&gt;dim[0];
      int dimy = Caml_ba_array_val(bigarray)-&gt;dim[1];
      /* C passes scalar parameters by value */
      my_c_function(Caml_ba_data_val(bigarray), dimx, dimy);
      /* Fortran passes all parameters by reference */
      my_fortran_function_(Caml_ba_data_val(bigarray), &amp;dimx, &amp;dimy);
      return Val_unit;
    }
</pre>
<!--TOC subsection id="ss:C-Bigarrays-wrap" 20.10.3  Wrapping a C or Fortran array as an OCaml Bigarray-->
<h3 class="subsection" id="ss:C-Bigarrays-wrap"><a class="section-anchor" href="#ss:C-Bigarrays-wrap" aria-hidden="true"></a>20.10.3  Wrapping a C or Fortran array as an OCaml Bigarray</h3><!--SEC END --><p>A pointer <span class="c009">p</span> to an already-allocated C or Fortran array can be
wrapped and returned to OCaml as a Bigarray using the <span class="c003">caml_ba_alloc</span>
or <span class="c003">caml_ba_alloc_dims</span> functions.
</p><ul class="itemize"><li class="li-itemize">
<span class="c003">caml_ba_alloc(</span><span class="c009">kind</span> <span class="c003">|</span> <span class="c009">layout</span>, <span class="c009">numdims</span>, <span class="c009">p</span>, <span class="c009">dims</span><span class="c003">)</span><p>Return an OCaml Bigarray wrapping the data pointed to by <span class="c009">p</span>.
<span class="c009">kind</span> is the kind of array elements (one of the <span class="c003">CAML_BA_</span>
kind constants above). <span class="c009">layout</span> is <span class="c003">CAML_BA_C_LAYOUT</span> for an
array with C layout and <span class="c003">CAML_BA_FORTRAN_LAYOUT</span> for an array with
Fortran layout. <span class="c009">numdims</span> is the number of dimensions in the
array. <span class="c009">dims</span> is an array of <span class="c009">numdims</span> long integers, giving
the sizes of the array in each dimension.</p></li><li class="li-itemize"><span class="c003">caml_ba_alloc_dims(</span><span class="c009">kind</span> <span class="c003">|</span> <span class="c009">layout</span>, <span class="c009">numdims</span>,
<span class="c009">p</span>, <span class="c003">(long) </span><span class="c009">dim</span><sub>1</sub>, <span class="c003">(long) </span><span class="c009">dim</span><sub>2</sub>, …, <span class="c003">(long) </span><span class="c009">dim</span><sub><span class="c009">numdims</span></sub><span class="c003">)</span><p>Same as <span class="c003">caml_ba_alloc</span>, but the sizes of the array in each dimension
are listed as extra arguments in the function call, rather than being
passed as an array.
</p></li></ul><p>
The following example illustrates how statically-allocated C and
Fortran arrays can be made available to OCaml.
</p><pre>    extern long my_c_array[100][200];
    extern float my_fortran_array_[300][400];

    value caml_get_c_array(value unit)
    {
      long dims[2];
      dims[0] = 100; dims[1] = 200;
      return caml_ba_alloc(CAML_BA_NATIVE_INT | CAML_BA_C_LAYOUT,
                           2, my_c_array, dims);
    }

    value caml_get_fortran_array(value unit)
    {
      return caml_ba_alloc_dims(CAML_BA_FLOAT32 | CAML_BA_FORTRAN_LAYOUT,
                                2, my_fortran_array_, 300L, 400L);
    }
</pre>
<!--TOC section id="s:C-cheaper-call" 20.11  Advanced topic: cheaper C call-->
<h2 class="section" id="s:C-cheaper-call"><a class="section-anchor" href="#s:C-cheaper-call" aria-hidden="true"></a>20.11  Advanced topic: cheaper C call</h2><!--SEC END --><p>This section describe how to make calling C functions cheaper.</p><p><span class="c013">Note:</span> this only applies to the native compiler. So whenever you
use any of these methods, you have to provide an alternative byte-code
stub that ignores all the special annotations.</p>
<!--TOC subsection id="ss:c-unboxed" 20.11.1  Passing unboxed values-->
<h3 class="subsection" id="ss:c-unboxed"><a class="section-anchor" href="#ss:c-unboxed" aria-hidden="true"></a>20.11.1  Passing unboxed values</h3><!--SEC END --><p>We said earlier that all OCaml objects are represented by the C type
<span class="c003">value</span>, and one has to use macros such as <span class="c003">Int_val</span> to decode data from
the <span class="c003">value</span> type. It is however possible to tell the OCaml native-code
compiler to do this for us and pass arguments unboxed to the C function.
Similarly it is possible to tell OCaml to expect the result unboxed and box
it for us.</p><p>The motivation is that, by letting ‘ocamlopt‘ deal with boxing, it can
often decide to suppress it entirely.</p><p>For instance let’s consider this example:</p><pre>external foo : float -&gt; float -&gt; float = "foo"

let f a b =
  let len = Array.length a in
  assert (Array.length b = len);
  let res = Array.make len 0. in
  for i = 0 to len - 1 do
    res.(i) &lt;- foo a.(i) b.(i)
  done
</pre><p>
Float arrays are unboxed in OCaml, however the C function <span class="c003">foo</span> expect
its arguments as boxed floats and returns a boxed float. Hence the
OCaml compiler has no choice but to box <span class="c003">a.(i)</span> and <span class="c003">b.(i)</span> and unbox
the result of <span class="c003">foo</span>. This results in the allocation of <span class="c003">3 * len</span>
temporary float values.</p><p>Now if we annotate the arguments and result with <span class="c003">[@unboxed]</span>, the
native-code compiler will be able to avoid all these allocations:</p><pre>external foo
  :  (float [@unboxed])
  -&gt; (float [@unboxed])
  -&gt; (float [@unboxed])
  = "foo_byte" "foo"
</pre><p>
In this case the C functions must look like:</p><pre>CAMLprim double foo(double a, double b)
{
  ...
}

CAMLprim value foo_byte(value a, value b)
{
  return caml_copy_double(foo(Double_val(a), Double_val(b)))
}
</pre><p>
For convenicence, when all arguments and the result are annotated with
<span class="c003">[@unboxed]</span>, it is possible to put the attribute only once on the
declaration itself. So we can also write instead:</p><pre>external foo : float -&gt; float -&gt; float = "foo_byte" "foo" [@@unboxed]
</pre><p>
The following table summarize what OCaml types can be unboxed, and
what C types should be used in correspondence:</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">OCaml type</span></td><td class="c014"><span class="c013">C type</span> </td></tr>
<tr><td class="c016">
<span class="c003">float</span></td><td class="c016"><span class="c003">double</span> </td></tr>
<tr><td class="c016"><span class="c003">int32</span></td><td class="c016"><span class="c003">int32_t</span> </td></tr>
<tr><td class="c016"><span class="c003">int64</span></td><td class="c016"><span class="c003">int64_t</span> </td></tr>
<tr><td class="c016"><span class="c003">nativeint</span></td><td class="c016"><span class="c003">intnat</span> </td></tr>
</table></div></div><p>Similarly, it is possible to pass untagged OCaml integers between
OCaml and C. This is done by annotating the arguments and/or result
with <span class="c003">[@untagged]</span>:</p><pre>external f : string -&gt; (int [@untagged]) = "f_byte" "f"
</pre><p>
The corresponding C type must be <span class="c003">intnat</span>.</p><p><span class="c013">Note:</span> do not use the C <span class="c003">int</span> type in correspondence with <span class="c003">(int [@untagged])</span>. This is because they often differ in size.</p>
<!--TOC subsection id="ss:c-direct-call" 20.11.2  Direct C call-->
<h3 class="subsection" id="ss:c-direct-call"><a class="section-anchor" href="#ss:c-direct-call" aria-hidden="true"></a>20.11.2  Direct C call</h3><!--SEC END --><p>In order to be able to run the garbage collector in the middle of
a C function, the OCaml native-code compiler generates some bookkeeping
code around C calls. Technically it wraps every C call with the C function
<span class="c003">caml_c_call</span> which is part of the OCaml runtime.</p><p>For small functions that are called repeatedly, this indirection can have
a big impact on performances. However this is not needed if we know that
the C function doesn’t allocate, doesn’t raise exceptions, and doesn’t release
the master lock (see section <a href="#ss%3Aparallel-execution-long-running-c-code">20.12.2</a>). 
We can instruct the OCaml native-code compiler of this fact by annotating the
external declaration with the attribute <span class="c003">[@@noalloc]</span>:</p><pre>external bar : int -&gt; int -&gt; int = "foo" [@@noalloc]
</pre><p>
In this case calling <span class="c003">bar</span> from OCaml is as cheap as calling any other
OCaml function, except for the fact that the OCaml compiler can’t
inline C functions...</p>
<!--TOC subsection id="ss:c-direct-call-example" 20.11.3  Example: calling C library functions without indirection-->
<h3 class="subsection" id="ss:c-direct-call-example"><a class="section-anchor" href="#ss:c-direct-call-example" aria-hidden="true"></a>20.11.3  Example: calling C library functions without indirection</h3><!--SEC END --><p>Using these attributes, it is possible to call C library functions
with no indirection. For instance many math functions are defined this
way in the OCaml standard library:</p><pre>external sqrt : float -&gt; float = "caml_sqrt_float" "sqrt"
  [@@unboxed] [@@noalloc]
(** Square root. *)

external exp : float -&gt; float = "caml_exp_float" "exp" [@@unboxed] [@@noalloc]
(** Exponential. *)

external log : float -&gt; float = "caml_log_float" "log" [@@unboxed] [@@noalloc]
(** Natural logarithm. *)
</pre>
<!--TOC section id="s:C-multithreading" 20.12  Advanced topic: multithreading-->
<h2 class="section" id="s:C-multithreading"><a class="section-anchor" href="#s:C-multithreading" aria-hidden="true"></a>20.12  Advanced topic: multithreading</h2><!--SEC END --><p>Using multiple threads (shared-memory concurrency) in a mixed OCaml/C
application requires special precautions, which are described in this
section.</p>
<!--TOC subsection id="ss:c-thread-register" 20.12.1  Registering threads created from C-->
<h3 class="subsection" id="ss:c-thread-register"><a class="section-anchor" href="#ss:c-thread-register" aria-hidden="true"></a>20.12.1  Registering threads created from C</h3><!--SEC END --><p>Callbacks from C to OCaml are possible only if the calling thread is
known to the OCaml run-time system. Threads created from OCaml (through
the <span class="c003">Thread.create</span> function of the system threads library) are
automatically known to the run-time system. If the application
creates additional threads from C and wishes to callback into OCaml
code from these threads, it must first register them with the run-time
system. The following functions are declared in the include file
<span class="c003">&lt;caml/threads.h&gt;</span>.</p><ul class="itemize"><li class="li-itemize">
<span class="c003">caml_c_thread_register()</span> registers the calling thread with the OCaml
run-time system. Returns 1 on success, 0 on error. Registering an
already-registered thread does nothing and returns 0.
</li><li class="li-itemize"><span class="c003">caml_c_thread_unregister()</span> must be called before the thread
terminates, to unregister it from the OCaml run-time system.
Returns 1 on success, 0 on error. If the calling thread was not
previously registered, does nothing and returns 0.
</li></ul>
<!--TOC subsection id="ss:parallel-execution-long-running-c-code" 20.12.2  Parallel execution of long-running C code-->
<h3 class="subsection" id="ss:parallel-execution-long-running-c-code"><a class="section-anchor" href="#ss:parallel-execution-long-running-c-code" aria-hidden="true"></a>20.12.2  Parallel execution of long-running C code</h3><!--SEC END --><p>The OCaml run-time system is not reentrant: at any time, at most one
thread can be executing OCaml code or C code that uses the OCaml
run-time system. Technically, this is enforced by a “master lock”
that any thread must hold while executing such code.</p><p>When OCaml calls the C code implementing a primitive, the master lock
is held, therefore the C code has full access to the facilities of the
run-time system. However, no other thread can execute OCaml code
concurrently with the C code of the primitive.</p><p>If a C primitive runs for a long time or performs potentially blocking
input-output operations, it can explicitly release the master lock,
enabling other OCaml threads to run concurrently with its operations.
The C code must re-acquire the master lock before returning to OCaml.
This is achieved with the following functions, declared in
the include file <span class="c003">&lt;caml/threads.h&gt;</span>.</p><ul class="itemize"><li class="li-itemize">
<span class="c003">caml_release_runtime_system()</span>
The calling thread releases the master lock and other OCaml resources,
enabling other threads to run OCaml code in parallel with the execution
of the calling thread.
</li><li class="li-itemize"><span class="c003">caml_acquire_runtime_system()</span>
The calling thread re-acquires the master lock and other OCaml
resources. It may block until no other thread uses the OCaml run-time
system.
</li></ul><p>These functions poll for pending signals by calling asynchronous
callbacks (section <a href="#ss%3Ac-process-pending-actions">20.5.3</a>) before releasing and
after acquiring the lock. They can therefore execute arbitrary OCaml
code including raising an asynchronous exception.</p><p>After <span class="c003">caml_release_runtime_system()</span> was called and until
<span class="c003">caml_acquire_runtime_system()</span> is called, the C code must not access
any OCaml data, nor call any function of the run-time system, nor call
back into OCaml code. Consequently, arguments provided by OCaml to the
C primitive must be copied into C data structures before calling
<span class="c003">caml_release_runtime_system()</span>, and results to be returned to OCaml
must be encoded as OCaml values after <span class="c003">caml_acquire_runtime_system()</span>
returns.</p><p>Example: the following C primitive invokes <span class="c003">gethostbyname</span> to find the
IP address of a host name. The <span class="c003">gethostbyname</span> function can block for
a long time, so we choose to release the OCaml run-time system while it
is running.
</p><pre>CAMLprim stub_gethostbyname(value vname)
{
  CAMLparam1 (vname);
  CAMLlocal1 (vres);
  struct hostent * h;
  char * name;

  /* Copy the string argument to a C string, allocated outside the
     OCaml heap. */
  name = caml_stat_strdup(String_val(vname));
  /* Release the OCaml run-time system */
  caml_release_runtime_system();
  /* Resolve the name */
  h = gethostbyname(name);
  /* Free the copy of the string, which we might as well do before
     acquiring the runtime system to benefit from parallelism. */
  caml_stat_free(name);
  /* Re-acquire the OCaml run-time system */
  caml_acquire_runtime_system();
  /* Encode the relevant fields of h as the OCaml value vres */
  ... /* Omitted */
  /* Return to OCaml */
  CAMLreturn (vres);
}
</pre><p>
Callbacks from C to OCaml must be performed while holding the master
lock to the OCaml run-time system. This is naturally the case if the
callback is performed by a C primitive that did not release the
run-time system. If the C primitive released the run-time system
previously, or the callback is performed from other C code that was
not invoked from OCaml (e.g. an event loop in a GUI application), the
run-time system must be acquired before the callback and released
after:
</p><pre>  caml_acquire_runtime_system();
  /* Resolve OCaml function vfun to be invoked */
  /* Build OCaml argument varg to the callback */
  vres = callback(vfun, varg);
  /* Copy relevant parts of result vres to C data structures */
  caml_release_runtime_system();
</pre><p>
Note: the <span class="c003">acquire</span> and <span class="c003">release</span> functions described above were
introduced in OCaml 3.12. Older code uses the following historical
names, declared in <span class="c003">&lt;caml/signals.h&gt;</span>:
</p><ul class="itemize"><li class="li-itemize">
<span class="c003">caml_enter_blocking_section</span> as an alias for
<span class="c003">caml_release_runtime_system</span>
</li><li class="li-itemize"><span class="c003">caml_leave_blocking_section</span> as an alias for
<span class="c003">caml_acquire_runtime_system</span>
</li></ul><p>
Intuition: a “blocking section” is a piece of C code that does not
use the OCaml run-time system, typically a blocking input/output operation.</p>
<!--TOC section id="s:interfacing-windows-unicode-apis" 20.13  Advanced topic: interfacing with Windows Unicode APIs-->
<h2 class="section" id="s:interfacing-windows-unicode-apis"><a class="section-anchor" href="#s:interfacing-windows-unicode-apis" aria-hidden="true"></a>20.13  Advanced topic: interfacing with Windows Unicode APIs</h2><!--SEC END --><p>This section contains some general guidelines for writing C stubs that use
Windows Unicode APIs.</p><p><span class="c013">Note:</span> This is an experimental feature of OCaml: the set of APIs below, as
well as their exact semantics are not final and subject to change in future
releases.</p><p>The OCaml system under Windows can be configured at build time in one of two
modes:</p><ul class="itemize"><li class="li-itemize"><span class="c013">legacy mode:</span> All path names, environment variables, command line
arguments, etc. on the OCaml side are assumed to be encoded using the current
8-bit code page of the system.</li><li class="li-itemize"><span class="c013">Unicode mode:</span> All path names, environment variables, command line
arguments, etc. on the OCaml side are assumed to be encoded using UTF-8.</li></ul><p>In what follows, we say that a string has the <em>OCaml encoding</em> if it is
encoded in UTF-8 when in Unicode mode, in the current code page in legacy mode,
or is an arbitrary string under Unix. A string has the <em>platform encoding</em>
if it is encoded in UTF-16 under Windows or is an arbitrary string under Unix.</p><p>From the point of view of the writer of C stubs, the challenges of interacting
with Windows Unicode APIs are twofold:</p><ul class="itemize"><li class="li-itemize">The Windows API uses the UTF-16 encoding to support Unicode. The runtime
system performs the necessary conversions so that the OCaml programmer only
needs to deal with the OCaml encoding. C stubs that call Windows Unicode APIs
need to use specific runtime functions to perform the necessary conversions in a
compatible way.</li><li class="li-itemize">When writing stubs that need to be compiled under both Windows and Unix,
the stubs need to be written in a way that allow the necessary conversions under
Windows but that also work under Unix, where typically nothing particular needs
to be done to support Unicode.</li></ul><p>The native C character type under Windows is <span class="c003">WCHAR</span>, two bytes wide, while
under Unix it is <span class="c003">char</span>, one byte wide. A type <span class="c003">char_os</span> is defined in
<span class="c003">&lt;caml/misc.h&gt;</span> that stands for the concrete C character type of each
platform. Strings in the platform encoding are of type <span class="c003">char_os *</span>.</p><p>The following functions are exposed to help write compatible C stubs. To use
them, you need to include both <span class="c003">&lt;caml/misc.h&gt;</span> and <span class="c003">&lt;caml/osdeps.h&gt;</span>.</p><ul class="itemize"><li class="li-itemize"><span class="c003">char_os* caml_stat_strdup_to_os(const char *)</span> copies the argument while
translating from OCaml encoding to the platform encoding. This function is
typically used to convert the <span class="c003">char *</span> underlying an OCaml string before passing
it to an operating system API that takes a Unicode argument. Under Unix, it is
equivalent to <span class="c003">caml_stat_strdup</span>.<p><span class="c013">Note:</span> For maximum backwards compatibility in Unicode mode, if the argument
is not a valid UTF-8 string, this function will fall back to assuming that it is
encoded in the current code page.</p></li><li class="li-itemize"><span class="c003">char* caml_stat_strdup_of_os(const char_os *)</span> copies the argument while
translating from the platform encoding to the OCaml encoding. It is the inverse
of <span class="c003">caml_stat_strdup_to_os</span>. This function is typically used to convert a string
obtained from the operating system before passing it on to OCaml code. Under
Unix, it is equivalent to <span class="c003">caml_stat_strdup</span>.</li><li class="li-itemize"><span class="c003">value caml_copy_string_of_os(char_os *)</span> allocates an OCaml string with
contents equal to the argument string converted to the OCaml encoding. This
function is essentially equivalent to <span class="c003">caml_stat_strdup_of_os</span> followed by
<span class="c003">caml_copy_string</span>, except that it avoids the allocation of the intermediate
string returned by <span class="c003">caml_stat_strdup_of_os</span>. Under Unix, it is equivalent to
<span class="c003">caml_copy_string</span>.</li></ul><p><span class="c013">Note:</span> The strings returned by <span class="c003">caml_stat_strdup_to_os</span> and
<span class="c003">caml_stat_strdup_of_os</span> are allocated using <span class="c003">caml_stat_alloc</span>, so they need to
be deallocated using <span class="c003">caml_stat_free</span> when they are no longer needed.</p>
<!--TOC paragraph id="sec489" Example-->
<h5 class="paragraph" id="sec489"><a class="section-anchor" href="#sec489" aria-hidden="true"></a>Example</h5><!--SEC END --><p> We want to bind the function <span class="c003">getenv</span> in a way that works
both under Unix and Windows. Under Unix this function has the prototype:</p><pre>    char *getenv(const char *);
</pre><p>While the Unicode version under Windows has the prototype:
</p><pre>    WCHAR *_wgetenv(const WCHAR *);
</pre><p>
In terms of <span class="c003">char_os</span>, both functions take an argument of type <span class="c003">char_os *</span> and
return a result of the same type. We begin by choosing the right implementation
of the function to bind:</p><pre>#ifdef _WIN32
#define getenv_os _wgetenv
#else
#define getenv_os getenv
#endif
</pre><p>
The rest of the binding is the same for both platforms:</p><pre>/* The following define is necessary because the API is experimental */
#define CAML_NAME_SPACE
#define CAML_INTERNALS

#include &lt;caml/mlvalues.h&gt;
#include &lt;caml/misc.h&gt;
#include &lt;caml/alloc.h&gt;
#include &lt;caml/fail.h&gt;
#include &lt;caml/osdeps.h&gt;
#include &lt;stdlib.h&gt;

CAMLprim value stub_getenv(value var_name)
{
  CAMLparam1(var_name);
  CAMLlocal1(var_value);
  char_os *var_name_os, *var_value_os;

  var_name_os = caml_stat_strdup_to_os(String_val(var_name));
  var_value_os = getenv_os(var_name_os);
  caml_stat_free(var_name_os);

  if (var_value_os == NULL)
    caml_raise_not_found();

  var_value = caml_copy_string_of_os(var_value_os);

  CAMLreturn(var_value);
}
</pre>
<!--TOC section id="s:ocamlmklib" 20.14  Building mixed C/OCaml libraries: <span class="c003">ocamlmklib</span>-->
<h2 class="section" id="s:ocamlmklib"><a class="section-anchor" href="#s:ocamlmklib" aria-hidden="true"></a>20.14  Building mixed C/OCaml libraries: <span class="c003">ocamlmklib</span></h2><!--SEC END --><p>The <span class="c003">ocamlmklib</span> command facilitates the construction of libraries
containing both OCaml code and C code, and usable both in static
linking and dynamic linking modes. This command is available under
Windows since Objective Caml 3.11 and under other operating systems since
Objective Caml 3.03.</p><p>The <span class="c003">ocamlmklib</span> command takes three kinds of arguments:
</p><ul class="itemize"><li class="li-itemize">
OCaml source files and object files (<span class="c003">.cmo</span>, <span class="c003">.cmx</span>, <span class="c003">.ml</span>)
comprising the OCaml part of the library;
</li><li class="li-itemize">C object files (<span class="c003">.o</span>, <span class="c003">.a</span>, respectively, <span class="c003">.obj</span>, <span class="c003">.lib</span>)
comprising the C part of the library;
</li><li class="li-itemize">Support libraries for the C part (<span class="c003">-l</span><span class="c009">lib</span>).
</li></ul><p>
It generates the following outputs:
</p><ul class="itemize"><li class="li-itemize">
An OCaml bytecode library <span class="c003">.cma</span> incorporating the <span class="c003">.cmo</span> and
<span class="c003">.ml</span> OCaml files given as arguments, and automatically referencing the
C library generated with the C object files.
</li><li class="li-itemize">An OCaml native-code library <span class="c003">.cmxa</span> incorporating the <span class="c003">.cmx</span> and
<span class="c003">.ml</span> OCaml files given as arguments, and automatically referencing the
C library generated with the C object files.
</li><li class="li-itemize">If dynamic linking is supported on the target platform, a
<span class="c003">.so</span> (respectively, <span class="c003">.dll</span>) shared library built from the C object files given as arguments,
and automatically referencing the support libraries.
</li><li class="li-itemize">A C static library <span class="c003">.a</span>(respectively, <span class="c003">.lib</span>) built from the C object files.
</li></ul><p>
In addition, the following options are recognized:
</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">-cclib</span>, <span class="c003">-ccopt</span>, <span class="c003">-I</span>, <span class="c003">-linkall</span></span></dt><dd class="dd-description">
These options are passed as is to <span class="c003">ocamlc</span> or <span class="c003">ocamlopt</span>.
See the documentation of these commands.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-rpath</span>, <span class="c003">-R</span>, <span class="c003">-Wl,-rpath</span>, <span class="c003">-Wl,-R</span></span></dt><dd class="dd-description">
These options are passed as is to the C compiler. Refer to the
documentation of the C compiler.
</dd><dt class="dt-description"><span class="c006">-custom</span></dt><dd class="dd-description"> Force the construction of a statically linked library
only, even if dynamic linking is supported.
</dd><dt class="dt-description"><span class="c006">-failsafe</span></dt><dd class="dd-description"> Fall back to building a statically linked library
if a problem occurs while building the shared library (e.g. some of
the support libraries are not available as shared libraries).
</dd><dt class="dt-description"><span class="c013"><span class="c003">-L</span><span class="c009">dir</span></span></dt><dd class="dd-description"> Add <span class="c009">dir</span> to the search path for support
libraries (<span class="c003">-l</span><span class="c009">lib</span>).
</dd><dt class="dt-description"><span class="c013"><span class="c003">-ocamlc</span> <span class="c009">cmd</span></span></dt><dd class="dd-description"> Use <span class="c009">cmd</span> instead of <span class="c003">ocamlc</span> to call
the bytecode compiler.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-ocamlopt</span> <span class="c009">cmd</span></span></dt><dd class="dd-description"> Use <span class="c009">cmd</span> instead of <span class="c003">ocamlopt</span> to call
the native-code compiler.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-o</span> <span class="c009">output</span></span></dt><dd class="dd-description"> Set the name of the generated OCaml library.
<span class="c003">ocamlmklib</span> will generate <span class="c009">output</span><span class="c003">.cma</span> and/or <span class="c009">output</span><span class="c003">.cmxa</span>.
If not specified, defaults to <span class="c003">a</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">-oc</span> <span class="c009">outputc</span></span></dt><dd class="dd-description"> Set the name of the generated C library.
<span class="c003">ocamlmklib</span> will generate <span class="c003">lib</span><span class="c009">outputc</span><span class="c003">.so</span> (if shared
libraries are supported) and <span class="c003">lib</span><span class="c009">outputc</span><span class="c003">.a</span>.
If not specified, defaults to the output name given with <span class="c003">-o</span>.
</dd></dl><p>On native Windows, the following environment variable is also consulted:</p><dl class="description"><dt class="dt-description">
<span class="c006">OCAML_FLEXLINK</span></dt><dd class="dd-description"> Alternative executable to use instead of the
configured value. Primarily used for bootstrapping.
</dd></dl>
<!--TOC paragraph id="sec491" Example-->
<h5 class="paragraph" id="sec491"><a class="section-anchor" href="#sec491" aria-hidden="true"></a>Example</h5><!--SEC END --><p> Consider an OCaml interface to the standard <span class="c003">libz</span>
C library for reading and writing compressed files. Assume this
library resides in <span class="c003">/usr/local/zlib</span>. This interface is
composed of an OCaml part <span class="c003">zip.cmo</span>/<span class="c003">zip.cmx</span> and a C part <span class="c003">zipstubs.o</span>
containing the stub code around the <span class="c003">libz</span> entry points. The
following command builds the OCaml libraries <span class="c003">zip.cma</span> and <span class="c003">zip.cmxa</span>,
as well as the companion C libraries <span class="c003">dllzip.so</span> and <span class="c003">libzip.a</span>:
</p><pre>ocamlmklib -o zip zip.cmo zip.cmx zipstubs.o -lz -L/usr/local/zlib
</pre><p>If shared libraries are supported, this performs the following
commands:
</p><pre>ocamlc -a -o zip.cma zip.cmo -dllib -lzip \
        -cclib -lzip -cclib -lz -ccopt -L/usr/local/zlib
ocamlopt -a -o zip.cmxa zip.cmx -cclib -lzip \
        -cclib -lzip -cclib -lz -ccopt -L/usr/local/zlib
gcc -shared -o dllzip.so zipstubs.o -lz -L/usr/local/zlib
ar rc libzip.a zipstubs.o
</pre><p>Note: This example is on a Unix system. The exact command lines
may be different on other systems.</p><p>If shared libraries are not supported, the following commands are
performed instead:
</p><pre>ocamlc -a -custom -o zip.cma zip.cmo -cclib -lzip \
        -cclib -lz -ccopt -L/usr/local/zlib
ocamlopt -a -o zip.cmxa zip.cmx -lzip \
        -cclib -lz -ccopt -L/usr/local/zlib
ar rc libzip.a zipstubs.o
</pre><p>Instead of building simultaneously the bytecode library, the
native-code library and the C libraries, <span class="c003">ocamlmklib</span> can be called
three times to build each separately. Thus,
</p><pre>ocamlmklib -o zip zip.cmo -lz -L/usr/local/zlib
</pre><p>builds the bytecode library <span class="c003">zip.cma</span>, and
</p><pre>ocamlmklib -o zip zip.cmx -lz -L/usr/local/zlib
</pre><p>builds the native-code library <span class="c003">zip.cmxa</span>, and
</p><pre>ocamlmklib -o zip zipstubs.o -lz -L/usr/local/zlib
</pre><p>builds the C libraries <span class="c003">dllzip.so</span> and <span class="c003">libzip.a</span>. Notice that the
support libraries (<span class="c003">-lz</span>) and the corresponding options
(<span class="c003">-L/usr/local/zlib</span>) must be given on all three invocations of <span class="c003">ocamlmklib</span>,
because they are needed at different times depending on whether shared
libraries are supported.</p>
<!--TOC section id="s:c-internal-guidelines" 20.15  Cautionary words: the internal runtime API-->
<h2 class="section" id="s:c-internal-guidelines"><a class="section-anchor" href="#s:c-internal-guidelines" aria-hidden="true"></a>20.15  Cautionary words: the internal runtime API</h2><!--SEC END --><p>Not all header available in the <span class="c003">caml/</span> directory were described in previous
sections. All those unmentioned headers are part of the internal runtime API,
for which there is <em>no</em> stability guarantee. If you really need access
to this internal runtime API, this section provides some guidelines
that may help you to write code that might not break on every new version
of OCaml.
</p>
<!--TOC paragraph id="sec493" Note-->
<h5 class="paragraph" id="sec493"><a class="section-anchor" href="#sec493" aria-hidden="true"></a>Note</h5><!--SEC END --><p> Programmers which come to rely on the internal API
for a use-case which they find realistic and useful are encouraged to open
a request for improvement on the bug tracker.</p>
<!--TOC subsection id="ss:c-internals" 20.15.1  Internal variables and CAML_INTERNALS-->
<h3 class="subsection" id="ss:c-internals"><a class="section-anchor" href="#ss:c-internals" aria-hidden="true"></a>20.15.1  Internal variables and CAML_INTERNALS</h3><!--SEC END --><p>
Since OCaml 4.04, it is possible to get access to every part of the internal
runtime API by defining the <span class="c003">CAML_INTERNALS</span> macro before loading caml header files.
If this macro is not defined, parts of the internal runtime API are hidden.</p><p>If you are using internal C variables, do not redefine them by hand. You should
import those variables by including the corresponding header files. The
representation of those variables has already changed once in OCaml 4.10, and is
still under evolution.
If your code relies on such internal and brittle properties, it will be broken
at some point in time.</p><p>For instance, rather than redefining <span class="c003">caml_young_limit</span>:
</p><pre>extern int caml_young_limit;
</pre><p>which breaks in OCaml ≥ 4.10, you should include the <span class="c003">minor_gc</span> header:
</p><pre>#include &lt;caml/minor_gc.h&gt;
</pre>
<!--TOC subsection id="ss:c-internal-macros" 20.15.2  OCaml version macros-->
<h3 class="subsection" id="ss:c-internal-macros"><a class="section-anchor" href="#ss:c-internal-macros" aria-hidden="true"></a>20.15.2  OCaml version macros</h3><!--SEC END --><p>
Finally, if including the right headers is not enough, or if you need to support
version older than OCaml 4.04, the header file <span class="c003">caml/version.h</span> should help
you to define your own compatibility layer.
This file provides few macros defining the current OCaml version.
In particular, the <span class="c003">OCAML_VERSION</span> macro describes the current version,
its format is <span class="c003">MmmPP</span>.
For example, if you need some specific handling for versions older than 4.10.0,
you could write
</p><pre>#include &lt;caml/version.h&gt;
#if OCAML_VERSION &gt;= 41000
...
#else
...
#endif
</pre>
<!--TOC chapter id="sec496" Chapter 21  Optimisation with Flambda-->
<h1 class="chapter" id="sec496">Chapter 21  Optimisation with Flambda</h1><!--SEC END --><!--NAME flambda.html-->

<!--TOC section id="s:flambda-overview" 21.1  Overview-->
<h2 class="section" id="s:flambda-overview"><a class="section-anchor" href="#s:flambda-overview" aria-hidden="true"></a>21.1  Overview</h2><!--SEC END --><p><em>Flambda</em> is the term used to describe a series of optimisation passes
provided by the native code compilers as of OCaml 4.03.</p><p>Flambda aims to make it easier to write idiomatic OCaml code without
incurring performance penalties.</p><p>To use the Flambda optimisers it is necessary to pass the <span class="c003">-flambda</span>
option to the OCaml <span class="c003">configure</span> script. (There is no support for a
single compiler that can operate in both Flambda and non-Flambda modes.)
Code compiled with Flambda
cannot be linked into the same program as code compiled without Flambda.
Attempting to do this will result in a compiler error.</p><p>Whether or not a particular <span class="c003">ocamlopt</span> uses Flambda may be
determined by invoking it with the <span class="c003">-config</span> option and looking
for any line starting with “<span class="c003">flambda:</span>”. If such a line is present
and says “<span class="c003">true</span>”, then Flambda is supported, otherwise it is not.</p><p>Flambda provides full optimisation across different compilation units,
so long as the <span class="c003">.cmx</span> files for the dependencies of the unit currently
being compiled are available. (A compilation unit corresponds to a
single <span class="c003">.ml</span> source file.) However it does not yet act entirely as
a whole-program compiler: for example, elimination of dead code across
a complete set of compilation units is not supported.</p><p>Optimisation with Flambda is not currently supported when generating
bytecode.</p><p>Flambda should not in general affect the semantics of existing programs.
Two exceptions to this rule are: possible elimination of pure code
that is being benchmarked (see section <a href="#s%3Aflambda-inhibition">21.14</a>) and changes in
behaviour of code using unsafe operations (see section <a href="#s%3Aflambda-unsafe">21.15</a>).</p><p>Flambda does not yet optimise array or string bounds checks. Neither
does it take hints for optimisation from any assertions written by the
user in the code.</p><p>Consult the <em>Glossary</em> at the end of this chapter for definitions of
technical terms used below.</p>
<!--TOC section id="s:flambda-cli" 21.2  Command-line flags-->
<h2 class="section" id="s:flambda-cli"><a class="section-anchor" href="#s:flambda-cli" aria-hidden="true"></a>21.2  Command-line flags</h2><!--SEC END --><p>The Flambda optimisers provide a variety of command-line flags that may
be used to control their behaviour. Detailed descriptions of each flag
are given in the referenced sections. Those sections also describe any
arguments which the particular flags take.</p><p>Commonly-used options:
</p><dl class="description"><dt class="dt-description">
<span class="c006">-O2</span></dt><dd class="dd-description"> Perform more optimisation than usual. Compilation
times may be lengthened. (This flag is an abbreviation for a certain
set of parameters described in section <a href="#s%3Aflambda-defaults">21.5</a>.)
</dd><dt class="dt-description"><span class="c006">-O3</span></dt><dd class="dd-description"> Perform even more optimisation than usual, possibly
including unrolling of recursive functions. Compilation times may be
significantly lengthened.
</dd><dt class="dt-description"><span class="c006">-Oclassic</span></dt><dd class="dd-description"> Make inlining decisions at the point of
definition of a function rather than at the call site(s). This mirrors
the behaviour of OCaml compilers not using Flambda. Compared to compilation
using the new Flambda inlining heuristics (for example at <span class="c003">-O2</span>) it
produces
smaller <span class="c003">.cmx</span> files, shorter compilation times and code that probably
runs rather slower. When using <span class="c003">-Oclassic</span>, only the following options
described in this section are relevant: <span class="c003">-inlining-report</span> and
<span class="c003">-inline</span>. If any other of the options described in this section are
used, the behaviour is undefined and may cause an error in future versions
of the compiler.
</dd><dt class="dt-description"><span class="c006">-inlining-report</span></dt><dd class="dd-description"> Emit <span class="c003">.inlining</span> files (one per
round of optimisation) showing all of the inliner’s decisions.
</dd></dl><p>Less commonly-used options:
</p><dl class="description"><dt class="dt-description">
<span class="c006">-remove-unused-arguments</span></dt><dd class="dd-description"> Remove unused function arguments
even when the argument is not specialised. This may have a small
performance penalty.
See section <a href="#ss%3Aflambda-remove-unused-args">21.10.3</a>.
</dd><dt class="dt-description"><span class="c006">-unbox-closures</span></dt><dd class="dd-description"> Pass free variables via specialised arguments
rather than closures (an optimisation for reducing allocation). See
section <a href="#ss%3Aflambda-unbox-closures">21.9.3</a>. This may have a small performance penalty.
</dd></dl><p>Advanced options, only needed for detailed tuning:
</p><dl class="description"><dt class="dt-description">
<span class="c006">-inline</span></dt><dd class="dd-description"> The behaviour depends on whether <span class="c003">-Oclassic</span>
is used.
<ul class="itemize"><li class="li-itemize">
When not in <span class="c003">-Oclassic</span> mode, <span class="c003">-inline</span> limits the total
size of functions considered for inlining during any speculative inlining
search. (See section <a href="#ss%3Aflambda-speculation">21.3.6</a>.) Note that
this parameter does
<span class="c013">not</span> control the assessment as to whether any particular function may
be inlined. Raising it to excessive amounts will not necessarily cause
more functions to be inlined.
</li><li class="li-itemize">When in <span class="c003">-Oclassic</span> mode, <span class="c003">-inline</span> behaves as in
previous versions of the compiler: it is the maximum size of function to
be considered for inlining. See section <a href="#ss%3Aflambda-classic">21.3.1</a>.
</li></ul>
</dd><dt class="dt-description"><span class="c006">-inline-toplevel</span></dt><dd class="dd-description"> The equivalent of <span class="c003">-inline</span> but used
when speculative inlining starts at toplevel. See
section <a href="#ss%3Aflambda-speculation">21.3.6</a>.
Not used in <span class="c003">-Oclassic</span> mode.
</dd><dt class="dt-description"><span class="c006">-inline-branch-factor</span></dt><dd class="dd-description"> Controls how the inliner assesses
whether a code path is likely to be hot or cold. See
section <a href="#ss%3Aflambda-assessment-inlining">21.3.5</a>.
</dd><dt class="dt-description"><span class="c006">-inline-alloc-cost,
-inline-branch-cost,
-inline-call-cost</span></dt><dd class="dd-description"> Controls how the inliner assesses the runtime
performance penalties associated with various operations. See
section <a href="#ss%3Aflambda-assessment-inlining">21.3.5</a>.
</dd><dt class="dt-description"><span class="c006">-inline-indirect-cost,
-inline-prim-cost</span></dt><dd class="dd-description"> Likewise.
</dd><dt class="dt-description"><span class="c006">-inline-lifting-benefit</span></dt><dd class="dd-description"> Controls inlining of functors
at toplevel. See section <a href="#ss%3Aflambda-assessment-inlining">21.3.5</a>.
</dd><dt class="dt-description"><span class="c006">-inline-max-depth</span></dt><dd class="dd-description"> The maximum depth of any
speculative inlining search. See section <a href="#ss%3Aflambda-speculation">21.3.6</a>.
</dd><dt class="dt-description"><span class="c006">-inline-max-unroll</span></dt><dd class="dd-description"> The maximum depth of any unrolling of
recursive functions during any speculative inlining search.
See section <a href="#ss%3Aflambda-speculation">21.3.6</a>.
</dd><dt class="dt-description"><span class="c006">-no-unbox-free-vars-of-closures</span></dt><dd class="dd-description"> Do not unbox closure variables. See section <a href="#ss%3Aflambda-unbox-fvs">21.9.1</a>.
</dd><dt class="dt-description"><span class="c006">-no-unbox-specialised-args</span></dt><dd class="dd-description"> Do not unbox arguments to which functions have been specialised. See
section <a href="#ss%3Aflambda-unbox-spec-args">21.9.2</a>.
</dd><dt class="dt-description"><span class="c006">-rounds</span></dt><dd class="dd-description"> How many rounds of optimisation to perform.
See section <a href="#ss%3Aflambda-rounds">21.2.1</a>.
</dd><dt class="dt-description"><span class="c006">-unbox-closures-factor</span></dt><dd class="dd-description"> Scaling factor for benefit
calculation when using <span class="c003">-unbox-closures</span>. See
section <a href="#ss%3Aflambda-unbox-closures">21.9.3</a>.
</dd></dl>
<!--TOC paragraph id="sec499" Notes-->
<h5 class="paragraph" id="sec499"><a class="section-anchor" href="#sec499" aria-hidden="true"></a>Notes</h5><!--SEC END --><ul class="itemize"><li class="li-itemize">
The set of command line flags relating to optimisation should typically
be specified to be the same across an entire project. Flambda does not
currently record the requested flags in the <span class="c003">.cmx</span> files. As such,
inlining of functions from previously-compiled units will subject their code
to the optimisation parameters of the unit currently being compiled, rather
than those specified when they were previously compiled. It is hoped to
rectify this deficiency in the future.</li><li class="li-itemize">Flambda-specific flags do not affect linking with the exception of
affecting the optimisation of code in the startup file (containing
generated functions such as currying helpers). Typically such optimisation
will not be significant, so eliding such flags at link time might be
reasonable.</li><li class="li-itemize">Flambda-specific flags are silently accepted even when the
<span class="c003">-flambda</span> option was not provided to the <span class="c003">configure</span> script.
(There is no means provided to change this behaviour.)
This is intended to make it more
straightforward to run benchmarks with and without the Flambda optimisers
in effect.
</li><li class="li-itemize">Some of the Flambda flags may be subject to change in future
releases.
</li></ul>
<!--TOC subsection id="ss:flambda-rounds" 21.2.1  Specification of optimisation parameters by round-->
<h3 class="subsection" id="ss:flambda-rounds"><a class="section-anchor" href="#ss:flambda-rounds" aria-hidden="true"></a>21.2.1  Specification of optimisation parameters by round</h3><!--SEC END --><p>Flambda operates in <em>rounds</em>: one round consists of a certain sequence
of transformations that may then be repeated in order to achieve more
satisfactory results. The number of rounds can be set manually using the
<span class="c003">-rounds</span> parameter (although this is not necessary when using
predefined optimisation levels such as with <span class="c003">-O2</span> and <span class="c003">-O3</span>).
For high optimisation the number of rounds might be set at 3 or 4.</p><p>Command-line flags that may apply per round, for example those with
<span class="c003">-cost</span> in the name, accept arguments of the form:
</p><div class="center">
<em>n</em><span class="c003"> | </span><em>round</em><span class="c003">=</span><em>n</em>[<span class="c003">,</span>...]
</div><ul class="itemize"><li class="li-itemize">
If the first form is used, with a single integer specified,
the value will apply to all rounds.
</li><li class="li-itemize">If the second form is used, zero-based <em>round</em> integers specify
values which are to be used only for those rounds.
</li></ul><p>The flags <span class="c003">-Oclassic</span>, <span class="c003">-O2</span> and <span class="c003">-O3</span> are applied before all
other flags, meaning that certain parameters may be overridden without
having to specify every parameter usually invoked by the given optimisation
level.</p>
<!--TOC section id="s:flambda-inlining" 21.3  Inlining-->
<h2 class="section" id="s:flambda-inlining"><a class="section-anchor" href="#s:flambda-inlining" aria-hidden="true"></a>21.3  Inlining</h2><!--SEC END --><p><em>Inlining</em> refers to the copying of the code of a function to a
place where the function is called.
The code of the function will be surrounded by bindings of its parameters
to the corresponding arguments.</p><p>The aims of inlining are:
</p><ul class="itemize"><li class="li-itemize">
to reduce the runtime overhead caused by function calls (including
setting up for such calls and returning afterwards);
</li><li class="li-itemize">to reduce instruction cache misses by expressing frequently-taken
paths through the program using fewer machine instructions; and
</li><li class="li-itemize">to reduce the amount of allocation (especially of closures).
</li></ul><p>
These goals are often reached not just by inlining itself but also by
other optimisations that the compiler is able to perform as a result of
inlining.</p><p>When a recursive call to a function (within the definition of that function
or another in the same mutually-recursive group) is inlined, the procedure is
also known as <em>unrolling</em>. This is somewhat akin to loop peeling.
For example, given the following code:
</p><pre>let rec fact x =
  if x = 0 then
    1
  else
    x * fact (x - 1)

let n = fact 4
</pre><p>unrolling once at the call site <span class="c003">fact 4</span> produces (with the body of
<span class="c003">fact</span> unchanged):
</p><pre>let n =
  if 4 = 0 then
    1
  else
    4 * fact (4 - 1)
</pre><p>This simplifies to:
</p><pre>let n = 4 * fact 3
</pre><p>Flambda provides significantly enhanced inlining capabilities relative to
previous versions of the compiler.</p>
<!--TOC subsubsection id="sss:flambda-inlining-aside" Aside: when inlining is performed-->
<h4 class="subsubsection" id="sss:flambda-inlining-aside"><a class="section-anchor" href="#sss:flambda-inlining-aside" aria-hidden="true"></a>Aside: when inlining is performed</h4><!--SEC END --><p>Inlining is performed together with all of the other Flambda optimisation
passes, that is to say, after closure conversion. This has three particular
advantages over a potentially more straightforward implementation prior to
closure conversion:
</p><ul class="itemize"><li class="li-itemize">
It permits higher-order inlining, for example when a non-inlinable
function always returns the same function yet with different environments
of definition. Not all such cases are supported yet, but it is intended
that such support will be improved in future.
</li><li class="li-itemize">It is easier to integrate with cross-module optimisation, since
imported information about other modules is already in the correct
intermediate language.
</li><li class="li-itemize">It becomes more straightforward to optimise closure allocations since
the layout of closures does not have to be estimated in any way: it is
known. Similarly,
it becomes more straightforward to control which variables end up
in which closures, helping to avoid closure bloat.
</li></ul>
<!--TOC subsection id="ss:flambda-classic" 21.3.1  Classic inlining heuristic-->
<h3 class="subsection" id="ss:flambda-classic"><a class="section-anchor" href="#ss:flambda-classic" aria-hidden="true"></a>21.3.1  Classic inlining heuristic</h3><!--SEC END --><p>In <span class="c003">-Oclassic</span> mode the behaviour of the Flambda inliner
mimics previous versions
of the compiler. (Code may still be subject to further optimisations not
performed by previous versions of the compiler: functors may be inlined,
constants are lifted and unused code is eliminated all as described elsewhere
in this chapter. See sections <a href="#sss%3Aflambda-functors">21.3.3</a>, <a href="#ss%3Aflambda-lift-const">21.8.1</a> and <a href="#s%3Aflambda-remove-unused">21.10</a>.
At the definition site of a function, the body of the
function is measured. It will then be marked as eligible for inlining
(and hence inlined at every direct call site) if:
</p><ul class="itemize"><li class="li-itemize">
the measured size (in unspecified units) is smaller than that of a
function call plus the argument of the <span class="c003">-inline</span> command-line flag; and
</li><li class="li-itemize">the function is not recursive.
</li></ul><p>Non-Flambda versions of the compiler cannot inline functions that
contain a definition of another function. However <span class="c003">-Oclassic</span> does
permit this. Further, non-Flambda versions also cannot inline functions
that are only themselves exposed as a result of a previous pass of inlining,
but again this is permitted by <span class="c003">-Oclassic</span>.
For example:
</p><pre>module M : sig
  val i : int
end = struct
  let f x =
    let g y = x + y in
    g
  let h = f 3
  let i = h 4  (* h is correctly discovered to be g and inlined *)
end
</pre><p>
All of this contrasts with the normal Flambda mode, that is to say
without <span class="c003">-Oclassic</span>, where:
</p><ul class="itemize"><li class="li-itemize">
the inlining decision is made at the <span class="c013">call site</span>; and
</li><li class="li-itemize">recursive functions can be handled, by <em>specialisation</em> (see
below).
</li></ul><p>
The Flambda mode is described in the next section.</p>
<!--TOC subsection id="ss:flambda-inlining-overview" 21.3.2  Overview of “Flambda” inlining heuristics-->
<h3 class="subsection" id="ss:flambda-inlining-overview"><a class="section-anchor" href="#ss:flambda-inlining-overview" aria-hidden="true"></a>21.3.2  Overview of “Flambda” inlining heuristics</h3><!--SEC END --><p>The Flambda inlining heuristics, used whenever the compiler is configured
for Flambda and <span class="c003">-Oclassic</span> was not specified, make inlining decisions
at call sites. This helps in situations where the context is important.
For example:
</p><pre>let f b x =
  if b then
    x
  else
    ... big expression ...

let g x = f true x
</pre><p>In this case, we would like to inline <span class="c003">f</span> into <span class="c003">g</span>, because a
conditional jump can be eliminated and the code size should reduce. If the
inlining decision has been made after the declaration of <span class="c003">f</span> without
seeing the use, its size would have probably made it ineligible for
inlining; but at the call site, its final size can be known. Further,
this function should probably not be inlined systematically: if <span class="c003">b</span>
is unknown, or indeed <span class="c003">false</span>, there is little benefit to trade off
against a large increase in code size. In the existing non-Flambda inliner
this isn’t a great problem because chains of inlining were cut off fairly
quickly. However it has led to excessive use of overly-large inlining
parameters such as <span class="c003">-inline 10000</span>.</p><p>In more detail, at each call site the following procedure is followed:
</p><ul class="itemize"><li class="li-itemize">
Determine whether it is clear that inlining would be beneficial
without, for the moment, doing any inlining within the function itself.
(The exact assessment of <em>benefit</em> is described below.) If so, the
function is inlined.
</li><li class="li-itemize">If inlining the function is not clearly beneficial, then inlining
will be performed <em>speculatively</em> inside the function itself. The
search for speculative inlining possibilities is controlled by two
parameters: the <em>inlining threshold</em> and the <em>inlining depth</em>.
(These are described in more detail below.)
<ul class="itemize"><li class="li-itemize">
If such speculation shows that performing some inlining inside the
function would be beneficial, then such inlining is performed and the
resulting function inlined at the original call site.
</li><li class="li-itemize">Otherwise, nothing happens.
</li></ul>
</li></ul><p>
Inlining within recursive functions of calls to other
functions in the same mutually-recursive group is kept in check by
an <em>unrolling depth</em>, described below. This ensures that functions are
not unrolled to excess. (Unrolling is only enabled
if <span class="c003">-O3</span> optimisation level is selected and/or the
<span class="c003">-inline-max-unroll</span>
flag is passed with an argument greater than zero.)</p>
<!--TOC subsection id="ss:flambda-by-constructs" 21.3.3  Handling of specific language constructs-->
<h3 class="subsection" id="ss:flambda-by-constructs"><a class="section-anchor" href="#ss:flambda-by-constructs" aria-hidden="true"></a>21.3.3  Handling of specific language constructs</h3><!--SEC END -->
<!--TOC subsubsection id="sss:flambda-functors" Functors-->
<h4 class="subsubsection" id="sss:flambda-functors"><a class="section-anchor" href="#sss:flambda-functors" aria-hidden="true"></a>Functors</h4><!--SEC END --><p>There is nothing particular about functors that inhibits inlining compared
to normal functions. To the inliner, these both look the same, except
that functors are marked as such.</p><p>Applications of functors at toplevel are biased in favour of inlining.
(This bias may be adjusted:
see the documentation for <span class="c003">-inline-lifting-benefit</span> below.)</p><p>Applications of functors not at toplevel, for example in a local module
inside some other expression, are treated by the inliner identically to
normal function calls.</p>
<!--TOC subsubsection id="sss:flambda-first-class-modules" First-class modules-->
<h4 class="subsubsection" id="sss:flambda-first-class-modules"><a class="section-anchor" href="#sss:flambda-first-class-modules" aria-hidden="true"></a>First-class modules</h4><!--SEC END --><p>The inliner will be able to consider inlining a call to a function in a first
class module if it knows which particular function is going to be called.
The presence of the first-class module record that wraps the set of functions
in the module does not per se inhibit inlining.</p>
<!--TOC subsubsection id="sss:flambda-objects" Objects-->
<h4 class="subsubsection" id="sss:flambda-objects"><a class="section-anchor" href="#sss:flambda-objects" aria-hidden="true"></a>Objects</h4><!--SEC END --><p>Method calls to objects are not at present inlined by Flambda.</p>
<!--TOC subsection id="ss:flambda-inlining-reports" 21.3.4  Inlining reports-->
<h3 class="subsection" id="ss:flambda-inlining-reports"><a class="section-anchor" href="#ss:flambda-inlining-reports" aria-hidden="true"></a>21.3.4  Inlining reports</h3><!--SEC END --><p>If the <span class="c003">-inlining-report</span> option is provided to the compiler then a file
will be emitted corresponding to each round of optimisation. For the
OCaml source file <em>basename</em><span class="c003">.ml</span> the files
are named <em>basename</em><span class="c003">.</span><em>round</em><span class="c003">.inlining.org</span>,
with <em>round</em> a
zero-based integer. Inside the files, which are formatted as “org mode”,
will be found English prose describing the decisions that the inliner took.</p>
<!--TOC subsection id="ss:flambda-assessment-inlining" 21.3.5  Assessment of inlining benefit-->
<h3 class="subsection" id="ss:flambda-assessment-inlining"><a class="section-anchor" href="#ss:flambda-assessment-inlining" aria-hidden="true"></a>21.3.5  Assessment of inlining benefit</h3><!--SEC END --><p>Inlining typically
results in an increase in code size, which if left unchecked, may not only
lead to grossly large executables and excessive compilation times but also
a decrease in performance due to worse locality. As such, the
Flambda inliner trades off the change in code size against
the expected runtime performance benefit, with the benefit being computed
based on the number of operations that the compiler observes may be removed
as a result of inlining.</p><p>For example given the following code:
</p><pre>let f b x =
  if b then
    x
  else
    ... big expression ...

let g x = f true x
</pre><p>it would be observed that inlining of <span class="c003">f</span> would remove:
</p><ul class="itemize"><li class="li-itemize">
one direct call;
</li><li class="li-itemize">one conditional branch.
</li></ul><p>Formally, an estimate of runtime performance benefit is computed by
first summing
the cost of the operations that are known to be removed as a result of the
inlining and subsequent simplification of the inlined body.
The individual costs for the various kinds of operations may be adjusted
using the various <span class="c003">-inline-...-cost</span> flags as follows. Costs are
specified as integers. All of these flags accept a single argument
describing such integers using the conventions
detailed in section <a href="#ss%3Aflambda-rounds">21.2.1</a>.
</p><dl class="description"><dt class="dt-description">
<span class="c006">-inline-alloc-cost</span></dt><dd class="dd-description"> The cost of an allocation.
</dd><dt class="dt-description"><span class="c006">-inline-branch-cost</span></dt><dd class="dd-description"> The cost of a branch.
</dd><dt class="dt-description"><span class="c006">-inline-call-cost</span></dt><dd class="dd-description"> The cost of a direct function call.
</dd><dt class="dt-description"><span class="c006">-inline-indirect-cost</span></dt><dd class="dd-description"> The cost of an indirect function call.
</dd><dt class="dt-description"><span class="c006">-inline-prim-cost</span></dt><dd class="dd-description"> The cost of a <em>primitive</em>. Primitives
encompass operations including arithmetic and memory access.
</dd></dl><p>
(Default values are described in section <a href="#s%3Aflambda-defaults">21.5</a> below.)</p><p>The initial benefit value is then scaled by a factor that attempts to
compensate for the fact that the current point in the code, if under some
number of conditional branches, may be cold. (Flambda does not currently
compute hot and cold paths.) The factor—the estimated probability that
the inliner really is on a <em>hot</em> path—is calculated as
1/(1 + <span class="c009">f</span>)<sup><span class="c009">d</span></sup>, where <span class="c009">f</span> is set by
<span class="c003">-inline-branch-factor</span> and <span class="c009">d</span> is the nesting depth of branches
at the current point. As the inliner descends into more deeply-nested
branches, the benefit of inlining thus lessens.</p><p>The resulting benefit value is known as the <em>estimated benefit</em>.</p><p>The change in code size is also estimated: morally speaking it should be the
change in machine code size, but since that is not available to the inliner,
an approximation is used.</p><p>If the estimated benefit exceeds the increase in code size then the inlined
version of the function will be kept. Otherwise the function will not be
inlined.</p><p>Applications of functors at toplevel will be given
an additional benefit (which may be controlled by the
<span class="c003">-inline-lifting-benefit</span> flag) to bias inlining in such situations
towards keeping the inlined version.</p>
<!--TOC subsection id="ss:flambda-speculation" 21.3.6  Control of speculation-->
<h3 class="subsection" id="ss:flambda-speculation"><a class="section-anchor" href="#ss:flambda-speculation" aria-hidden="true"></a>21.3.6  Control of speculation</h3><!--SEC END --><p>As described above, there are three parameters that restrict the search
for inlining opportunities during speculation:
</p><ul class="itemize"><li class="li-itemize">
the <em>inlining threshold</em>;
</li><li class="li-itemize">the <em>inlining depth</em>;
</li><li class="li-itemize">the <em>unrolling depth</em>.
</li></ul><p>
These parameters are ultimately bounded by the arguments provided to
the corresponding command-line flags (or their default values):
</p><ul class="itemize"><li class="li-itemize">
<span class="c003">-inline</span> (or, if the call site that triggered speculation is
at toplevel, <span class="c003">-inline-toplevel</span>);
</li><li class="li-itemize"><span class="c003">-inline-max-depth</span>;
</li><li class="li-itemize"><span class="c003">-inline-max-unroll</span>.
</li></ul><p>
<span class="c013">Note in particular</span> that <span class="c003">-inline</span> does not have the meaning that
it has in the previous compiler or in <span class="c003">-Oclassic</span> mode. In both of those
situations <span class="c003">-inline</span> was effectively some kind of basic assessment of
inlining benefit. However in Flambda inlining mode it corresponds to a
constraint on the search; the assessment of benefit is independent, as
described above.</p><p>When speculation starts the inlining threshold starts at the value set
by <span class="c003">-inline</span> (or <span class="c003">-inline-toplevel</span> if appropriate, see above).
Upon making a speculative inlining decision the
threshold is reduced by the code size of the function being inlined.
If the threshold becomes exhausted, at or below zero, no further speculation
will be performed.</p><p>The inlining depth starts at zero
and is increased by one every time the inliner
descends into another function. It is then decreased by one every time the
inliner leaves such function. If the depth exceeds the value set by
<span class="c003">-inline-max-depth</span> then speculation stops. This parameter is intended
as a general backstop for situations where the inlining
threshold does not control the search sufficiently.</p><p>The unrolling depth applies to calls within the same mutually-recursive
group of functions. Each time an inlining of such a call is performed
the depth is incremented by one when examining the resulting body. If the
depth reaches the limit set by <span class="c003">-inline-max-unroll</span> then speculation
stops.</p>
<!--TOC section id="s:flambda-specialisation" 21.4  Specialisation-->
<h2 class="section" id="s:flambda-specialisation"><a class="section-anchor" href="#s:flambda-specialisation" aria-hidden="true"></a>21.4  Specialisation</h2><!--SEC END --><p>The inliner may discover a call site to a recursive function where
something is known about the arguments: for example, they may be equal to
some other variables currently in scope. In this situation it may be
beneficial to <em>specialise</em> the function to those arguments. This is
done by copying the declaration of the function (and any others involved
in any same mutually-recursive declaration) and noting the extra information
about the arguments. The arguments augmented by this information are known
as <em>specialised arguments</em>. In order to try to ensure that specialisation
is not performed uselessly, arguments are only specialised if it can be shown
that they are <em>invariant</em>: in other words, during the execution of the
recursive function(s) themselves, the arguments never change.</p><p>Unless overridden by an attribute (see below), specialisation of a function
will not be attempted if:
</p><ul class="itemize"><li class="li-itemize">
the compiler is in <span class="c003">-Oclassic</span> mode;
</li><li class="li-itemize">the function is not obviously recursive;
</li><li class="li-itemize">the function is not closed.
</li></ul><p>The compiler can prove invariance of function arguments across multiple
functions within a recursive group (although this has some limitations,
as shown by the example below).</p><p>It should be noted that the <em>unboxing of closures</em> pass (see below)
can introduce specialised arguments on non-recursive functions. (No other
place in the compiler currently does this.)</p>
<!--TOC paragraph id="sec513" Example: the well-known <span class="c003">List.iter</span> function-->
<h5 class="paragraph" id="sec513"><a class="section-anchor" href="#sec513" aria-hidden="true"></a>Example: the well-known <span class="c003">List.iter</span> function</h5><!--SEC END --><p>
This function might be written like so:
</p><pre>let rec iter f l =
  match l with
  | [] -&gt; ()
  | h :: t -&gt;
    f h;
    iter f t
</pre><p>and used like this:
</p><pre>let print_int x =
  print_endline (Int.to_string x)

let run xs =
  iter print_int (List.rev xs)
</pre><p>The argument <span class="c003">f</span> to <span class="c003">iter</span> is invariant so the function may be
specialised:
</p><pre>let run xs =
  let rec iter' f l =
    (* The compiler knows: f holds the same value as foo throughout iter'. *)
    match l with
    | [] -&gt; ()
    | h :: t -&gt;
      f h;
      iter' f t
  in
  iter' print_int (List.rev xs)
</pre><p>The compiler notes down that for the function <span class="c003">iter’</span>, the argument
<span class="c003">f</span> is specialised to the constant closure <span class="c003">print_int</span>. This
means that the body of <span class="c003">iter’</span> may be simplified:
</p><pre>let run xs =
  let rec iter' f l =
    (* The compiler knows: f holds the same value as foo throughout iter'. *)
    match l with
    | [] -&gt; ()
    | h :: t -&gt;
      print_int h;  (* this is now a direct call *)
      iter' f t
  in
  iter' print_int (List.rev xs)
</pre><p>The call to <span class="c003">print_int</span> can indeed be inlined:
</p><pre>let run xs =
  let rec iter' f l =
    (* The compiler knows: f holds the same value as foo throughout iter'. *)
    match l with
    | [] -&gt; ()
    | h :: t -&gt;
      print_endline (Int.to_string h);
      iter' f t
  in
  iter' print_int (List.rev xs)
</pre><p>The unused specialised argument <span class="c003">f</span> may now be removed, leaving:
</p><pre>let run xs =
  let rec iter' l =
    match l with
    | [] -&gt; ()
    | h :: t -&gt;
      print_endline (Int.to_string h);
      iter' t
  in
  iter' (List.rev xs)
</pre>
<!--TOC paragraph id="sec514" Aside on invariant parameters.-->
<h5 class="paragraph" id="sec514"><a class="section-anchor" href="#sec514" aria-hidden="true"></a>Aside on invariant parameters.</h5><!--SEC END --><p> The compiler cannot currently
detect invariance in cases such as the following.
</p><pre>let rec iter_swap f g l =
  match l with
  | [] -&gt; ()
  | 0 :: t -&gt;
    iter_swap g f l
  | h :: t -&gt;
    f h;
    iter_swap f g t
</pre>
<!--TOC subsection id="ss:flambda-assessment-specialisation" 21.4.1  Assessment of specialisation benefit-->
<h3 class="subsection" id="ss:flambda-assessment-specialisation"><a class="section-anchor" href="#ss:flambda-assessment-specialisation" aria-hidden="true"></a>21.4.1  Assessment of specialisation benefit</h3><!--SEC END --><p>The benefit of specialisation is assessed in a similar way as for inlining.
Specialised argument information may mean that the body of the function
being specialised can be simplified: the removed operations are accumulated
into a benefit. This, together with the size of the duplicated (specialised)
function declaration, is then assessed against the size of the call to the
original function.</p>
<!--TOC section id="s:flambda-defaults" 21.5  Default settings of parameters-->
<h2 class="section" id="s:flambda-defaults"><a class="section-anchor" href="#s:flambda-defaults" aria-hidden="true"></a>21.5  Default settings of parameters</h2><!--SEC END --><p>The default settings (when not using <span class="c003">-Oclassic</span>) are for one
round of optimisation using the following parameters.
</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Parameter</span></td><td class="c014"><span class="c013">Setting</span> </td></tr>
<tr><td class="c016">
<span class="c003">-inline</span></td><td class="c016">10 </td></tr>
<tr><td class="c016"><span class="c003">-inline-branch-factor</span></td><td class="c016">0.1 </td></tr>
<tr><td class="c016"><span class="c003">-inline-alloc-cost</span></td><td class="c016">7 </td></tr>
<tr><td class="c016"><span class="c003">-inline-branch-cost</span></td><td class="c016">5 </td></tr>
<tr><td class="c016"><span class="c003">-inline-call-cost</span></td><td class="c016">5 </td></tr>
<tr><td class="c016"><span class="c003">-inline-indirect-cost</span></td><td class="c016">4 </td></tr>
<tr><td class="c016"><span class="c003">-inline-prim-cost</span></td><td class="c016">3 </td></tr>
<tr><td class="c016"><span class="c003">-inline-lifting-benefit</span></td><td class="c016">1300 </td></tr>
<tr><td class="c016"><span class="c003">-inline-toplevel</span></td><td class="c016">160 </td></tr>
<tr><td class="c016"><span class="c003">-inline-max-depth</span></td><td class="c016">1 </td></tr>
<tr><td class="c016"><span class="c003">-inline-max-unroll</span></td><td class="c016">0 </td></tr>
<tr><td class="c016"><span class="c003">-unbox-closures-factor</span></td><td class="c016">10 </td></tr>
</table></div></div>
<!--TOC subsection id="ss:flambda-o2" 21.5.1  Settings at -O2 optimisation level-->
<h3 class="subsection" id="ss:flambda-o2"><a class="section-anchor" href="#ss:flambda-o2" aria-hidden="true"></a>21.5.1  Settings at -O2 optimisation level</h3><!--SEC END --><p>When <span class="c003">-O2</span> is specified two rounds of optimisation are performed.
The first round uses the default parameters (see above). The second uses
the following parameters.</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Parameter</span></td><td class="c014"><span class="c013">Setting</span> </td></tr>
<tr><td class="c016">
<span class="c003">-inline</span></td><td class="c016">25 </td></tr>
<tr><td class="c016"><span class="c003">-inline-branch-factor</span></td><td class="c016">Same as default </td></tr>
<tr><td class="c016"><span class="c003">-inline-alloc-cost</span></td><td class="c016">Double the default </td></tr>
<tr><td class="c016"><span class="c003">-inline-branch-cost</span></td><td class="c016">Double the default </td></tr>
<tr><td class="c016"><span class="c003">-inline-call-cost</span></td><td class="c016">Double the default </td></tr>
<tr><td class="c016"><span class="c003">-inline-indirect-cost</span></td><td class="c016">Double the default </td></tr>
<tr><td class="c016"><span class="c003">-inline-prim-cost</span></td><td class="c016">Double the default </td></tr>
<tr><td class="c016"><span class="c003">-inline-lifting-benefit</span></td><td class="c016">Same as default </td></tr>
<tr><td class="c016"><span class="c003">-inline-toplevel</span></td><td class="c016">400 </td></tr>
<tr><td class="c016"><span class="c003">-inline-max-depth</span></td><td class="c016">2 </td></tr>
<tr><td class="c016"><span class="c003">-inline-max-unroll</span></td><td class="c016">Same as default </td></tr>
<tr><td class="c016"><span class="c003">-unbox-closures-factor</span></td><td class="c016">Same as default </td></tr>
</table></div></div>
<!--TOC subsection id="ss:flambda-o3" 21.5.2  Settings at -O3 optimisation level-->
<h3 class="subsection" id="ss:flambda-o3"><a class="section-anchor" href="#ss:flambda-o3" aria-hidden="true"></a>21.5.2  Settings at -O3 optimisation level</h3><!--SEC END --><p>When <span class="c003">-O3</span> is specified three rounds of optimisation are performed.
The first two rounds are as for <span class="c003">-O2</span>. The third round uses
the following parameters.</p><div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Parameter</span></td><td class="c014"><span class="c013">Setting</span> </td></tr>
<tr><td class="c016">
<span class="c003">-inline</span></td><td class="c016">50 </td></tr>
<tr><td class="c016"><span class="c003">-inline-branch-factor</span></td><td class="c016">Same as default </td></tr>
<tr><td class="c016"><span class="c003">-inline-alloc-cost</span></td><td class="c016">Triple the default </td></tr>
<tr><td class="c016"><span class="c003">-inline-branch-cost</span></td><td class="c016">Triple the default </td></tr>
<tr><td class="c016"><span class="c003">-inline-call-cost</span></td><td class="c016">Triple the default </td></tr>
<tr><td class="c016"><span class="c003">-inline-indirect-cost</span></td><td class="c016">Triple the default </td></tr>
<tr><td class="c016"><span class="c003">-inline-prim-cost</span></td><td class="c016">Triple the default </td></tr>
<tr><td class="c016"><span class="c003">-inline-lifting-benefit</span></td><td class="c016">Same as default </td></tr>
<tr><td class="c016"><span class="c003">-inline-toplevel</span></td><td class="c016">800 </td></tr>
<tr><td class="c016"><span class="c003">-inline-max-depth</span></td><td class="c016">3 </td></tr>
<tr><td class="c016"><span class="c003">-inline-max-unroll</span></td><td class="c016">1 </td></tr>
<tr><td class="c016"><span class="c003">-unbox-closures-factor</span></td><td class="c016">Same as default </td></tr>
</table></div></div>
<!--TOC section id="s:flambda-manual-control" 21.6  Manual control of inlining and specialisation-->
<h2 class="section" id="s:flambda-manual-control"><a class="section-anchor" href="#s:flambda-manual-control" aria-hidden="true"></a>21.6  Manual control of inlining and specialisation</h2><!--SEC END --><p>Should the inliner prove recalcitrant and refuse to inline a particular
function, or if the observed inlining decisions are not to the programmer’s
satisfaction for some other reason, inlining behaviour can be dictated by the
programmer directly in the source code.
One example where this might be appropriate is when the programmer,
but not the compiler, knows that a particular function call is on a cold
code path. It might be desirable to prevent inlining of the function so
that the code size along the hot path is kept smaller, so as to increase
locality.</p><p>The inliner is directed using attributes.
For non-recursive functions (and one-step unrolling of recursive functions,
although <span class="c003">@unroll</span> is more clear for this purpose)
the following are supported:
</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">@@inline always</span> or <span class="c003">@@inline never</span></span></dt><dd class="dd-description"> Attached
to a <em>declaration</em> of a function or functor, these direct the inliner to
either
always or never inline, irrespective of the size/benefit calculation. (If
the function is recursive then the body is substituted and no special
action is taken for the recursive call site(s).)
<span class="c003">@@inline</span> with no argument is equivalent to
<span class="c003">@@inline always</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">@inlined always</span> or <span class="c003">@inlined never</span></span></dt><dd class="dd-description"> Attached
to a function <em>application</em>, these direct the inliner likewise. These
attributes at call sites override any other attribute that may be present
on the corresponding declaration.
<span class="c003">@inlined</span> with no argument is equivalent to
<span class="c003">@inlined always</span>. <span class="c003">@@inlined hint</span> is equivalent to
<span class="c003">@@inline always</span> except that it will not trigger warning 55 if
the function application cannot be inlined.
</dd></dl><p>For recursive functions the relevant attributes are:
</p><dl class="description"><dt class="dt-description">
<span class="c013"><span class="c003">@@specialise always</span> or <span class="c003">@@specialise never</span></span></dt><dd class="dd-description">Attached to a declaration of a function
or functor, this directs the inliner to either always or never
specialise the function so
long as it has appropriate contextual knowledge, irrespective of the
size/benefit calculation.
<span class="c003">@@specialise</span> with no argument is equivalent to
<span class="c003">@@specialise always</span>.
</dd><dt class="dt-description"><span class="c013"><span class="c003">@specialised always</span> or <span class="c003">@specialised never</span></span></dt><dd class="dd-description">Attached to a function application, this
directs the inliner likewise. This attribute at a call site overrides any
other attribute that may be present on the corresponding declaration.
(Note that the function will still only be specialised if there exist
one or more invariant parameters whose values are known.)
<span class="c003">@specialised</span> with no argument is equivalent to
<span class="c003">@specialised always</span>.
</dd><dt class="dt-description"><span class="c006">@unrolled </span><span class="c009">n</span></dt><dd class="dd-description"> This attribute is attached to a function
application and always takes an integer argument. Each time the inliner sees
the attribute it behaves as follows:
<ul class="itemize"><li class="li-itemize">
If <span class="c009">n</span> is zero or less, nothing happens.
</li><li class="li-itemize">Otherwise the function being called is substituted at the call site
with its body having been rewritten such that 
any recursive calls to that function <em>or
any others in the same mutually-recursive group</em> are annotated with the
attribute <span class="c003">unrolled(</span><span class="c009">n</span> − 1<span class="c003">)</span>. Inlining may continue on that body.
</li></ul>
As such, <span class="c009">n</span> behaves as the “maximum depth of unrolling”.
</dd></dl><p>A compiler warning will be emitted if it was found impossible to obey an
annotation from an <span class="c003">@inlined</span> or <span class="c003">@specialised</span> attribute.</p>
<!--TOC paragraph id="sec520" Example showing correct placement of attributes-->
<h5 class="paragraph" id="sec520"><a class="section-anchor" href="#sec520" aria-hidden="true"></a>Example showing correct placement of attributes</h5><!--SEC END --><pre>module F (M : sig type t end) = struct
  let[@inline never] bar x =
    x * 3

  let foo x =
    (bar [@inlined]) (42 + x)
end [@@inline never]

module X = F [@inlined] (struct type t = int end)
</pre>
<!--TOC section id="s:flambda-simplification" 21.7  Simplification-->
<h2 class="section" id="s:flambda-simplification"><a class="section-anchor" href="#s:flambda-simplification" aria-hidden="true"></a>21.7  Simplification</h2><!--SEC END --><p>Simplification, which is run in conjunction with inlining,
propagates information (known as <em>approximations</em>) about which
variables hold what values at runtime. Certain relationships between
variables and symbols are also tracked: for example, some variable may be
known to always hold the same value as some other variable; or perhaps
some variable may be known to always hold the value pointed to by some
symbol.</p><p>The propagation can help to eliminate allocations in cases such as:
</p><pre>let f x y =
  ...
  let p = x, y in
  ...
  ... (fst p) ... (snd p) ...
</pre><p>The projections from <span class="c003">p</span> may be replaced by uses of the variables
<span class="c003">x</span> and <span class="c003">y</span>, potentially meaning that <span class="c003">p</span> becomes unused.</p><p>The propagation performed by the simplification pass is also important for
discovering which functions flow to indirect call sites. This can enable
the transformation of such call sites into direct call sites, which makes
them eligible for an inlining transformation.</p><p>Note that no information is propagated about the contents of strings,
even in <span class="c003">safe-string</span> mode, because it cannot yet be guaranteed
that they are immutable throughout a given program.</p>
<!--TOC section id="s:flambda-other-transfs" 21.8  Other code motion transformations-->
<h2 class="section" id="s:flambda-other-transfs"><a class="section-anchor" href="#s:flambda-other-transfs" aria-hidden="true"></a>21.8  Other code motion transformations</h2><!--SEC END -->
<!--TOC subsection id="ss:flambda-lift-const" 21.8.1  Lifting of constants-->
<h3 class="subsection" id="ss:flambda-lift-const"><a class="section-anchor" href="#ss:flambda-lift-const" aria-hidden="true"></a>21.8.1  Lifting of constants</h3><!--SEC END --><p>Expressions found to be constant will be lifted to symbol
bindings—that is to say, they will be statically allocated in the
object file—when
they evaluate to boxed values. Such constants may be straightforward numeric
constants, such as the floating-point number <span class="c003">42.0</span>, or more complicated
values such as constant closures.</p><p>Lifting of constants to toplevel reduces allocation at runtime.</p><p>The compiler aims to share constants lifted to toplevel such that there
are no duplicate definitions. However if <span class="c003">.cmx</span> files are hidden
from the compiler then maximal sharing may not be possible.</p>
<!--TOC paragraph id="sec524" Notes about float arrays-->
<h5 class="paragraph" id="sec524"><a class="section-anchor" href="#sec524" aria-hidden="true"></a>Notes about float arrays</h5><!--SEC END --><p> The following language semantics apply specifically to constant float arrays.
(By “constant float array” is meant an array consisting entirely of floating
point numbers that are known at compile time. A common case is a literal
such as <span class="c003">[| 42.0; 43.0; |]</span>.
</p><ul class="itemize"><li class="li-itemize">
Constant float arrays at the toplevel are mutable and never shared.
(That is to say, for each
such definition there is a distinct symbol in the data section of the object
file pointing at the array.)
</li><li class="li-itemize">Constant float arrays not at toplevel are mutable and are created each
time the expression is evaluated. This can be thought of as an operation that
takes an immutable array (which in the source code has no associated name; let
us call it the <em>initialising array</em>) and
duplicates it into a fresh mutable array.
<ul class="itemize"><li class="li-itemize">
If the array is of size four or less, the expression will create a
fresh block and write the values into it one by one. There is no reference
to the initialising array as a whole.</li><li class="li-itemize">Otherwise, the initialising array is lifted out and subject to the
normal constant sharing procedure;
creation of the array consists of bulk copying the initialising array
into a fresh value on the OCaml heap.
</li></ul>
</li></ul>
<!--TOC subsection id="ss:flambda-lift-toplevel-let" 21.8.2  Lifting of toplevel let bindings-->
<h3 class="subsection" id="ss:flambda-lift-toplevel-let"><a class="section-anchor" href="#ss:flambda-lift-toplevel-let" aria-hidden="true"></a>21.8.2  Lifting of toplevel let bindings</h3><!--SEC END --><p>Toplevel <span class="c003">let</span>-expressions may be lifted to symbol bindings to ensure
that the corresponding bound variables are not captured by closures. If the
defining expression of a given binding is found to be constant, it is bound
as such (the technical term is a <em>let-symbol</em> binding).</p><p>Otherwise, the symbol is bound to a (statically-allocated)
<em>preallocated block</em> containing one field. At runtime, the defining
expression will be evaluated and the first field of the block filled with
the resulting value. This <em>initialise-symbol</em> binding
causes one extra indirection but ensures, by
virtue of the symbol’s address being known at compile time, that uses of the
value are not captured by closures.</p><p>It should be noted that the blocks corresponding to initialise-symbol
bindings are kept alive forever, by virtue of them occurring in a static
table of GC roots within the object file. This extended lifetime of
expressions may on occasion be surprising. If it is desired to create
some non-constant value (for example when writing GC tests) that does not
have this
extended lifetime, then it may be created and used inside a function,
with the application point of that function (perhaps at toplevel)—or
indeed the function declaration itself—marked
as to never be inlined. This technique prevents lifting of the definition
of the value in question (assuming of course that it is not constant).</p>
<!--TOC section id="s:flambda-unboxing" 21.9  Unboxing transformations-->
<h2 class="section" id="s:flambda-unboxing"><a class="section-anchor" href="#s:flambda-unboxing" aria-hidden="true"></a>21.9  Unboxing transformations</h2><!--SEC END --><p>The transformations in this section relate to the splitting apart of
<em>boxed</em> (that is to say, non-immediate) values. They are largely
intended to reduce allocation, which tends to result in a runtime
performance profile with lower variance and smaller tails.</p>
<!--TOC subsection id="ss:flambda-unbox-fvs" 21.9.1  Unboxing of closure variables-->
<h3 class="subsection" id="ss:flambda-unbox-fvs"><a class="section-anchor" href="#ss:flambda-unbox-fvs" aria-hidden="true"></a>21.9.1  Unboxing of closure variables</h3><!--SEC END --><p>This transformation is enabled unless
<span class="c003">-no-unbox-free-vars-of-closures</span> is provided.</p><p>Variables that appear in closure environments may themselves be boxed
values. As such, they may be split into further closure variables, each
of which corresponds to some projection from the original closure variable(s).
This transformation is called <em>unboxing of closure variables</em> or
<em>unboxing of free variables of closures</em>. It is only applied when
there is
reasonable certainty that there are no uses of the boxed free variable itself
within the corresponding function bodies.
</p>
<!--TOC paragraph id="sec528" Example:-->
<h5 class="paragraph" id="sec528"><a class="section-anchor" href="#sec528" aria-hidden="true"></a>Example:</h5><!--SEC END --><p> In the following code, the compiler observes that
the closure returned from the function <span class="c003">f</span> contains a variable <span class="c003">pair</span>
(free in the body of <span class="c003">f</span>) that may be split into two separate variables.
</p><pre>let f x0 x1 =
  let pair = x0, x1 in
  Printf.printf "foo\n";
  fun y -&gt;
    fst pair + snd pair + y
</pre><p>After some simplification one obtains:
</p><pre>let f x0 x1 =
  let pair_0 = x0 in
  let pair_1 = x1 in
  Printf.printf "foo\n";
  fun y -&gt;
    pair_0 + pair_1 + y
</pre><p>and then:
</p><pre>let f x0 x1 =
  Printf.printf "foo\n";
  fun y -&gt;
    x0 + x1 + y
</pre><p>The allocation of the pair has been eliminated.</p><p>This transformation does not operate if it would cause the closure to
contain more than twice as many closure variables as it did beforehand.</p>
<!--TOC subsection id="ss:flambda-unbox-spec-args" 21.9.2  Unboxing of specialised arguments-->
<h3 class="subsection" id="ss:flambda-unbox-spec-args"><a class="section-anchor" href="#ss:flambda-unbox-spec-args" aria-hidden="true"></a>21.9.2  Unboxing of specialised arguments</h3><!--SEC END --><p>This transformation is enabled unless
<span class="c003">-no-unbox-specialised-args</span> is provided.</p><p>It may become the case during compilation that one or more invariant arguments
to a function become specialised to a particular value. When such values are
themselves boxed the corresponding specialised arguments may be split into
more specialised arguments corresponding to the projections out of the boxed
value that occur within the function body. This transformation is called
<em>unboxing of specialised arguments</em>. It is only applied when there is
reasonable certainty that the boxed argument itself is unused within the
function.</p><p>If the function in question is involved in a recursive group then unboxing
of specialised arguments may be immediately replicated across the group
based on the dataflow between invariant arguments.</p>
<!--TOC paragraph id="sec530" Example:-->
<h5 class="paragraph" id="sec530"><a class="section-anchor" href="#sec530" aria-hidden="true"></a>Example:</h5><!--SEC END --><p> Having been given the following code, the compiler
will inline <span class="c003">loop</span> into <span class="c003">f</span>, and then observe <span class="c003">inv</span>
being invariant and always the pair formed by adding <span class="c003">42</span> and <span class="c003">43</span>
to the argument <span class="c003">x</span> of the function <span class="c003">f</span>.
</p><pre>let rec loop inv xs =
  match xs with
  | [] -&gt; fst inv + snd inv
  | x::xs -&gt; x + loop2 xs inv
and loop2 ys inv =
  match ys with
  | [] -&gt; 4
  | y::ys -&gt; y - loop inv ys

let f x =
  Printf.printf "%d\n" (loop (x + 42, x + 43) [1; 2; 3])
</pre><p>Since the functions have sufficiently few arguments, more specialised
arguments will be added. After some simplification one obtains:
</p><pre>let f x =
  let rec loop' xs inv_0 inv_1 =
    match xs with
    | [] -&gt; inv_0 + inv_1
    | x::xs -&gt; x + loop2' xs inv_0 inv_1
  and loop2' ys inv_0 inv_1 =
    match ys with
    | [] -&gt; 4
    | y::ys -&gt; y - loop' ys inv_0 inv_1
  in
  Printf.printf "%d\n" (loop' [1; 2; 3] (x + 42) (x + 43))
</pre><p>The allocation of the pair within <span class="c003">f</span> has been removed. (Since the
two closures for <span class="c003">loop’</span> and <span class="c003">loop2’</span> are constant they will also be
lifted to toplevel with no runtime allocation penalty. This
would also happen without having run the transformation to unbox
specialise arguments.)</p><p>The transformation to unbox specialised arguments never introduces extra
allocation.</p><p>The transformation will not unbox arguments if it would result in the
original function having sufficiently many arguments so as to inhibit
tail-call optimisation.</p><p>The transformation is implemented by creating a wrapper function that
accepts the original arguments. Meanwhile, the original function is renamed
and extra arguments are added corresponding to the unboxed specialised
arguments; this new function
is called from the wrapper. The wrapper will then be inlined
at direct call sites. Indeed, all call sites will be direct unless
<span class="c003">-unbox-closures</span> is being used, since they will have been generated
by the compiler when originally specialising the function. (In the case
of <span class="c003">-unbox-closures</span> other functions may appear with specialised
arguments; in this case there may be indirect calls and these will incur
a small penalty owing to having to bounce through the wrapper. The technique
of <em>direct call surrogates</em> used for <span class="c003">-unbox-closures</span> is not
used by the transformation to unbox specialised arguments.)</p>
<!--TOC subsection id="ss:flambda-unbox-closures" 21.9.3  Unboxing of closures-->
<h3 class="subsection" id="ss:flambda-unbox-closures"><a class="section-anchor" href="#ss:flambda-unbox-closures" aria-hidden="true"></a>21.9.3  Unboxing of closures</h3><!--SEC END --><p>This transformation is <em>not</em> enabled by default. It may be enabled
using the <span class="c003">-unbox-closures</span> flag.</p><p>The transformation replaces closure variables by specialised arguments.
The aim is to cause more closures to become closed. It is particularly
applicable, as a means of reducing allocation, where the function concerned
cannot be inlined or specialised. For example, some non-recursive function
might be too large to inline; or some recursive function might offer
no opportunities for specialisation perhaps because its only argument is
one of type <span class="c003">unit</span>.</p><p>At present there may be a small penalty in terms of actual runtime
performance when this transformation is enabled, although more stable
performance may be obtained due to reduced allocation. It is recommended
that developers experiment to determine whether the option is beneficial
for their code. (It is expected that in the future it will be possible
for the performance degradation to be removed.)</p>
<!--TOC paragraph id="sec532" Simple example:-->
<h5 class="paragraph" id="sec532"><a class="section-anchor" href="#sec532" aria-hidden="true"></a>Simple example:</h5><!--SEC END --><p> In the following code (which might typically
occur when <span class="c003">g</span> is too large to inline) the value of <span class="c003">x</span> would usually
be communicated to the application of the <span class="c003">+</span> function via the closure
of <span class="c003">g</span>.
</p><pre>let f x =
  let g y =
    x + y
  in
  (g [@inlined never]) 42
</pre><p>Unboxing of the closure causes the value for <span class="c003">x</span> inside <span class="c003">g</span> to
be passed as an argument to <span class="c003">g</span> rather than through its closure. This
means that the closure of <span class="c003">g</span> becomes constant and may be lifted to
toplevel, eliminating the runtime allocation.</p><p>The transformation is implemented by adding a new wrapper function in the
manner of that used when unboxing specialised arguments. The closure
variables are still free in the wrapper, but the intention is that when
the wrapper is inlined at direct call sites, the relevant values are
passed directly to the main function via the new specialised arguments.</p><p>Adding such a wrapper will penalise indirect calls to the function
(which might exist in arbitrary places; remember that this transformation
is not for example applied only on functions the compiler has produced
as a result of specialisation) since such calls will bounce through
the wrapper. To
mitigate this, if a function is small enough when weighed up against
the number of free variables being removed, it will be duplicated by the
transformation to obtain two versions: the original (used for indirect calls,
since we can do no better) and the wrapper/rewritten function pair as
described in the previous paragraph. The wrapper/rewritten function pair
will only be used at direct call sites of the function. (The wrapper in
this case is known as a <em>direct call surrogate</em>, since
it takes the place of another function—the unchanged version used for
indirect calls—at direct call sites.)</p><p>The <span class="c003">-unbox-closures-factor</span> command line flag, which takes an
integer, may be used to adjust the point at which a function is deemed
large enough to be ineligible for duplication. The benefit of
duplication is scaled by the integer before being evaluated against the
size.</p>
<!--TOC paragraph id="sec533" Harder example:-->
<h5 class="paragraph" id="sec533"><a class="section-anchor" href="#sec533" aria-hidden="true"></a>Harder example:</h5><!--SEC END --><p> In the following code, there are two closure
variables that would typically cause closure allocations. One is called
<span class="c003">fv</span> and occurs inside the function <span class="c003">baz</span>; the other is called
<span class="c003">z</span> and occurs inside the function <span class="c003">bar</span>.
In this toy (yet sophisticated) example we again use an attribute to
simulate the typical situation where the first argument of <span class="c003">baz</span> is
too large to inline.
</p><pre>let foo c =
  let rec bar zs fv =
    match zs with
    | [] -&gt; []
    | z::zs -&gt;
      let rec baz f = function
        | [] -&gt; []
        | a::l -&gt; let r = fv + ((f [@inlined never]) a) in r :: baz f l
      in
      (map2 (fun y -&gt; z + y) [z; 2; 3; 4]) @ bar zs fv
  in
  Printf.printf "%d" (List.length (bar [1; 2; 3; 4] c))
</pre><p>The code resulting from applying <span class="c003">-O3 -unbox-closures</span> to this code
passes the free variables via function arguments in
order to eliminate all closure allocation in this example (aside from any
that might be performed inside <span class="c003">printf</span>).</p>
<!--TOC section id="s:flambda-remove-unused" 21.10  Removal of unused code and values-->
<h2 class="section" id="s:flambda-remove-unused"><a class="section-anchor" href="#s:flambda-remove-unused" aria-hidden="true"></a>21.10  Removal of unused code and values</h2><!--SEC END -->
<!--TOC subsection id="ss:flambda-redundant-let" 21.10.1  Removal of redundant let expressions-->
<h3 class="subsection" id="ss:flambda-redundant-let"><a class="section-anchor" href="#ss:flambda-redundant-let" aria-hidden="true"></a>21.10.1  Removal of redundant let expressions</h3><!--SEC END --><p>The simplification pass removes unused <span class="c003">let</span> bindings so long as
their corresponding defining expressions have “no effects”. See
the section “Treatment of effects” below for the precise definition of
this term.</p>
<!--TOC subsection id="ss:flambda-redundant" 21.10.2  Removal of redundant program constructs-->
<h3 class="subsection" id="ss:flambda-redundant"><a class="section-anchor" href="#ss:flambda-redundant" aria-hidden="true"></a>21.10.2  Removal of redundant program constructs</h3><!--SEC END --><p>This transformation is analogous to the removal of <span class="c003">let</span>-expressions
whose defining expressions have no effects. It operates instead on symbol
bindings, removing those that have no effects.</p>
<!--TOC subsection id="ss:flambda-remove-unused-args" 21.10.3  Removal of unused arguments-->
<h3 class="subsection" id="ss:flambda-remove-unused-args"><a class="section-anchor" href="#ss:flambda-remove-unused-args" aria-hidden="true"></a>21.10.3  Removal of unused arguments</h3><!--SEC END --><p>This transformation is only enabled by default for specialised arguments.
It may be enabled for all arguments using the <span class="c003">-remove-unused-arguments</span>
flag.</p><p>The pass analyses functions to determine which arguments are unused.
Removal is effected by creating a wrapper function, which will be inlined
at every direct call site, that accepts the original arguments and then
discards the unused ones before calling the original function. As a
consequence, this transformation may be detrimental if the original
function is usually indirectly called, since such calls will now bounce
through the wrapper. (The technique of <em>direct call surrogates</em> used
to reduce this penalty during unboxing of closure variables (see above)
does not yet apply to the pass that removes unused arguments.)</p>
<!--TOC subsection id="ss:flambda-removal-closure-vars" 21.10.4  Removal of unused closure variables-->
<h3 class="subsection" id="ss:flambda-removal-closure-vars"><a class="section-anchor" href="#ss:flambda-removal-closure-vars" aria-hidden="true"></a>21.10.4  Removal of unused closure variables</h3><!--SEC END --><p>This transformation performs an analysis across
the whole compilation unit to determine whether there exist closure variables
that are never used. Such closure variables are then eliminated. (Note that
this has to be a whole-unit analysis because a projection of a closure
variable from some particular closure may have propagated to an arbitrary
location within the code due to inlining.)</p>
<!--TOC section id="s:flambda-other" 21.11  Other code transformations-->
<h2 class="section" id="s:flambda-other"><a class="section-anchor" href="#s:flambda-other" aria-hidden="true"></a>21.11  Other code transformations</h2><!--SEC END -->
<!--TOC subsection id="ss:flambda-non-escaping-refs" 21.11.1  Transformation of non-escaping references into mutable variables-->
<h3 class="subsection" id="ss:flambda-non-escaping-refs"><a class="section-anchor" href="#ss:flambda-non-escaping-refs" aria-hidden="true"></a>21.11.1  Transformation of non-escaping references into mutable variables</h3><!--SEC END --><p>Flambda performs a simple analysis analogous to that performed elsewhere
in the compiler that can transform <span class="c003">ref</span>s into mutable variables
that may then be held in registers (or on the stack as appropriate) rather
than being allocated on the OCaml heap. This only happens so long as the
reference concerned can be shown to not escape from its defining scope.</p>
<!--TOC subsection id="ss:flambda-subst-closure-vars" 21.11.2  Substitution of closure variables for specialised arguments-->
<h3 class="subsection" id="ss:flambda-subst-closure-vars"><a class="section-anchor" href="#ss:flambda-subst-closure-vars" aria-hidden="true"></a>21.11.2  Substitution of closure variables for specialised arguments</h3><!--SEC END --><p>This transformation discovers closure variables that are known to be
equal to specialised arguments. Such closure variables are replaced by
the specialised arguments; the closure variables may then be removed by
the “removal of unused closure variables” pass (see below).</p>
<!--TOC section id="s:flambda-effects" 21.12  Treatment of effects-->
<h2 class="section" id="s:flambda-effects"><a class="section-anchor" href="#s:flambda-effects" aria-hidden="true"></a>21.12  Treatment of effects</h2><!--SEC END --><p>The Flambda optimisers classify expressions in order to determine whether
an expression:
</p><ul class="itemize"><li class="li-itemize">
does not need to be evaluated at all; and/or
</li><li class="li-itemize">may be duplicated.
</li></ul><p>This is done by forming judgements on the <em>effects</em> and the <em>coeffects</em>
that might be performed were the expression to be executed. Effects talk
about how the expression might affect the world; coeffects talk about how
the world might affect the expression.</p><p>Effects are classified as follows:
</p><dl class="description"><dt class="dt-description">
<span class="c013">No effects:</span></dt><dd class="dd-description"> The expression does not change the observable state
of the world. For example, it must not write to any mutable storage,
call arbitrary external functions or change control flow (e.g. by raising
an exception). Note that allocation is <em>not</em> classed as having
“no effects” (see below).
<ul class="itemize"><li class="li-itemize">
It is assumed in the compiler that expressions with no
effects, whose results are not used, may be eliminated. (This typically
happens where the expression in question is the defining expression of a
<span class="c003">let</span>; in such cases the <span class="c003">let</span>-expression will be
eliminated.) It is further
assumed that such expressions with no effects may be
duplicated (and thus possibly executed more than once).
</li><li class="li-itemize">Exceptions arising from allocation points, for example
“out of memory” or
exceptions propagated from finalizers or signal handlers, are treated as
“effects out of the ether” and thus ignored for our determination here
of effectfulness. The same goes for floating point operations that may
cause hardware traps on some platforms.
</li></ul>
</dd><dt class="dt-description"><span class="c013">Only generative effects:</span></dt><dd class="dd-description"> The expression does not change the
observable state of the world save for possibly affecting the state of
the garbage collector by performing an allocation. Expressions
that only have generative effects and whose results are unused
may be eliminated by the compiler. However, unlike expressions with
“no effects”, such expressions will never be eligible for duplication.
</dd><dt class="dt-description"><span class="c013">Arbitrary effects:</span></dt><dd class="dd-description"> All other expressions.
</dd></dl><p>There is a single classification for coeffects:
</p><dl class="description"><dt class="dt-description">
<span class="c013">No coeffects:</span></dt><dd class="dd-description"> The expression does not observe the effects (in
the sense described above) of other expressions. For example, it must not
read from any mutable storage or call arbitrary external functions.
</dd></dl><p>It is assumed in the compiler that, subject to data dependencies,
expressions with neither effects nor coeffects may be reordered with
respect to other expressions.</p>
<!--TOC section id="s:flambda-static-modules" 21.13  Compilation of statically-allocated modules-->
<h2 class="section" id="s:flambda-static-modules"><a class="section-anchor" href="#s:flambda-static-modules" aria-hidden="true"></a>21.13  Compilation of statically-allocated modules</h2><!--SEC END --><p>Compilation of modules that are able to be statically allocated (for example,
the module corresponding to an entire compilation unit, as opposed to a first
class module dependent on values computed at runtime) initially follows the
strategy used for bytecode. A sequence of <span class="c003">let</span>-bindings, which may be
interspersed with arbitrary effects, surrounds a record creation that becomes
the module block. The Flambda-specific transformation follows: these bindings
are lifted to toplevel symbols, as described above.</p>
<!--TOC section id="s:flambda-inhibition" 21.14  Inhibition of optimisation-->
<h2 class="section" id="s:flambda-inhibition"><a class="section-anchor" href="#s:flambda-inhibition" aria-hidden="true"></a>21.14  Inhibition of optimisation</h2><!--SEC END --><p>Especially when writing benchmarking suites that run non-side-effecting
algorithms in loops, it may be found that the optimiser entirely
elides the code being benchmarked. This behaviour can be prevented by
using the <span class="c003">Sys.opaque_identity</span> function (which indeed behaves as a
normal OCaml function and does not possess any “magic” semantics). The
documentation of the <span class="c003">Sys</span> module should be consulted for further details.</p>
<!--TOC section id="s:flambda-unsafe" 21.15  Use of unsafe operations-->
<h2 class="section" id="s:flambda-unsafe"><a class="section-anchor" href="#s:flambda-unsafe" aria-hidden="true"></a>21.15  Use of unsafe operations</h2><!--SEC END --><p>The behaviour of the Flambda simplification pass means that certain unsafe
operations, which may without Flambda or when using previous versions of
the compiler be safe, must not be used. This specifically refers to
functions found in the <span class="c003">Obj</span> module.</p><p>In particular, it is forbidden to change any value (for example using
<span class="c003">Obj.set_field</span> or <span class="c003">Obj.set_tag</span>) that is not mutable.
(Values returned from C stubs
are always treated as mutable.) The compiler will emit warning 59 if it
detects such a write—but it cannot warn in all cases. Here is an example
of code that will trigger the warning:
</p><pre>let f x =
  let a = 42, x in
  (Obj.magic a : int ref) := 1;
  fst a
</pre><p>The reason this is unsafe is because the simplification pass believes that
<span class="c003">fst a</span> holds the value <span class="c003">42</span>; and indeed it must, unless type
soundness has been broken via unsafe operations.</p><p>If it must be the case that code has to be written that triggers warning 59,
but the code is known to actually be correct (for some definition of
correct), then <span class="c003">Sys.opaque_identity</span> may be used to wrap the value
before unsafe operations are performed upon it. Great care must be taken
when doing this to ensure that the opacity is added at the correct place.
It must be emphasised that this use of <span class="c003">Sys.opaque_identity</span> is only
for <span class="c013">exceptional</span> cases. It should not be used in normal code or to
try to guide the optimiser.</p><p>As an example, this code will return the integer <span class="c003">1</span>:
</p><pre>let f x =
  let a = Sys.opaque_identity (42, x) in
  (Obj.magic a : int ref) := 1;
  fst a
</pre><p>However the following code will still return <span class="c003">42</span>:
</p><pre>let f x =
  let a = 42, x in
  Sys.opaque_identity (Obj.magic a : int ref) := 1;
  fst a
</pre><p>
High levels of inlining performed by Flambda may expose bugs in code
thought previously to be correct. Take care, for example, not
to add type annotations that claim some mutable value is always immediate
if it might be possible for an unsafe operation to update it to a boxed
value.</p>
<!--TOC section id="s:flambda-glossary" 21.16  Glossary-->
<h2 class="section" id="s:flambda-glossary"><a class="section-anchor" href="#s:flambda-glossary" aria-hidden="true"></a>21.16  Glossary</h2><!--SEC END --><p>The following terminology is used in this chapter of the manual.</p><dl class="description"><dt class="dt-description">
<span class="c013">Call site</span></dt><dd class="dd-description"> See <em>direct call site</em> and <em>indirect call site</em> below.
</dd><dt class="dt-description"><span class="c013">Closed function</span></dt><dd class="dd-description"> A function whose body has no free variables
except its parameters and any to which are bound other functions within
the same (possibly mutually-recursive) declaration.
</dd><dt class="dt-description"><span class="c013">Closure</span></dt><dd class="dd-description"> The runtime representation of a function. This
includes pointers to the code of the function
together with the values of any variables that are used in the body of
the function but actually defined outside of the function, in the
enclosing scope.
The values of such variables, collectively known as the
<em>environment</em>, are required because the function may be
invoked from a place where the original bindings of such variables are
no longer in scope. A group of possibly
mutually-recursive functions defined using <em>let rec</em> all share a
single closure. (Note to developers: in the Flambda source code a
<em>closure</em> always corresponds to a single function; a
<em>set of closures</em> refers to a group of such.)
</dd><dt class="dt-description"><span class="c013">Closure variable</span></dt><dd class="dd-description"> A member of the environment held within the
closure of a given function.
</dd><dt class="dt-description"><span class="c013">Constant</span></dt><dd class="dd-description"> Some entity (typically an expression) the value of which
is known by the compiler at compile time. Constantness may be explicit from
the source code or inferred by the Flambda optimisers.
</dd><dt class="dt-description"><span class="c013">Constant closure</span></dt><dd class="dd-description"> A closure that is statically allocated in an
object file. It is almost always the case that the environment portion of
such a closure is empty.
</dd><dt class="dt-description"><span class="c013">Defining expression</span></dt><dd class="dd-description"> The expression <span class="c003">e</span> in <span class="c003">let x = e in e’</span>.
</dd><dt class="dt-description"><span class="c013">Direct call site</span></dt><dd class="dd-description"> A place in a program’s code where a function is
called and it is known at compile time which function it will always be.
</dd><dt class="dt-description"><span class="c013">Indirect call site</span></dt><dd class="dd-description"> A place in a program’s code where a function
is called but is not known to be a <em>direct call site</em>.
</dd><dt class="dt-description"><span class="c013">Program</span></dt><dd class="dd-description"> A collection of <em>symbol bindings</em> forming the
definition of a single compilation unit (i.e. <span class="c003">.cmx</span> file).
</dd><dt class="dt-description"><span class="c013">Specialised argument</span></dt><dd class="dd-description"> An argument to a function that is known
to always hold a particular value at runtime. These are introduced by the
inliner when specialising recursive functions; and the <span class="c003">unbox-closures</span>
pass. (See section <a href="#s%3Aflambda-specialisation">21.4</a>.)
</dd><dt class="dt-description"><span class="c013">Symbol</span></dt><dd class="dd-description"> A name referencing a particular place in an object file
or executable image. At that particular place will be some constant value.
Symbols may be examined using operating system-specific tools (for
example <span class="c003">objdump</span> on Linux).
</dd><dt class="dt-description"><span class="c013">Symbol binding</span></dt><dd class="dd-description"> Analogous to a <span class="c003">let</span>-expression but working
at the level of symbols defined in the object file. The address of a symbol is
fixed, but it may be bound to both constant and non-constant expressions.
</dd><dt class="dt-description"><span class="c013">Toplevel</span></dt><dd class="dd-description"> An expression in the current program which is not
enclosed within any function declaration.
</dd><dt class="dt-description"><span class="c013">Variable</span></dt><dd class="dd-description"> A named entity to which some OCaml value is bound by a
<span class="c003">let</span> expression, pattern-matching construction, or similar.
</dd></dl>
<!--TOC chapter id="sec547" Chapter 22  Memory profiling with Spacetime-->
<h1 class="chapter" id="sec547">Chapter 22  Memory profiling with Spacetime</h1><!--SEC END --><!--NAME spacetime.html-->

<!--TOC section id="s:spacetime-overview" 22.1  Overview-->
<h2 class="section" id="s:spacetime-overview"><a class="section-anchor" href="#s:spacetime-overview" aria-hidden="true"></a>22.1  Overview</h2><!--SEC END --><p>Spacetime is the name given to functionality within the OCaml compiler that
provides for accurate profiling of the memory behaviour of a program.
Using Spacetime it is possible to determine the source of memory leaks
and excess memory allocation quickly and easily. Excess allocation slows
programs down both by imposing a higher load on the garbage collector and
reducing the cache locality of the program’s code. Spacetime provides
full backtraces for every allocation that occurred on the OCaml heap
during the lifetime of the program including those in C stubs.</p><p>Spacetime only analyses the memory behaviour of a program with respect to
the OCaml heap allocators and garbage collector. It does not analyse
allocation on the C heap. Spacetime does not affect the memory behaviour
of a program being profiled with the exception of any change caused by the
overhead of profiling (see section <a href="#s%3Aspacetime-runtimeoverhead">22.3</a>)—for example
the program running slower might cause it to allocate less memory in total.</p><p>Spacetime is currently only available for x86-64 targets and has only been
tested on Linux systems (although it is expected to work on most modern
Unix-like systems and provision has been made for running under
Windows). It is expected that the set of supported platforms will
be extended in the future.</p>
<!--TOC section id="s:spacetime-howto" 22.2  How to use it-->
<h2 class="section" id="s:spacetime-howto"><a class="section-anchor" href="#s:spacetime-howto" aria-hidden="true"></a>22.2  How to use it</h2><!--SEC END -->
<!--TOC subsection id="ss:spacetime-building" 22.2.1  Building-->
<h3 class="subsection" id="ss:spacetime-building"><a class="section-anchor" href="#ss:spacetime-building" aria-hidden="true"></a>22.2.1  Building</h3><!--SEC END --><p>To use Spacetime it is necessary to use an OCaml compiler that was
configured with the <span class="c003">-spacetime</span> option. It is not possible to select
Spacetime on a per-source-file basis or for a subset of files in a project;
all files involved in the executable being profiled must be built with the
Spacetime compiler. Only native code compilation is supported (not
bytecode).</p><p>If the <span class="c003">libunwind</span> library is not available on the system then it will
not be possible for Spacetime to profile allocations occurring within
C stubs. If the <span class="c003">libunwind</span> library is available but in an unusual
location then that location may be specified to the <span class="c003">configure</span> script
using the <span class="c003">-libunwinddir</span> option (or alternatively, using separate
<span class="c003">-libunwindinclude</span> and <span class="c003">-libunwindlib</span> options).</p><p>OPAM switches will be provided for Spacetime-configured compilers.</p><p>Once the appropriate compiler has been selected the program should be
built as normal (ensuring that all files are built with the Spacetime
compiler—there is currently no protection to ensure this is the case, but
it is essential). For many uses it will not be necessary to change the
code of the program to use the profiler.</p><p>Spacetime-configured compilers run slower and occupy more memory than their
counterparts. It is hoped this will be fixed in the future as part of
improved cross compilation support.</p>
<!--TOC subsection id="ss:spacetime-running" 22.2.2  Running-->
<h3 class="subsection" id="ss:spacetime-running"><a class="section-anchor" href="#ss:spacetime-running" aria-hidden="true"></a>22.2.2  Running</h3><!--SEC END --><p>Programs built with Spacetime instrumentation have a dependency on
the <span class="c003">libunwind</span> library unless that was unavailable at configure time or
the <span class="c003">-disable-libunwind</span> option was specified
(see section <a href="#s%3Aspacetime-runtimeoverhead">22.3</a>).</p><p>Setting the <span class="c003">OCAML_SPACETIME_INTERVAL</span> environment variable to an
integer representing a number of milliseconds before running a program built
with Spacetime will cause memory profiling to be in operation when the
program is started. The contents of the OCaml heap will be sampled each
time the number of milliseconds that the program has spent executing since the
last sample exceeds the given number. (Note that the time base is combined
user plus system time—<em>not</em> wall clock time. This peculiarity may be
changed in future.)</p><p>The program being profiled must exit normally or be caused to exit using
the <span class="c003">SIGINT</span> signal (e.g. by pressing Ctrl+C). When the program exits
files will be written in the directory that was the working directory when
the program was started. One Spacetime file will be written for each
process that was involved, indexed by process ID; there will normally only
be one such. The Spacetime files may be substantial. The directory to which
they are written may be overridden by setting
the <span class="c003">OCAML_SPACETIME_SNAPSHOT_DIR</span> environment variable before the
program is started.</p><p>Instead of using the automatic snapshot facility described above it is also
possible to manually control Spacetime profiling. (The environment variables
<span class="c003">OCAML_SPACETIME_INTERVAL</span> and <span class="c003">OCAML_SPACETIME_SNAPSHOT_DIR</span>
are then not relevant.) Full documentation as regards this method of profiling
is provided in the standard library documentation (section <a href="#c%3Astdlib">26</a>)
for the <span class="c003">Spacetime</span> module.</p>
<!--TOC subsection id="ss:spacetime-analysis" 22.2.3  Analysis-->
<h3 class="subsection" id="ss:spacetime-analysis"><a class="section-anchor" href="#ss:spacetime-analysis" aria-hidden="true"></a>22.2.3  Analysis</h3><!--SEC END --><p>The compiler distribution does not itself provide the facility for analysing
Spacetime output files; this is left to external tools. The first such tool
will appear in OPAM as a package called <span class="c003">prof_spacetime</span>. That tool will
provide interactive graphical and terminal-based visualisation of
the results of profiling.</p>
<!--TOC section id="s:spacetime-runtimeoverhead" 22.3  Runtime overhead-->
<h2 class="section" id="s:spacetime-runtimeoverhead"><a class="section-anchor" href="#s:spacetime-runtimeoverhead" aria-hidden="true"></a>22.3  Runtime overhead</h2><!--SEC END --><p>The runtime overhead imposed by Spacetime varies considerably depending on
the particular program being profiled. The overhead may be as low as
ten percent—but more usually programs should be expected to run at perhaps
a third or quarter of their normal speed. It is expected that this overhead
will be reduced in future versions of the compiler.</p><p>Execution speed of instrumented programs may be increased by using a compiler
configured with the <span class="c003">-disable-libunwind</span> option. This prevents collection
of profiling information from C stubs.</p><p>Programs running with Spacetime instrumentation consume significantly more
memory than their non-instrumented counterparts. It is expected that this
memory overhead will also be reduced in the future.</p>
<!--TOC section id="s:spacetime-dev" 22.4  For developers-->
<h2 class="section" id="s:spacetime-dev"><a class="section-anchor" href="#s:spacetime-dev" aria-hidden="true"></a>22.4  For developers</h2><!--SEC END --><p>The compiler distribution provides an “<span class="c003">otherlibs</span>” library called
<span class="c003">raw_spacetime_lib</span> for decoding Spacetime files. This library
provides facilities to read not only memory profiling information but also
the full dynamic call graph of the profiled program which is written into
Spacetime output files.</p><p>A library package <span class="c003">spacetime_lib</span> will be provided in OPAM
to provide an interface for decoding profiling information at a higher
level than that provided by <span class="c003">raw_spacetime_lib</span>.

</p>
<!--TOC chapter id="sec555" Chapter 23  Fuzzing with afl-fuzz-->
<h1 class="chapter" id="sec555">Chapter 23  Fuzzing with afl-fuzz</h1><!--SEC END --><!--NAME afl-fuzz.html-->

<!--TOC section id="s:afl-overview" 23.1  Overview-->
<h2 class="section" id="s:afl-overview"><a class="section-anchor" href="#s:afl-overview" aria-hidden="true"></a>23.1  Overview</h2><!--SEC END --><p>American fuzzy lop (“afl-fuzz”) is a <em>fuzzer</em>, a tool for
testing software by providing randomly-generated inputs, searching for
those inputs which cause the program to crash.</p><p>Unlike most fuzzers, afl-fuzz observes the internal behaviour of the
program being tested, and adjusts the test cases it generates to
trigger unexplored execution paths. As a result, test cases generated
by afl-fuzz cover more of the possible behaviours of the tested
program than other fuzzers.</p><p>This requires that programs to be tested are instrumented to
communicate with afl-fuzz. The native-code compiler “ocamlopt” can
generate such instrumentation, allowing afl-fuzz to be used against
programs written in OCaml.</p><p>For more information on afl-fuzz, see the website at
<a href="http://lcamtuf.coredump.cx/afl/">http://lcamtuf.coredump.cx/afl/</a>.
</p>
<!--TOC section id="s:afl-generate" 23.2  Generating instrumentation-->
<h2 class="section" id="s:afl-generate"><a class="section-anchor" href="#s:afl-generate" aria-hidden="true"></a>23.2  Generating instrumentation</h2><!--SEC END --><p>The instrumentation that afl-fuzz requires is not generated by
default, and must be explicitly enabled, by passing the <span class="c003">-afl-instrument</span> option to <span class="c003">ocamlopt</span>.</p><p>To fuzz a large system without modifying build tools, OCaml’s <span class="c003">configure</span> script also accepts the <span class="c003">afl-instrument</span> option. If
OCaml is configured with <span class="c003">afl-instrument</span>, then all programs
compiled by <span class="c003">ocamlopt</span> will be instrumented.</p>
<!--TOC subsection id="ss:afl-advanced" 23.2.1  Advanced options-->
<h3 class="subsection" id="ss:afl-advanced"><a class="section-anchor" href="#ss:afl-advanced" aria-hidden="true"></a>23.2.1  Advanced options</h3><!--SEC END --><p>In rare cases, it is useful to control the amount of instrumentation
generated. By passing the <span class="c003">-afl-inst-ratio N</span> argument to <span class="c003">ocamlopt</span> with <span class="c003">N</span> less than 100, instrumentation can be
generated for only N% of branches. (See the afl-fuzz documentation on
the parameter <span class="c003">AFL_INST_RATIO</span> for the precise effect of this).</p>
<!--TOC section id="s:afl-example" 23.3  Example-->
<h2 class="section" id="s:afl-example"><a class="section-anchor" href="#s:afl-example" aria-hidden="true"></a>23.3  Example</h2><!--SEC END --><p>As an example, we fuzz-test the following program, <span class="c003">readline.ml</span>:</p><pre>let _ =
  let s = read_line () in
  match Array.to_list (Array.init (String.length s) (String.get s)) with
    ['s'; 'e'; 'c'; 'r'; 'e'; 't'; ' '; 'c'; 'o'; 'd'; 'e'] -&gt; failwith "uh oh"
  | _ -&gt; ()
</pre><p>
There is a single input (the string “secret code”) which causes this
program to crash, but finding it by blind random search is infeasible.</p><p>Instead, we compile with afl-fuzz instrumentation enabled:
</p><pre>ocamlopt -afl-instrument readline.ml -o readline
</pre><p>Next, we run the program under afl-fuzz:
</p><pre>mkdir input
echo asdf &gt; input/testcase
mkdir output
afl-fuzz -i input -o output ./readline
</pre><p>By inspecting instrumentation output, the fuzzer finds the crashing input quickly.

</p>
<!--TOC chapter id="sec560" Chapter 24  Runtime tracing with the instrumented runtime-->
<h1 class="chapter" id="sec560">Chapter 24  Runtime tracing with the instrumented runtime</h1><!--SEC END --><!--NAME instrumented-runtime.html-->
<p>This chapter describes the OCaml instrumented runtime, a runtime variant
allowing the collection of events and metrics.</p><p>Collected metrics include time spent executing the <em>garbage collector</em>.
The overall execution time of individual pauses are measured
down to the time spent in specific parts of the garbage collection.
Insight is also given on memory allocation and motion by recording
the size of allocated memory blocks, as well as value promotions from the
<em>minor heap</em> to the <em>major heap</em>.</p>
<!--TOC section id="s:instr-runtime-overview" 24.1  Overview-->
<h2 class="section" id="s:instr-runtime-overview"><a class="section-anchor" href="#s:instr-runtime-overview" aria-hidden="true"></a>24.1  Overview</h2><!--SEC END --><p>Once compiled and linked with the instrumented runtime, any OCaml program
can generate <em>trace files</em> that can then be read
and analyzed by users in order to understand specific runtime behaviors.</p><p>The generated trace files are stored using the <em>Common Trace Format</em>, which
is a general purpose binary tracing format.
A complete trace consists of:
</p><ul class="itemize"><li class="li-itemize">
a <em>metadata file</em>, part of the OCaml distribution
</li><li class="li-itemize">and a <em>trace file</em>, generated by the runtime
 in the program being traced.
</li></ul><p>For more information on the <em>Common Trace Format</em>, see
<a href="https://diamon.org/ctf/">https://diamon.org/ctf/</a>.</p>
<!--TOC section id="s:instr-runtime-enabling" 24.2  Enabling runtime instrumentation-->
<h2 class="section" id="s:instr-runtime-enabling"><a class="section-anchor" href="#s:instr-runtime-enabling" aria-hidden="true"></a>24.2  Enabling runtime instrumentation</h2><!--SEC END --><p>For the following examples, we will use the following example program:</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input"> <span class="ocamlkeyword">module</span> SMap = Map.Make(String)

 <span class="ocamlkeyword">let</span> s i = String.make 512 (Char.chr (i <span class="ocamlkeyword">mod</span> 256))

 <span class="ocamlkeyword">let</span> clear map = SMap.fold (<span class="ocamlkeyword">fun</span> k _ m -&gt; SMap.remove k m) map map

 <span class="ocamlkeyword">let</span> <span class="ocamlkeyword">rec</span> seq i =
   <span class="ocamlkeyword">if</span> i = 0 <span class="ocamlkeyword">then</span> Seq.empty <span class="ocamlkeyword">else</span> <span class="ocamlkeyword">fun</span> () -&gt; (Seq.Cons (i, seq (i - 1)))

 <span class="ocamlkeyword">let</span> () =
   seq 1_000_000
   |&gt; Seq.fold_left (<span class="ocamlkeyword">fun</span> m i -&gt; SMap.add (s i) i m) SMap.empty
   |&gt; clear
   |&gt; ignore</div></div>

</div><p>The next step is to compile and link the program with the instrumented runtime.
This can be done by using the <span class="c003">-runtime-variant</span> flag:</p><pre>       ocamlopt -runtime-variant i program.ml -o program
</pre><p>
Note that the instrumented runtime is an alternative runtime for OCaml
programs. It is only referenced during the linking stage of the final
executable. This means that the compilation stage does not need to be altered
to enable instrumentation.</p><p>The resulting program can then be traced by running it with the environment
variable <span class="c003">OCAML_EVENTLOG_ENABLED</span>:</p><pre>        OCAML_EVENTLOG_ENABLED=1 ./program
</pre><p>
During execution, a trace file will be generated in the
program’s current working directory.</p><!--TOC subsubsection id="sss:instr-runtime-build-more" More build examples-->
<h4 class="subsubsection" id="sss:instr-runtime-build-more"><a class="section-anchor" href="#sss:instr-runtime-build-more" aria-hidden="true"></a>More build examples</h4><!--SEC END --><p>When using the <em>dune</em> build system, this compiler invocation can be
replicated using the <span class="c003">flags</span> <span class="c003">stanza</span> when building an executable.</p><pre>       (executable
         (name program)
         (flags "-runtime-variant=i"))
</pre><p>
The instrumented runtime can also be used with the OCaml bytecode interpreter.
This can be done by either using the
<span class="c003">-runtime-variant=i</span> flag when linking the program with <span class="c003">ocamlc</span>, or by running the generated
bytecode through <span class="c003">ocamlruni</span>:</p><pre>       ocamlc program.ml -o program.byte
       OCAML_EVENTLOG_ENABLED=1 ocamlruni program.byte
</pre><p>
See chapter <a href="#c%3Acamlc">9</a> and chapter <a href="#c%3Aruntime">11</a> for more information about
<span class="c003">ocamlc</span> and <span class="c003">ocamlrun</span>.</p>
<!--TOC section id="s:instr-runtime-read" 24.3  Reading traces-->
<h2 class="section" id="s:instr-runtime-read"><a class="section-anchor" href="#s:instr-runtime-read" aria-hidden="true"></a>24.3  Reading traces</h2><!--SEC END --><p>Traces generated by the instrumented runtime can be analyzed with tooling
available outside of the OCaml distribution.</p><p>A complete trace consists of a <em>metadata file</em> and a <em>trace file</em>.
Two simple ways to work with the traces are the <em>eventlog-tools</em> and
<em>babeltrace</em> libraries.</p>
<!--TOC subsection id="ss:instr-runtime-tools" 24.3.1  eventlog-tools-->
<h3 class="subsection" id="ss:instr-runtime-tools"><a class="section-anchor" href="#ss:instr-runtime-tools" aria-hidden="true"></a>24.3.1  eventlog-tools</h3><!--SEC END --><p>
<em>eventlog-tools</em> is a library implementing a parser, as well as a
a set of tools that allows to perform basic format conversions and analysis.</p><p>For more information about <em>eventlog-tools</em>, refer to the project’s
main page: <a href="https://github.com/ocaml-multicore/eventlog-tools">https://github.com/ocaml-multicore/eventlog-tools</a></p>
<!--TOC subsection id="ss:instr-runtime-babeltrace" 24.3.2  babeltrace-->
<h3 class="subsection" id="ss:instr-runtime-babeltrace"><a class="section-anchor" href="#ss:instr-runtime-babeltrace" aria-hidden="true"></a>24.3.2  babeltrace</h3><!--SEC END --><p><em>babeltrace</em> is a C library, as well as a Python binding and set of tools
that serve as the reference implementation for the <em>Common Trace Format</em>.
The <em>babeltrace</em> command line utility allows for a basic rendering
of a trace’s content, while the high level Python API can be used to
decode the trace and process them programmatically with libraries
such as <em>numpy</em> or <em>Jupyter</em>.</p><p>Unlike <em>eventlog-tools</em>, which possesses a specific knowledge of
OCaml’s <em>Common Trace Format</em> schema, it is required to provide
the OCaml <em>metadata</em> file to <em>babeltrace</em>.</p><p>The metadata file is available in the OCaml installation.
Its location can be obtained using the following command:</p><pre>        ocamlc -where
</pre><p>
The <em>eventlog_metadata</em> file can be found at this path and
copied in the same directory as the generated trace file.
However, <em>babeltrace</em> expects the file to be named
<span class="c003">metadata</span> in order to process the trace.
Thus, it will need to be renamed when copied to the trace’s directory.</p><p>Here is a naive decoder example, using <em>babeltrace</em>’s Python
library, and <em>Python 3.8</em>:</p><pre>
import subprocess
import shutil
import sys
import babeltrace as bt

def print_event(ev):
    print(ev['timestamp'])
    print(ev['pid'])
    if ev.name == "entry":
        print('entry_event')
        print(ev['phase'])
    if ev.name == "exit":
        print('exit_event')
        print(ev['phase'])
    if ev.name == "alloc":
        print(ev['count'])
        print(ev['bucket'])
    if ev.name == "counter":
        print(ev['count'])
        print(ev['kind'])
    if ev.name == "flush":
        print("flush")

def get_ocaml_dir():
    # Fetching OCaml's installation directory to extract the CTF metadata
    ocamlc_where = subprocess.run(['ocamlc', '-where'], stdout=subprocess.PIPE)
    ocaml_dir = ocamlc_where.stdout.decode('utf-8').rstrip('\n')
    return(ocaml_dir)

def main():
    trace_dir = sys.argv[1]
    ocaml_dir = get_ocaml_dir()
    metadata_path = ocaml_dir + "/eventlog_metadata"
    # copying the metadata to the trace's directory,
    # and renaming it to 'metadata'.
    shutil.copyfile(metadata_path, trace_dir + "/metadata")
    tr = bt.TraceCollection()
    tr.add_trace(trace_dir, 'ctf')
    for event in tr.events:
        print_event(event)

if __name__ == '__main__':
    main()

</pre><p>
This script expect to receive as an argument the directory containing the
trace file. It will then copy the <em>CTF</em> metadata file to the trace’s
directory, and then decode the trace, printing each event in the process.</p><p>For more information on <em>babeltrace</em>, see the website at:
<a href="https://babeltrace.org/">https://babeltrace.org/</a></p>
<!--TOC section id="s:instr-runtime-more" 24.4  Controlling instrumentation and limitations-->
<h2 class="section" id="s:instr-runtime-more"><a class="section-anchor" href="#s:instr-runtime-more" aria-hidden="true"></a>24.4  Controlling instrumentation and limitations</h2><!--SEC END -->
<!--TOC subsection id="ss:instr-runtime-prefix" 24.4.1  Trace filename-->
<h3 class="subsection" id="ss:instr-runtime-prefix"><a class="section-anchor" href="#ss:instr-runtime-prefix" aria-hidden="true"></a>24.4.1  Trace filename</h3><!--SEC END --><p>The default trace filename is <span class="c003">caml-{PID}.eventlog</span>, where <span class="c003">{PID}</span>
is the process identifier of the traced program.</p><p>This filename can also be specified using the
<span class="c003">OCAML_EVENTLOG_PREFIX</span> environment variable.
The given path will be suffixed with <span class="c003">{.PID}.eventlog</span>.</p><pre>        OCAML_EVENTLOG_PREFIX=/tmp/a_prefix OCAML_EVENTLOG_ENABLED=1 ./program
</pre><p>
In this example, the trace will be available at path
<span class="c003">/tmp/a_prefix.{PID}.eventlog</span>.</p><p>Note that this will only affect the prefix of the trace file, there is no
option to specify the full effective file name.
This restriction is in place to make room for future improvements to the
instrumented runtime, where the single trace file per session design
may be replaced.</p><p>For scripting purpose, matching against ‘{PID}‘, as well as the
<span class="c003">.eventlog</span> file extension should provide enough control over
the generated files.</p><p>Note as well that parent directories in the given path will not be created
when opening the trace. The runtime assumes the path is
accessible for creating and writing the trace. The program will
fail to start if this requirement isn’t met.</p>
<!--TOC subsection id="ss:instr-runtime-pause" 24.4.2  Pausing and resuming tracing-->
<h3 class="subsection" id="ss:instr-runtime-pause"><a class="section-anchor" href="#ss:instr-runtime-pause" aria-hidden="true"></a>24.4.2  Pausing and resuming tracing</h3><!--SEC END --><p>
Mechanisms are available to control event collection at runtime.</p><p><span class="c003">OCAML_EVENTLOG_ENABLED</span> can be set to the <span class="c003">p</span> flag in order
to start the program with event collection paused.</p><pre>        OCAML_EVENTLOG_ENABLED=p ./program
</pre><p>
The program will have to start event collection explicitly.
Starting and stopping event collection programmatically can be done by calling
<span class="c003">Gc.eventlog_resume</span> and <span class="c003">Gc.eventlog_pause</span>) from within the program.
Refer to the <a href="libref/Gc.html"><span class="c003">Gc</span></a> module documentation for more information.</p><p>Running the program provided earlier with <span class="c003">OCAML_EVENTLOG_ENABLED=p</span>
will for example yield the following result.</p><pre>$ OCAML_EVENTLOG_ENABLED=p ./program
$ ocaml-eventlog-report caml-{PID}.eventlog
==== eventlog/flush
median flush time: 58ns
total flush time: 58ns
flush count: 1
</pre><p>
The resulting trace contains only one event payload, namely a <em>flush</em> event,
indicating how much time was spent flushing the trace file to disk.</p><p>However, if the program is changed to include a call to
<span class="c003">Gc.eventlog_resume</span>, events payloads can be seen again
in the trace file.</p><div class="caml-example verbatim">

<div class="ocaml">



<div class="pre caml-input">        <span class="ocamlkeyword">let</span> () =
          Gc.eventlog_resume();
          seq 1_000_000
          |&gt; Seq.fold_left (<span class="ocamlkeyword">fun</span> m i -&gt; SMap.add (s i) i m) SMap.empty
          |&gt; clear
          |&gt; ignore</div></div>

</div><p>The resulting trace will contain all events encountered during
the program’s execution:</p><pre>        $ ocaml-eventlog-report caml-{PID}.eventlog
        [..omitted..]
        ==== force_minor/alloc_small
        100.0K..200.0K: 174
        20.0K..30.0K: 1
        0..100: 1

        ==== eventlog/flush
        median flush time: 207.8us
        total flush time: 938.1us
        flush count: 5
</pre>
<!--TOC subsection id="ss:instr-runtime-limitations" 24.4.3  Limitations-->
<h3 class="subsection" id="ss:instr-runtime-limitations"><a class="section-anchor" href="#ss:instr-runtime-limitations" aria-hidden="true"></a>24.4.3  Limitations</h3><!--SEC END --><p>The instrumented runtime does not support the <span class="c003">fork</span> system call.
A child process forked from an instrumented program will not be traced.</p><p>The instrumented runtime aims to provide insight into the runtime’s execution
while maintaining a low overhead.
However, this overhead may become more noticeable depending on how a program
executes.
The instrumented runtime currently puts a strong emphasis on
tracing <em>garbage collection</em> events. This means that programs
with heavy garbage collection activity may be more susceptible to
tracing induced performance penalties.</p><p>While providing an accurate estimate of potential performance loss is difficult,
test on various OCaml programs showed a total running time increase ranging
from 1% to 8%.</p><p>For a program with an extended running time where the collection of only a
small sample of events is required, using the <em>eventlog_resume</em> and
<em>eventlog_pause</em> primitives may help relieve some of the
tracing induced performance impact.
</p>
<!--TOC part id="sec571" Part IV  The OCaml library-->
<table class="center"><tr><td><h1 class="part" id="sec571">Part IV<br>
The OCaml library</h1></td></tr>
</table><!--SEC END --><p>
<a id="p:library"></a>
</p>
<!--TOC chapter id="sec572" Chapter 25  The core library-->
<h1 class="chapter" id="sec572">Chapter 25  The core library</h1><!--SEC END --><p> <a id="c:corelib"></a></p><!--NAME core.html-->
<p>This chapter describes the OCaml core library, which is
composed of declarations for built-in types and exceptions, plus
the module <span class="c003">Stdlib</span> that provides basic operations on these
built-in types. The <span class="c003">Stdlib</span> module is special in two
ways:
</p><ul class="itemize"><li class="li-itemize">
It is automatically linked with the user’s object code files by
the <span class="c003">ocamlc</span> command (chapter <a href="#c%3Acamlc">9</a>).</li><li class="li-itemize">It is automatically “opened” when a compilation starts, or
when the toplevel system is launched. Hence, it is possible to use
unqualified identifiers to refer to the functions provided by the
<span class="c003">Stdlib</span> module, without adding a <span class="c003">open Stdlib</span> directive.
</li></ul><!--TOC section id="s:core-conventions" Conventions-->
<h2 class="section" id="s:core-conventions"><a class="section-anchor" href="#s:core-conventions" aria-hidden="true"></a>Conventions</h2><!--SEC END --><p>The declarations of the built-in types and the components of module
<span class="c003">Stdlib</span> are printed one by one in typewriter font, followed by a
short comment. All library modules and the components they provide are
indexed at the end of this report.</p>
<!--TOC section id="s:core-builtins" 25.1  Built-in types and predefined exceptions-->
<h2 class="section" id="s:core-builtins"><a class="section-anchor" href="#s:core-builtins" aria-hidden="true"></a>25.1  Built-in types and predefined exceptions</h2><!--SEC END --><p>The following built-in types and predefined exceptions are always
defined in the
compilation environment, but are not part of any module. As a
consequence, they can only be referred by their short names.</p><!--TOC subsection id="ss:builtin-types" Built-in types-->
<h3 class="subsection" id="ss:builtin-types"><a class="section-anchor" href="#ss:builtin-types" aria-hidden="true"></a>Built-in types</h3><!--SEC END --><pre> type int
</pre><p><a id="hevea_manual6"></a>
</p><blockquote class="quote">
The type of integer numbers.
</blockquote><pre> type char
</pre><p><a id="hevea_manual7"></a>
</p><blockquote class="quote">
The type of characters.
</blockquote><pre> type bytes
</pre><p><a id="hevea_manual8"></a>
</p><blockquote class="quote">
The type of (writable) byte sequences.
</blockquote><pre> type string
</pre><p><a id="hevea_manual9"></a>
</p><blockquote class="quote">
The type of (read-only) character strings.
</blockquote><pre> type float
</pre><p><a id="hevea_manual10"></a>
</p><blockquote class="quote">
The type of floating-point numbers.
</blockquote><pre> type bool = false | true
</pre><p><a id="hevea_manual11"></a>
</p><blockquote class="quote">
The type of booleans (truth values).
</blockquote><pre> type unit = ()
</pre><p><a id="hevea_manual12"></a>
</p><blockquote class="quote">
The type of the unit value.
</blockquote><pre> type exn
</pre><p><a id="hevea_manual13"></a>
</p><blockquote class="quote">
The type of exception values.
</blockquote><pre> type 'a array
</pre><p><a id="hevea_manual14"></a>
</p><blockquote class="quote">
The type of arrays whose elements have type <span class="c003">'a</span>.
</blockquote><pre> type 'a list = [] | :: of 'a * 'a list
</pre><p><a id="hevea_manual15"></a>
</p><blockquote class="quote">
The type of lists whose elements have type <span class="c003">'a</span>.
</blockquote><pre>type 'a option = None | Some of 'a
</pre><p><a id="hevea_manual16"></a>
</p><blockquote class="quote">
The type of optional values of type <span class="c003">'a</span>.
</blockquote><pre>type int32
</pre><p><a id="hevea_manual17"></a>
</p><blockquote class="quote">
The type of signed 32-bit integers.
Literals for 32-bit integers are suffixed by l.
See the <a href="libref/Int32.html"><span class="c003">Int32</span></a> module.
</blockquote><pre>type int64
</pre><p><a id="hevea_manual18"></a>
</p><blockquote class="quote">
The type of signed 64-bit integers.
Literals for 64-bit integers are suffixed by L.
See the <a href="libref/Int64.html"><span class="c003">Int64</span></a> module.
</blockquote><pre>type nativeint
</pre><p><a id="hevea_manual19"></a>
</p><blockquote class="quote">
The type of signed, platform-native integers (32 bits on 32-bit
processors, 64 bits on 64-bit processors).
Literals for native integers are suffixed by n.
See the <a href="libref/Nativeint.html"><span class="c003">Nativeint</span></a> module.
</blockquote><pre>type ('a, 'b, 'c, 'd, 'e, 'f) format6
</pre><p><a id="hevea_manual20"></a>
</p><blockquote class="quote">
The type of format strings. <span class="c003">'a</span> is the type of the parameters of
the format, <span class="c003">'f</span> is the result type for the <span class="c003">printf</span>-style
functions, <span class="c003">'b</span> is the type of the first argument given to <span class="c003">%a</span> and
<span class="c003">%t</span> printing functions (see module <a href="libref/Printf.html"><span class="c003">Printf</span></a>),
<span class="c003">'c</span> is the result type of these functions, and also the type of the
argument transmitted to the first argument of <span class="c003">kprintf</span>-style
functions, <span class="c003">'d</span> is the result type for the <span class="c003">scanf</span>-style functions
(see module <a href="libref/Scanf.html"><span class="c003">Scanf</span></a>), and <span class="c003">'e</span> is the type of the receiver function
for the <span class="c003">scanf</span>-style functions.
</blockquote><pre>type 'a lazy_t
</pre><p><a id="hevea_manual21"></a>
</p><blockquote class="quote">
This type is used to implement the <a href="libref/Lazy.html"><span class="c003">Lazy</span></a> module.
It should not be used directly.
</blockquote><!--TOC subsection id="ss:predef-exn" Predefined exceptions-->
<h3 class="subsection" id="ss:predef-exn"><a class="section-anchor" href="#ss:predef-exn" aria-hidden="true"></a>Predefined exceptions</h3><!--SEC END --><pre>exception Match_failure of (string * int * int)
</pre><p><a id="hevea_manual22"></a>
</p><blockquote class="quote">
Exception raised when none of the cases of a pattern-matching
apply. The arguments are the location of the <span class="c003">match</span> keyword
in the source code (file name, line number, column number).
</blockquote><pre>exception Assert_failure of (string * int * int)
</pre><p><a id="hevea_manual23"></a>
</p><blockquote class="quote">
Exception raised when an assertion fails. The arguments are
the location of the <span class="c003">assert</span> keyword in the source code
(file name, line number, column number).
</blockquote><pre>exception Invalid_argument of string
</pre><p><a id="hevea_manual24"></a>
</p><blockquote class="quote">
Exception raised by library functions to signal that the given
arguments do not make sense. The string gives some information
to the programmer. As a general rule, this exception should not
be caught, it denotes a programming error and the code should be
modified not to trigger it.
</blockquote><pre>exception Failure of string
</pre><p><a id="hevea_manual25"></a>
</p><blockquote class="quote">
Exception raised by library functions to signal that they are
undefined on the given arguments. The string is meant to give some
information to the programmer; you must <em>not</em> pattern match on
the string literal because it may change in future versions (use
<code>Failure _</code> instead).
</blockquote><pre>exception Not_found
</pre><p><a id="hevea_manual26"></a>
</p><blockquote class="quote">
Exception raised by search functions when the desired object
could not be found.
</blockquote><pre>exception Out_of_memory
</pre><p><a id="hevea_manual27"></a>
</p><blockquote class="quote">
Exception raised by the garbage collector when there is
insufficient memory to complete the computation. (Not reliable for
allocations on the minor heap.)
</blockquote><pre>exception Stack_overflow
</pre><p><a id="hevea_manual28"></a>
</p><blockquote class="quote">
Exception raised by the bytecode interpreter when the evaluation
stack reaches its maximal size. This often indicates infinite or
excessively deep recursion in the user’s program. Before 4.10, it
was not fully implemented by the native-code compiler.
</blockquote><pre>exception Sys_error of string
</pre><p><a id="hevea_manual29"></a>
</p><blockquote class="quote">
Exception raised by the input/output functions to report an
operating system error. The string is meant to give some
information to the programmer; you must <em>not</em> pattern match on
the string literal because it may change in future versions (use
<code>Sys_error _</code> instead).
</blockquote><pre>exception End_of_file
</pre><p><a id="hevea_manual30"></a>
</p><blockquote class="quote">
Exception raised by input functions to signal that the
end of file has been reached.
</blockquote><pre>exception Division_by_zero
</pre><p><a id="hevea_manual31"></a>
</p><blockquote class="quote">
Exception raised by integer division and remainder operations
when their second argument is zero.
</blockquote><pre>exception Sys_blocked_io
</pre><p><a id="hevea_manual32"></a>
</p><blockquote class="quote">
A special case of <span class="c003">Sys_error</span> raised when no I/O is possible
on a non-blocking I/O channel.
</blockquote><pre>exception Undefined_recursive_module of (string * int * int)
</pre><p><a id="hevea_manual33"></a>
</p><blockquote class="quote">
Exception raised when an ill-founded recursive module definition
is evaluated. (See section <a href="#s%3Arecursive-modules">8.2</a>.)
The arguments are the location of the definition in the source code
(file name, line number, column number).
</blockquote>
<!--TOC section id="s:stdlib-module" 25.2  Module <span class="c003">Stdlib</span>: the initially opened module-->
<h2 class="section" id="s:stdlib-module"><a class="section-anchor" href="#s:stdlib-module" aria-hidden="true"></a>25.2  Module <span class="c003">Stdlib</span>: the initially opened module</h2><!--SEC END --><ul class="ftoc2"><li class="li-links">
<a href="libref/Stdlib.html">Module <span class="c003">Stdlib</span>: the initially opened module</a>
</li><li class="li-links">Module <span class="c003">Pervasives</span>: deprecated alias for Stdlib
</li></ul>
<!--TOC chapter id="sec578" Chapter 26  The standard library-->
<h1 class="chapter" id="sec578">Chapter 26  The standard library</h1><!--SEC END --><p> <a id="c:stdlib"></a></p><!--NAME stdlib.html-->
<p>This chapter describes the functions provided by the OCaml
standard library. The modules from the standard library are
automatically linked with the user’s object code files by the <span class="c003">ocamlc</span>
command. Hence, these modules can be used in standalone programs without
having to add any <span class="c003">.cmo</span> file on the command line for the linking
phase. Similarly, in interactive use, these globals can be used in
toplevel phrases without having to load any <span class="c003">.cmo</span> file in memory.</p><p>Unlike the core <span class="c003">Stdlib</span> module, submodules are not automatically
“opened” when compilation starts, or when the toplevel system is launched.
Hence it is necessary to use qualified identifiers to refer to the functions
provided by these modules, or to add <span class="c003">open</span> directives.</p><p><a id="stdlib:top"></a></p><!--TOC section id="s:stdlib-conv" Conventions-->
<h2 class="section" id="s:stdlib-conv"><a class="section-anchor" href="#s:stdlib-conv" aria-hidden="true"></a>Conventions</h2><!--SEC END --><p>For easy reference, the modules are listed below in alphabetical order
of module names.
For each module, the declarations from its signature are printed
one by one in typewriter font, followed by a short comment.
All modules and the identifiers they export are indexed at the end of
this report.</p><ul class="ftoc2"><li class="li-links">
<a href="libref/Arg.html">Module <span class="c003">Arg</span>: parsing of command line arguments</a>
</li><li class="li-links"><a href="libref/Array.html">Module <span class="c003">Array</span>: array operations</a>
</li><li class="li-links"><a href="libref/ArrayLabels.html">Module <span class="c003">ArrayLabels</span>: array operations (with labels)</a>
</li><li class="li-links"><a href="libref/Bigarray.html">Module <span class="c003">Bigarray</span>: large, multi-dimensional, numerical arrays</a>
</li><li class="li-links"><a href="libref/Bool.html">Module <span class="c003">Bool</span>: boolean values</a>
</li><li class="li-links"><a href="libref/Buffer.html">Module <span class="c003">Buffer</span>: extensible buffers</a>
</li><li class="li-links"><a href="libref/Bytes.html">Module <span class="c003">Bytes</span>: byte sequences</a>
</li><li class="li-links"><a href="libref/BytesLabels.html">Module <span class="c003">BytesLabels</span>: byte sequences (with labels)</a>
</li><li class="li-links"><a href="libref/Callback.html">Module <span class="c003">Callback</span>: registering OCaml values with the C runtime</a>
</li><li class="li-links"><a href="libref/Char.html">Module <span class="c003">Char</span>: character operations</a>
</li><li class="li-links"><a href="libref/Complex.html">Module <span class="c003">Complex</span>: Complex numbers</a>
</li><li class="li-links"><a href="libref/Digest.html">Module <span class="c003">Digest</span>: MD5 message digest</a>
</li><li class="li-links"><a href="libref/Ephemeron.html">Module <span class="c003">Ephemeron</span>: Ephemerons and weak hash table</a>
</li><li class="li-links"><a href="libref/Filename.html">Module <span class="c003">Filename</span>: operations on file names</a>
</li><li class="li-links"><a href="libref/Float.html">Module <span class="c003">Float</span>: Floating-point numbers</a>
</li><li class="li-links"><a href="libref/Format.html">Module <span class="c003">Format</span>: pretty printing</a>
</li><li class="li-links"><a href="libref/Fun.html">Module <span class="c003">Fun</span>: function values</a>
</li><li class="li-links"><a href="libref/Gc.html">Module <span class="c003">Gc</span>: memory management control and statistics; finalized values</a>
</li><li class="li-links"><a href="libref/Genlex.html">Module <span class="c003">Genlex</span>: a generic lexical analyzer</a>
</li><li class="li-links"><a href="libref/Hashtbl.html">Module <span class="c003">Hashtbl</span>: hash tables and hash functions</a>
</li><li class="li-links"><a href="libref/Int.html">Module <span class="c003">Int</span>: integers</a>
</li><li class="li-links"><a href="libref/Int32.html">Module <span class="c003">Int32</span>: 32-bit integers</a>
</li><li class="li-links"><a href="libref/Int64.html">Module <span class="c003">Int64</span>: 64-bit integers</a>
</li><li class="li-links"><a href="libref/Lazy.html">Module <span class="c003">Lazy</span>: deferred computations</a>
</li><li class="li-links"><a href="libref/Lexing.html">Module <span class="c003">Lexing</span>: the run-time library for lexers generated by <span class="c003">ocamllex</span></a>
</li><li class="li-links"><a href="libref/List.html">Module <span class="c003">List</span>: list operations</a>
</li><li class="li-links"><a href="libref/ListLabels.html">Module <span class="c003">ListLabels</span>: list operations (with labels)</a>
</li><li class="li-links"><a href="libref/Map.html">Module <span class="c003">Map</span>: association tables over ordered types</a>
</li><li class="li-links"><a href="libref/Marshal.html">Module <span class="c003">Marshal</span>: marshaling of data structures</a>
</li><li class="li-links"><a href="libref/MoreLabels.html">Module <span class="c003">MoreLabels</span>: Include modules <span class="c003">Hashtbl</span>, <span class="c003">Map</span> and <span class="c003">Set</span> with labels</a>
</li><li class="li-links"><a href="libref/Nativeint.html">Module <span class="c003">Nativeint</span>: processor-native integers</a>
</li><li class="li-links"><a href="libref/Oo.html">Module <span class="c003">Oo</span>: object-oriented extension</a>
</li><li class="li-links"><a href="libref/Option.html">Module <span class="c003">Option</span>: option values</a>
</li><li class="li-links"><a href="libref/Parsing.html">Module <span class="c003">Parsing</span>: the run-time library for parsers generated by <span class="c003">ocamlyacc</span></a>
</li><li class="li-links"><a href="libref/Printexc.html">Module <span class="c003">Printexc</span>: facilities for printing exceptions</a>
</li><li class="li-links"><a href="libref/Printf.html">Module <span class="c003">Printf</span>: formatting printing functions</a>
</li><li class="li-links"><a href="libref/Queue.html">Module <span class="c003">Queue</span>: first-in first-out queues</a>
</li><li class="li-links"><a href="libref/Random.html">Module <span class="c003">Random</span>: pseudo-random number generator (PRNG)</a>
</li><li class="li-links"><a href="libref/Result.html">Module <span class="c003">Result</span>: result values</a>
</li><li class="li-links"><a href="libref/Scanf.html">Module <span class="c003">Scanf</span>: formatted input functions</a>
</li><li class="li-links"><a href="libref/Seq.html">Module <span class="c003">Seq</span>: functional iterators</a>
</li><li class="li-links"><a href="libref/Set.html">Module <span class="c003">Set</span>: sets over ordered types</a>
</li><li class="li-links"><a href="libref/Spacetime.html">Module <span class="c003">Spacetime</span>: memory profiler</a>
</li><li class="li-links"><a href="libref/Stack.html">Module <span class="c003">Stack</span>: last-in first-out stacks</a>
</li><li class="li-links"><a href="libref/StdLabels.html">Module <span class="c003">StdLabels</span>: Include modules <span class="c003">Array</span>, <span class="c003">List</span> and <span class="c003">String</span> with labels</a>
</li><li class="li-links"><a href="libref/Stream.html">Module <span class="c003">Stream</span>: streams and parsers</a>
</li><li class="li-links"><a href="libref/String.html">Module <span class="c003">String</span>: string operations</a>
</li><li class="li-links"><a href="libref/StringLabels.html">Module <span class="c003">StringLabels</span>: string operations (with labels)</a>
</li><li class="li-links"><a href="libref/Sys.html">Module <span class="c003">Sys</span>: system interface</a>
</li><li class="li-links"><a href="libref/Uchar.html">Module <span class="c003">Uchar</span>: Unicode characters</a>
</li><li class="li-links"><a href="libref/Unit.html">Module <span class="c003">Unit</span>: unit values</a>
</li><li class="li-links"><a href="libref/Weak.html">Module <span class="c003">Weak</span>: arrays of weak pointers</a>
</li></ul>
<!--TOC chapter id="sec580" Chapter 27  The compiler front-end-->
<h1 class="chapter" id="sec580">Chapter 27  The compiler front-end</h1><!--SEC END --><p> <a id="c:parsinglib"></a></p><!--NAME parsing.html-->
<p>
<a id="Compiler-underscorelibs"></a> </p><p>This chapter describes the OCaml front-end, which declares the abstract
syntax tree used by the compiler, provides a way to parse, print
and pretty-print OCaml code, and ultimately allows one to write abstract
syntax tree preprocessors invoked via the <span class="c003">-ppx</span> flag (see chapters <a href="#c%3Acamlc">9</a>
and <a href="#c%3Anativecomp">12</a>).</p><p>It is important to note that the exported front-end interface follows the evolution of the OCaml language and implementation, and thus does not provide <span class="c013">any</span> backwards compatibility guarantees.</p><p>The front-end is a part of <span class="c003">compiler-libs</span> library.
Programs that use the <span class="c003">compiler-libs</span> library should be built as follows:
</p><pre>
        ocamlfind ocamlc <span class="c009">other options</span> -package compiler-libs.common <span class="c009">other files</span>
        ocamlfind ocamlopt <span class="c009">other options</span> -package compiler-libs.common <span class="c009">other files</span>
</pre><p>
Use of the <span class="c003">ocamlfind</span> utility is recommended. However, if this is not possible, an alternative method may be used:
</p><pre>
        ocamlc <span class="c009">other options</span> -I +compiler-libs ocamlcommon.cma <span class="c009">other files</span>
        ocamlopt <span class="c009">other options</span> -I +compiler-libs ocamlcommon.cmxa <span class="c009">other files</span>
</pre><p>
For interactive use of the <span class="c003">compiler-libs</span> library, start <span class="c003">ocaml</span> and
type<br>
<span class="c003">#load "compiler-libs/ocamlcommon.cma";;</span>.</p><ul class="ftoc2"><li class="li-links">
<a href="compilerlibref/Ast_helper.html">Module <span class="c003">Ast_helper</span>: helper functions for AST construction</a>
</li><li class="li-links"><a href="compilerlibref/Ast_mapper.html">Module <span class="c003">Ast_mapper</span>: -ppx rewriter interface</a>
</li><li class="li-links"><a href="compilerlibref/Asttypes.html">Module <span class="c003">Asttypes</span>: auxiliary types used by Parsetree</a>
</li><li class="li-links"><a href="compilerlibref/Location.html">Module <span class="c003">Location</span>: source code locations</a>
</li><li class="li-links"><a href="compilerlibref/Longident.html">Module <span class="c003">Longident</span>: long identifiers</a>
</li><li class="li-links"><a href="compilerlibref/Parse.html">Module <span class="c003">Parse</span>: OCaml syntax parsing</a>
</li><li class="li-links"><a href="compilerlibref/Parsetree.html">Module <span class="c003">Parsetree</span>: OCaml syntax tree</a>
</li><li class="li-links"><a href="compilerlibref/Pprintast.html">Module <span class="c003">Pprintast</span>: OCaml syntax printing</a>
</li></ul>
<!--TOC chapter id="sec581" Chapter 28  The unix library: Unix system calls-->
<h1 class="chapter" id="sec581">Chapter 28  The unix library: Unix system calls</h1><!--SEC END --><!--NAME libunix.html-->
<p>
<a id="c:unix"></a></p><p>The <span class="c003">unix</span> library makes many Unix
system calls and system-related library functions available to
OCaml programs. This chapter describes briefly the functions
provided. Refer to sections 2 and 3 of the Unix manual for more
details on the behavior of these functions.</p><ul class="ftoc2"><li class="li-links">
<a href="libref/Unix.html">Module <span class="c003">Unix</span>: Unix system calls</a>
</li><li class="li-links"><a href="libref/UnixLabels.html">Module <span class="c003">UnixLabels</span>: Labeled
Unix system calls</a>
</li></ul><p>Not all functions are provided by all Unix variants. If some functions
are not available, they will raise <span class="c003">Invalid_arg</span> when called.</p><p>Programs that use the <span class="c003">unix</span> library must be linked as follows:
</p><pre>
        ocamlc <span class="c009">other options</span> unix.cma <span class="c009">other files</span>
        ocamlopt <span class="c009">other options</span> unix.cmxa <span class="c009">other files</span>
</pre><p>
For interactive use of the <span class="c003">unix</span> library, do:
</p><pre>
        ocamlmktop -o mytop unix.cma
        ./mytop
</pre><p>
or (if dynamic linking of C libraries is supported on your platform),
start <span class="c003">ocaml</span> and type <span class="c003">#load "unix.cma";;</span>.</p><blockquote class="quote"><span class="c007">Windows:</span>  
A fairly complete emulation of the Unix system calls is provided in
the Windows version of OCaml. The end of this chapter gives
more information on the functions that are not supported under Windows.
</blockquote><blockquote class="quote"><span class="c007">Windows:</span>  
The Cygwin port of OCaml fully implements all functions from
the Unix module. The native Win32 ports implement a subset of them.
Below is a list of the functions that are not implemented, or only
partially implemented, by the Win32 ports. Functions not mentioned are
fully implemented and behave as described previously in this chapter.<div class="tableau">
<div class="center"><table class="c000 cellpadding1" border=1><tr><td class="c014"><span class="c013">Functions</span></td><td class="c014"><span class="c013">Comment</span> </td></tr>
<tr><td class="c022">
<span class="c003">fork</span></td><td class="c021">not implemented, use <span class="c003">create_process</span> or threads </td></tr>
<tr><td class="c022"><span class="c003">wait</span></td><td class="c021">not implemented, use <span class="c003">waitpid</span> </td></tr>
<tr><td class="c022"><span class="c003">waitpid</span></td><td class="c021">can only wait for a given PID, not any child process </td></tr>
<tr><td class="c022"><span class="c003">getppid</span></td><td class="c021">not implemented (meaningless under Windows) </td></tr>
<tr><td class="c022"><span class="c003">nice</span></td><td class="c021">not implemented </td></tr>
<tr><td class="c022"><span class="c003">truncate</span>, <span class="c003">ftruncate</span></td><td class="c021">not implemented </td></tr>
<tr><td class="c022"><span class="c003">link</span></td><td class="c021">implemented (since 3.02) </td></tr>
<tr><td class="c022"><span class="c003">symlink</span>, <span class="c003">readlink</span></td><td class="c021">implemented (since 4.03.0) </td></tr>
<tr><td class="c022"><span class="c003">access</span></td><td class="c021">execute permission <span class="c003">X_OK</span> cannot be tested,
it just tests for read permission instead </td></tr>
<tr><td class="c022"><span class="c003">fchmod</span></td><td class="c021">not implemented </td></tr>
<tr><td class="c022"><span class="c003">chown</span>, <span class="c003">fchown</span></td><td class="c021">not implemented (make no sense on a DOS
file system) </td></tr>
<tr><td class="c022"><span class="c003">umask</span></td><td class="c021">not implemented </td></tr>
<tr><td class="c022"><span class="c003">mkfifo</span></td><td class="c021">not implemented </td></tr>
<tr><td class="c022"><span class="c003">kill</span></td><td class="c021">partially implemented (since 4.00.0): only the <span class="c003">sigkill</span> signal
is implemented </td></tr>
<tr><td class="c022"><span class="c003">pause</span></td><td class="c021">not implemented (no inter-process signals in Windows) </td></tr>
<tr><td class="c022"><span class="c003">alarm</span></td><td class="c021">not implemented </td></tr>
<tr><td class="c022"><span class="c003">times</span></td><td class="c021">partially implemented, will not report timings for child
processes </td></tr>
<tr><td class="c022"><span class="c003">getitimer</span>, <span class="c003">setitimer</span></td><td class="c021">not implemented </td></tr>
<tr><td class="c022"><span class="c003">getuid</span>, <span class="c003">geteuid</span>, <span class="c003">getgid</span>, <span class="c003">getegid</span></td><td class="c021">always return 1 </td></tr>
<tr><td class="c022"><span class="c003">getgroups</span></td><td class="c021">always returns <span class="c003">[|1|]</span> (since 2.00) </td></tr>
<tr><td class="c022"><span class="c003">setuid</span>, <span class="c003">setgid</span>, <span class="c003">setgroups</span></td><td class="c021">not implemented </td></tr>
<tr><td class="c022"><span class="c003">getpwnam</span>, <span class="c003">getpwuid</span></td><td class="c021">always raise <span class="c003">Not_found</span> </td></tr>
<tr><td class="c022"><span class="c003">getgrnam</span>, <span class="c003">getgrgid</span></td><td class="c021">always raise <span class="c003">Not_found</span> </td></tr>
<tr><td class="c022">type <span class="c003">socket_domain</span></td><td class="c021"><span class="c003">PF_INET</span> is fully supported;
<span class="c003">PF_INET6</span> is fully supported (since 4.01.0); <span class="c003">PF_UNIX</span> is not supported  </td></tr>
<tr><td class="c022"><span class="c003">establish_server</span></td><td class="c021">not implemented; use threads </td></tr>
<tr><td class="c022">terminal functions (<span class="c003">tc*</span>)</td><td class="c021">not implemented </td></tr>
</table></div></div></blockquote>
<!--TOC chapter id="sec582" Chapter 29  The num library: arbitrary-precision rational arithmetic-->
<h1 class="chapter" id="sec582">Chapter 29  The num library: arbitrary-precision rational arithmetic</h1><!--SEC END --><!--NAME libnum.html-->
<p>The <span class="c003">num</span> library implements integer arithmetic and rational
arithmetic in arbitrary precision. It was split off the core
OCaml distribution starting with the 4.06.0 release, and can now be found
at <a href="https://github.com/ocaml/num"><span class="c003">https://github.com/ocaml/num</span></a>.</p><p>New applications that need arbitrary-precision arithmetic should use the
<span class="c003">Zarith</span> library (<a href="https://github.com/ocaml/Zarith"><span class="c003">https://github.com/ocaml/Zarith</span></a>) instead of the <span class="c003">Num</span>
library, and older applications that already use <span class="c003">Num</span> are encouraged to
switch to <span class="c003">Zarith</span>. <span class="c003">Zarith</span> delivers much better performance than <span class="c003">Num</span>
and has a nicer API.

</p>
<!--TOC chapter id="sec583" Chapter 30  The str library: regular expressions and string processing-->
<h1 class="chapter" id="sec583">Chapter 30  The str library: regular expressions and string processing</h1><!--SEC END --><!--NAME libstr.html-->
<p>The <span class="c003">str</span> library provides high-level string processing functions,
some based on regular expressions. It is intended to support the kind
of file processing that is usually performed with scripting languages
such as <span class="c003">awk</span>, <span class="c003">perl</span> or <span class="c003">sed</span>.</p><p>Programs that use the <span class="c003">str</span> library must be linked as follows:
</p><pre>
        ocamlc <span class="c009">other options</span> str.cma <span class="c009">other files</span>
        ocamlopt <span class="c009">other options</span> str.cmxa <span class="c009">other files</span>
</pre><p>
For interactive use of the <span class="c003">str</span> library, do:
</p><pre>
        ocamlmktop -o mytop str.cma
        ./mytop
</pre><p>
or (if dynamic linking of C libraries is supported on your platform),
start <span class="c003">ocaml</span> and type <span class="c003">#load "str.cma";;</span>.</p><ul class="ftoc2"><li class="li-links">
<a href="libref/Str.html">Module <span class="c003">Str</span>: regular expressions and string processing</a>
</li></ul>
<!--TOC chapter id="sec584" Chapter 31  The threads library-->
<h1 class="chapter" id="sec584">Chapter 31  The threads library</h1><!--SEC END --><p>
<a id="c:threads"></a></p><!--NAME threads.html-->
<!--NAME libthreads.html-->
<p><span class="c013">Warning:</span> the <span class="c003">threads</span> library is deprecated since version
4.08.0 of OCaml. Please switch to system threads, which have the same
API. Lightweight threads with VM-level scheduling are provided by
third-party libraries such as Lwt, but with a different API.</p><p>The <span class="c003">threads</span> library allows concurrent programming in OCaml.
It provides multiple threads of control (also called lightweight
processes) that execute concurrently in the same memory space. Threads
communicate by in-place modification of shared data structures, or by
sending and receiving data on communication channels.</p><p>The <span class="c003">threads</span> library is implemented by time-sharing on a single
processor. It will not take advantage of multi-processor machines.
Using this library will therefore never make programs run
faster. However, many programs are easier to write when structured as
several communicating processes.</p><p>Two implementations of the <span class="c003">threads</span> library are available, depending
on the capabilities of the operating system:
</p><ul class="itemize"><li class="li-itemize">
System threads. This implementation builds on the OS-provided threads
facilities: POSIX 1003.1c threads for Unix, and Win32 threads for
Windows. When available, system threads support both bytecode and
native-code programs.
</li><li class="li-itemize">VM-level threads. This implementation performs time-sharing and
context switching at the level of the OCaml virtual machine (bytecode
interpreter). It is available on Unix systems, and supports only
bytecode programs. It cannot be used with native-code programs.
</li></ul><p>
Programs that use system threads must be linked as follows:
</p><pre>
        ocamlc -I +threads <span class="c009">other options</span> unix.cma threads.cma <span class="c009">other files</span>
        ocamlopt -I +threads <span class="c009">other options</span> unix.cmxa threads.cmxa <span class="c009">other files</span>
</pre><p>
Compilation units that use the <span class="c003">threads</span> library must also be compiled with
the <span class="c003">-I +threads</span> option (see chapter <a href="#c%3Acamlc">9</a>).</p><ul class="ftoc2"><li class="li-links">
<a href="libref/Thread.html">Module <span class="c003">Thread</span>: lightweight threads</a>
</li><li class="li-links"><a href="libref/Mutex.html">Module <span class="c003">Mutex</span>: locks for mutual exclusion</a>
</li><li class="li-links"><a href="libref/Condition.html">Module <span class="c003">Condition</span>: condition variables to synchronize between threads</a>
</li><li class="li-links"><a href="libref/Event.html">Module <span class="c003">Event</span>: first-class synchronous communication</a>
</li><li class="li-links"><a href="libref/ThreadUnix.html">Module <span class="c003">ThreadUnix</span>: thread-compatible system calls</a>
</li></ul>
<!--TOC chapter id="sec585" Chapter 32  The graphics library-->
<h1 class="chapter" id="sec585">Chapter 32  The graphics library</h1><!--SEC END --><!--NAME libgraph.html-->
<p>Since OCaml 4.09, the <span class="c003">graphics</span> library is distributed as an external
package. Its new home is:</p><p><a href="https://github.com/ocaml/graphics"><span class="c003">https://github.com/ocaml/graphics</span></a></p><p>If you are using the opam package manager, you should install the
corresponding <span class="c003">graphics</span> package:</p><pre>
        opam install graphics
</pre><p>Before OCaml 4.09, this package simply ensures that the <span class="c003">graphics</span>
library was installed by the compiler, and starting from OCaml 4.09
this package effectively provides the <span class="c003">graphics</span> library.

</p>
<!--TOC chapter id="sec586" Chapter 33  The dynlink library: dynamic loading and linking of object files-->
<h1 class="chapter" id="sec586">Chapter 33  The dynlink library: dynamic loading and linking of object files</h1><!--SEC END --><!--NAME libdynlink.html-->
<p>The <span class="c003">dynlink</span> library supports type-safe dynamic loading and linking
of bytecode object files (<span class="c003">.cmo</span> and <span class="c003">.cma</span> files) in a running
bytecode program, or of native plugins (usually <span class="c003">.cmxs</span> files) in a
running native program. Type safety is ensured by limiting the set of
modules from the running program that the loaded object file can
access, and checking that the running program and the loaded object
file have been compiled against the same interfaces for these modules.
In native code, there are also some compatibility checks on the
implementations (to avoid errors with cross-module optimizations); it
might be useful to hide <span class="c003">.cmx</span> files when building native plugins so
that they remain independent of the implementation of modules in the
main program.</p><p>Programs that use the <span class="c003">dynlink</span> library simply need to link
<span class="c003">dynlink.cma</span> or <span class="c003">dynlink.cmxa</span> with their object files and other libraries.</p><p><span class="c013">Note:</span> in order to insure that the dynamically-loaded modules have
access to all the libraries that are visible to the main program (and not just
to the parts of those libraries that are actually used in the main program),
programs using the <span class="c003">dynlink</span> library should be linked with <span class="c003">-linkall</span>.</p><ul class="ftoc2"><li class="li-links">
<a href="libref/Dynlink.html">Module <span class="c003">Dynlink</span>: dynamic loading of bytecode object files</a>
</li></ul>
<!--TOC chapter id="sec587" Chapter 34  The bigarray library-->
<h1 class="chapter" id="sec587">Chapter 34  The bigarray library</h1><!--SEC END --><!--NAME libbigarray.html-->
<p>The <span class="c003">bigarray</span> library has now been integrated into OCaml’s standard
library.</p><p>The <span class="c003">bigarray</span> functionality may now be found in the standard library
<a href="libref/Bigarray.html"><span class="c003">Bigarray</span> module</a>,
except for the <span class="c003">map_file</span> function which is now
part of the <a href="#c%3Aunix">Unix library</a>. The documentation has
been integrated into the documentation for the standard library.</p><p>The legacy <span class="c003">bigarray</span> library bundled with the compiler is a
compatibility library with exactly the same interface as before,
i.e. with <span class="c003">map_file</span> included.</p><p>We strongly recommend that you port your code to use the standard
library version instead, as the changes required are minimal.</p><p>If you choose to use the compatibility library, you must link your
programs as follows:
</p><pre>
        ocamlc <span class="c009">other options</span> bigarray.cma <span class="c009">other files</span>
        ocamlopt <span class="c009">other options</span> bigarray.cmxa <span class="c009">other files</span>
</pre><p>
For interactive use of the <span class="c003">bigarray</span> compatibility library, do:
</p><pre>
        ocamlmktop -o mytop bigarray.cma
        ./mytop
</pre><p>
or (if dynamic linking of C libraries is supported on your platform),
start <span class="c003">ocaml</span> and type <span class="c003">#load "bigarray.cma";;</span>.
</p>
<!--TOC part id="sec588" Part V  Appendix-->
<table class="center"><tr><td><h1 class="part" id="sec588">Part V<br>
Appendix</h1></td></tr>
</table><!--SEC END --><p>
<a id="p:appendix"></a></p><ul class="ftoc2"><li class="li-links">
<a href="libref/index_modules.html">Index of modules</a>
</li><li class="li-links"><a href="libref/index_module_types.html">Index of module types</a>
</li><li class="li-links"><a href="libref/index_types.html">Index of types</a>
</li><li class="li-links"><a href="libref/index_exceptions.html">Index of exceptions</a>
</li><li class="li-links"><a href="libref/index_values.html">Index of values</a>
</li></ul><!--TOC chapter id="sec589" Index of keywords-->
<h1 class="chapter" id="sec589">Index of keywords</h1><!--SEC END --><p></p><table class="c001 cellpading0"><tr><td class="c020"><ul class="indexenv"><li class="li-indexenv">
<span class="c003">and</span>, <a href="#hevea_manual.kwd21">7.7</a>, <a href="#hevea_manual.kwd93">7.8.1</a>, <a href="#hevea_manual.kwd122">7.9.2</a>, <a href="#hevea_manual.kwd144">7.9.3</a>, <a href="#hevea_manual.kwd146">7.9.4</a>, <a href="#hevea_manual.kwd149">7.9.5</a>, <a href="#hevea_manual.kwd154">7.10</a>, <a href="#hevea_manual.kwd183">7.11</a>, <a href="#hevea_manual.kwd207">8.2</a>, <a href="#hevea_manual.kwd215">8.5</a>
</li><li class="li-indexenv"><span class="c003">as</span>, <a href="#hevea_manual.kwd7">7.4</a>, <a href="#hevea_manual.kwd8">7.4</a>, <a href="#hevea_manual.kwd9">7.4</a>, <a href="#hevea_manual.kwd15">7.6</a>, <a href="#hevea_manual.kwd16">7.6</a>, <a href="#hevea_manual.kwd17">7.6</a>, <a href="#hevea_manual.kwd124">7.9.2</a>, <a href="#hevea_manual.kwd132">7.9.2</a>
</li><li class="li-indexenv"><span class="c003">asr</span>, <a href="#hevea_manual.kwd6">7.3</a>, <a href="#hevea_manual.kwd57">7.7.1</a>, <a href="#hevea_manual.kwd76">7.7.5</a>, <a href="#hevea_manual.kwd83">7.7.5</a>
</li><li class="li-indexenv"><span class="c003">assert</span>, <a href="#hevea_manual.kwd86">7.7.8</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">begin</span>, <a href="#hevea_manual.kwd13">7.5</a>, <a href="#hevea_manual.kwd38">7.7</a>, <a href="#hevea_manual.kwd58">7.7.2</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">class</span>, <a href="#hevea_manual.kwd143">7.9.3</a>, <a href="#hevea_manual.kwd145">7.9.4</a>, <a href="#hevea_manual.kwd147">7.9.5</a>, <a href="#hevea_manual.kwd159">7.10</a>, <a href="#hevea_manual.kwd169">7.10.2</a>, <a href="#hevea_manual.kwd170">7.10.2</a>, <a href="#hevea_manual.kwd187">7.11</a>, <a href="#hevea_manual.kwd197">7.11.2</a>, <a href="#hevea_manual.kwd198">7.11.2</a>
</li><li class="li-indexenv"><span class="c003">constraint</span>, <a href="#hevea_manual.kwd97">7.8.1</a>, <a href="#hevea_manual.kwd99">7.8.1</a>, <a href="#hevea_manual.kwd109">7.9.1</a>, <a href="#hevea_manual.kwd117">7.9.1</a>, <a href="#hevea_manual.kwd129">7.9.2</a>, <a href="#hevea_manual.kwd141">7.9.2</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">do</span>, see <span class="c009"><span class="c003">while</span>, <span class="c003">for</span></span>
</li><li class="li-indexenv"><span class="c003">done</span>, see <span class="c009"><span class="c003">while</span>, <span class="c003">for</span></span>
</li><li class="li-indexenv"><span class="c003">downto</span>, see <span class="c005">for</span>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">else</span>, see <span class="c005">if</span>
</li><li class="li-indexenv"><span class="c003">end</span>, <a href="#hevea_manual.kwd14">7.5</a>, <a href="#hevea_manual.kwd39">7.7</a>, <a href="#hevea_manual.kwd59">7.7.2</a>, <a href="#hevea_manual.kwd102">7.9.1</a>, <a href="#hevea_manual.kwd119">7.9.2</a>, <a href="#hevea_manual.kwd151">7.10</a>, <a href="#hevea_manual.kwd164">7.10.2</a>, <a href="#hevea_manual.kwd180">7.11</a>, <a href="#hevea_manual.kwd192">7.11.2</a>
</li><li class="li-indexenv"><span class="c003">exception</span>, <a href="#hevea_manual.kwd100">7.8.2</a>, <a href="#hevea_manual.kwd158">7.10</a>, <a href="#hevea_manual.kwd168">7.10.2</a>, <a href="#hevea_manual.kwd186">7.11</a>, <a href="#hevea_manual.kwd196">7.11.2</a>
</li><li class="li-indexenv"><span class="c003">external</span>, <a href="#hevea_manual.kwd156">7.10</a>, <a href="#hevea_manual.kwd166">7.10.2</a>, <a href="#hevea_manual.kwd184">7.11</a>, <a href="#hevea_manual.kwd194">7.11.2</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">false</span>, <a href="#hevea_manual.kwd11">7.5</a>
</li><li class="li-indexenv"><span class="c003">for</span>, <a href="#hevea_manual.kwd32">7.7</a>, <a href="#hevea_manual.kwd68">7.7.3</a>
</li><li class="li-indexenv"><span class="c003">fun</span>, <a href="#hevea_manual.kwd26">7.7</a>, <a href="#hevea_manual.kwd46">7.7.1</a>, <a href="#hevea_manual.kwd61">7.7.2</a>, <a href="#hevea_manual.kwd120">7.9.2</a>, <a href="#hevea_manual.kwd211">8.4</a>
</li><li class="li-indexenv"><span class="c003">function</span>, <a href="#hevea_manual.kwd25">7.7</a>, <a href="#hevea_manual.kwd47">7.7.1</a>, <a href="#hevea_manual.kwd60">7.7.2</a>
</li><li class="li-indexenv"><span class="c003">functor</span>, <a href="#hevea_manual.kwd152">7.10</a>, <a href="#hevea_manual.kwd177">7.10.3</a>, <a href="#hevea_manual.kwd181">7.11</a>, <a href="#hevea_manual.kwd205">7.11.3</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">if</span>, <a href="#hevea_manual.kwd35">7.7</a>, <a href="#hevea_manual.kwd45">7.7.1</a>, <a href="#hevea_manual.kwd64">7.7.3</a>
</li><li class="li-indexenv"><span class="c003">in</span>, see <span class="c005">let</span>
</li><li class="li-indexenv"><span class="c003">include</span>, <a href="#hevea_manual.kwd162">7.10</a>, <a href="#hevea_manual.kwd176">7.10.2</a>, <a href="#hevea_manual.kwd190">7.11</a>, <a href="#hevea_manual.kwd204">7.11.2</a>, <a href="#hevea_manual.kwd219">8.6</a>
</li><li class="li-indexenv"><span class="c003">inherit</span>, <a href="#hevea_manual.kwd103">7.9.1</a>, <a href="#hevea_manual.kwd110">7.9.1</a>, <a href="#hevea_manual.kwd123">7.9.2</a>, <a href="#hevea_manual.kwd131">7.9.2</a>
</li><li class="li-indexenv"><span class="c003">initializer</span>, <a href="#hevea_manual.kwd130">7.9.2</a>, <a href="#hevea_manual.kwd142">7.9.2</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">land</span>, <a href="#hevea_manual.kwd1">7.3</a>, <a href="#hevea_manual.kwd52">7.7.1</a>, <a href="#hevea_manual.kwd71">7.7.5</a>, <a href="#hevea_manual.kwd78">7.7.5</a>
</li><li class="li-indexenv"><span class="c003">lazy</span>, <a href="#hevea_manual.kwd18">7.6</a>, <a href="#hevea_manual.kwd43">7.7</a>, <a href="#hevea_manual.kwd87">7.7.8</a>
</li><li class="li-indexenv"><span class="c003">let</span>, <a href="#hevea_manual.kwd23">7.7</a>, <a href="#hevea_manual.kwd50">7.7.1</a>, <a href="#hevea_manual.kwd63">7.7.2</a>, <a href="#hevea_manual.kwd88">7.7.8</a>, <a href="#hevea_manual.kwd90">7.7.8</a>, <a href="#hevea_manual.kwd121">7.9.2</a>, <a href="#hevea_manual.kwd182">7.11</a>, <a href="#hevea_manual.kwd193">7.11.2</a>
</li><li class="li-indexenv"><span class="c003">lor</span>, <a href="#hevea_manual.kwd2">7.3</a>, <a href="#hevea_manual.kwd53">7.7.1</a>, <a href="#hevea_manual.kwd72">7.7.5</a>, <a href="#hevea_manual.kwd79">7.7.5</a>
</li><li class="li-indexenv"><span class="c003">lsl</span>, <a href="#hevea_manual.kwd4">7.3</a>, <a href="#hevea_manual.kwd55">7.7.1</a>, <a href="#hevea_manual.kwd74">7.7.5</a>, <a href="#hevea_manual.kwd81">7.7.5</a>
</li><li class="li-indexenv"><span class="c003">lsr</span>, <a href="#hevea_manual.kwd5">7.3</a>, <a href="#hevea_manual.kwd56">7.7.1</a>, <a href="#hevea_manual.kwd75">7.7.5</a>, <a href="#hevea_manual.kwd82">7.7.5</a>
</li></ul></td><td class="c020"><ul class="indexenv"><li class="li-indexenv"><span class="c003">lxor</span>, <a href="#hevea_manual.kwd3">7.3</a>, <a href="#hevea_manual.kwd54">7.7.1</a>, <a href="#hevea_manual.kwd73">7.7.5</a>, <a href="#hevea_manual.kwd80">7.7.5</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">match</span>, <a href="#hevea_manual.kwd37">7.7</a>, <a href="#hevea_manual.kwd48">7.7.1</a>, <a href="#hevea_manual.kwd65">7.7.3</a>, <a href="#hevea_manual.kwd226">8.10</a>
</li><li class="li-indexenv"><span class="c003">method</span>, <a href="#hevea_manual.kwd106">7.9.1</a>, <a href="#hevea_manual.kwd113">7.9.1</a>, <a href="#hevea_manual.kwd115">7.9.1</a>, <a href="#hevea_manual.kwd127">7.9.2</a>, <a href="#hevea_manual.kwd137">7.9.2</a>, <a href="#hevea_manual.kwd139">7.9.2</a>
</li><li class="li-indexenv"><span class="c003">mod</span>, <a href="#hevea_manual.kwd0">7.3</a>, <a href="#hevea_manual.kwd51">7.7.1</a>, <a href="#hevea_manual.kwd70">7.7.5</a>, <a href="#hevea_manual.kwd77">7.7.5</a>
</li><li class="li-indexenv"><span class="c003">module</span>, <a href="#hevea_manual.kwd89">7.7.8</a>, <a href="#hevea_manual.kwd160">7.10</a>, <a href="#hevea_manual.kwd172">7.10.2</a>, <a href="#hevea_manual.kwd174">7.10.2</a>, <a href="#hevea_manual.kwd188">7.11</a>, <a href="#hevea_manual.kwd200">7.11.2</a>, <a href="#hevea_manual.kwd202">7.11.2</a>, <a href="#hevea_manual.kwd206">8.2</a>, <a href="#hevea_manual.kwd212">8.5</a>, <a href="#hevea_manual.kwd216">8.6</a>, <a href="#hevea_manual.kwd221">8.7</a>, <a href="#hevea_manual.kwd223">8.8</a>
</li><li class="li-indexenv"><span class="c003">open</span>, <a href="#hevea_manual.kwd91">7.7.8</a>
</li><li class="li-indexenv"><span class="c003">mutable</span>, <a href="#hevea_manual.kwd96">7.8.1</a>, <a href="#hevea_manual.kwd98">7.8.1</a>, <a href="#hevea_manual.kwd105">7.9.1</a>, <a href="#hevea_manual.kwd112">7.9.1</a>, <a href="#hevea_manual.kwd126">7.9.2</a>, <a href="#hevea_manual.kwd134">7.9.2</a>, <a href="#hevea_manual.kwd136">7.9.2</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">new</span>, <a href="#hevea_manual.kwd41">7.7</a>, <a href="#hevea_manual.kwd84">7.7.6</a>
</li><li class="li-indexenv"><span class="c003">nonrec</span>, <a href="#hevea_manual.kwd94">7.8.1</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">object</span>, <a href="#hevea_manual.kwd42">7.7</a>, <a href="#hevea_manual.kwd85">7.7.6</a>, <a href="#hevea_manual.kwd101">7.9.1</a>, <a href="#hevea_manual.kwd118">7.9.2</a>
</li><li class="li-indexenv"><span class="c003">of</span>, <a href="#hevea_manual.kwd10">7.4</a>, <a href="#hevea_manual.kwd95">7.8.1</a>, <a href="#hevea_manual.kwd218">8.6</a>
</li><li class="li-indexenv"><span class="c003">open</span>, <a href="#hevea_manual.kwd19">7.6</a>, <a href="#hevea_manual.kwd161">7.10</a>, <a href="#hevea_manual.kwd175">7.10.2</a>, <a href="#hevea_manual.kwd189">7.11</a>, <a href="#hevea_manual.kwd203">7.11.2</a>
</li><li class="li-indexenv"><span class="c003">open!</span>, <a href="#hevea_manual.kwd224">8.9</a>
</li><li class="li-indexenv"><span class="c003">or</span>, <a href="#hevea_manual.kwd36">7.7</a>, <a href="#hevea_manual.kwd44">7.7.1</a>, <a href="#hevea_manual.kwd66">7.7.3</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">private</span>, <a href="#hevea_manual.kwd107">7.9.1</a>, <a href="#hevea_manual.kwd114">7.9.1</a>, <a href="#hevea_manual.kwd116">7.9.1</a>, <a href="#hevea_manual.kwd128">7.9.2</a>, <a href="#hevea_manual.kwd138">7.9.2</a>, <a href="#hevea_manual.kwd140">7.9.2</a>, <a href="#hevea_manual.kwd208">8.3</a>, <a href="#hevea_manual.kwd209">8.3.3</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">rec</span>, see <span class="c009"><span class="c003">let</span>, <span class="c003">module</span></span>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">sig</span>, <a href="#hevea_manual.kwd150">7.10</a>, <a href="#hevea_manual.kwd163">7.10.2</a>
</li><li class="li-indexenv"><span class="c003">struct</span>, <a href="#hevea_manual.kwd179">7.11</a>, <a href="#hevea_manual.kwd191">7.11.2</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">then</span>, see <span class="c005">if</span>
</li><li class="li-indexenv"><span class="c003">to</span>, see <span class="c005">for</span>
</li><li class="li-indexenv"><span class="c003">true</span>, <a href="#hevea_manual.kwd12">7.5</a>
</li><li class="li-indexenv"><span class="c003">try</span>, <a href="#hevea_manual.kwd24">7.7</a>, <a href="#hevea_manual.kwd49">7.7.1</a>, <a href="#hevea_manual.kwd69">7.7.3</a>
</li><li class="li-indexenv"><span class="c003">type</span>, <a href="#hevea_manual.kwd92">7.8.1</a>, <a href="#hevea_manual.kwd148">7.9.5</a>, <a href="#hevea_manual.kwd157">7.10</a>, <a href="#hevea_manual.kwd167">7.10.2</a>, <a href="#hevea_manual.kwd171">7.10.2</a>, <a href="#hevea_manual.kwd173">7.10.2</a>, <a href="#hevea_manual.kwd185">7.11</a>, <a href="#hevea_manual.kwd195">7.11.2</a>, <a href="#hevea_manual.kwd199">7.11.2</a>, <a href="#hevea_manual.kwd201">7.11.2</a>, <a href="#hevea_manual.kwd210">8.4</a>, <a href="#hevea_manual.kwd217">8.6</a>, <a href="#hevea_manual.kwd222">8.7</a>, <a href="#hevea_manual.kwd225">8.10</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">val</span>, <a href="#hevea_manual.kwd104">7.9.1</a>, <a href="#hevea_manual.kwd111">7.9.1</a>, <a href="#hevea_manual.kwd125">7.9.2</a>, <a href="#hevea_manual.kwd133">7.9.2</a>, <a href="#hevea_manual.kwd135">7.9.2</a>, <a href="#hevea_manual.kwd155">7.10</a>, <a href="#hevea_manual.kwd165">7.10.2</a>, <a href="#hevea_manual.kwd213">8.5</a>
</li><li class="li-indexenv"><span class="c003">virtual</span>, see <span class="c009"><span class="c003">val</span>, <span class="c003">method</span>, <span class="c003">class</span></span>
<br>
<br>
</li><li class="li-indexenv"><span class="c003">when</span>, <a href="#hevea_manual.kwd40">7.7</a>, <a href="#hevea_manual.kwd62">7.7.2</a>, <a href="#hevea_manual.kwd227">8.12</a>
</li><li class="li-indexenv"><span class="c003">while</span>, <a href="#hevea_manual.kwd67">7.7.3</a>
</li><li class="li-indexenv"><span class="c003">with</span>, <a href="#hevea_manual.kwd27">7.7</a>, <a href="#hevea_manual.kwd153">7.10</a>, <a href="#hevea_manual.kwd178">7.10.4</a>, <a href="#hevea_manual.kwd214">8.5</a>, <a href="#hevea_manual.kwd220">8.7</a>
</li></ul></td></tr>
</table><!--CUT END -->
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<hr style="height:2"><blockquote class="quote"><em>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</em><a href="http://hevea.inria.fr/index.html"><em>H<span class="c008"><sup>E</sup></span>V<span class="c008"><sup>E</sup></span>A</em></a><em>.</em></blockquote></body>
</html>