<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="Pa_do_nums.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Pa_do_nums" rel="Chapter" href="Pa_do_nums.html">
<link title="Pa_infix" rel="Chapter" href="Pa_infix.html"><link title="Pa_infix API" rel="Section" href="#api">
<title>Pa_infix</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Pa_do_nums.html" title="Pa_do_nums">Previous</a>
<a class="up" href="index.html" title="Index">Up</a>
</div>
<h1>Module <a href="type_Pa_infix.html">Pa_infix</a></h1>
<pre><span class="keyword">module</span> Pa_infix: <code class="code">sig</code> <a href="Pa_infix.html">..</a> <code class="code">end</code></pre><div class="info">
Syntax extension module to change the priority or associativity of
unary and binary operators. As these characteristics of operators
are global for a source file, the API also checks that no
conflicts occur.
<p>
There are two ways of using this syntax extension.
<p>
<h6 id="6_1">1. Using the API</h6>
<p>
Create a file, say my_syntax.ml, in which you <code class="code">open Pa_infix</code> and
use the API below to set the operators you need, compile it to an
object file and pass the latter to camlp4. The advantage of this
approach is that the created module can be reused with various
source files. This is the recommended way of proceeding if you
want to define new operators to ship with your OCaml library.
<p>
<h6 id="concrete">2. Using the concrete syntax</h6>
<p>
This approach is particularly useful when you quickly need to
define prefix/postfix/infix operators in a given source file. The
syntax is <code class="code">INFIX ( op )</code>, <code class="code">PREFIX ( op )</code>, and <code class="code">POSTFIX ( op )</code> to
respectively define binary infix, unary prefix, and unary postfix
operators. These can be followed by a precedence specification:
<code class="code">HIGHEST</code>, <code class="code">HIGHER ( op )</code>, <code class="code">LEVEL ( op )</code>, <code class="code">LOWER ( op )</code>, or
<code class="code">LOWEST</code>. Finally the associativity of infix operators can be set
with <code class="code">LEFTA</code> (left associative), <code class="code">RIGHTA</code> (right associative), or
<code class="code">NONA</code> (non-associative). Operators at the same level must have
the same associativity so associativity is inherited from <code class="code">op</code>
when you use <code class="code">LEVEL ( op )</code> (you cannot specify it).
<p>
Examples:
<pre class="codepre"><code class="code">
INFIX ( %+ ) RIGHTA HIGHER (+)
INFIX ( ^* ) LEVEL (+)
PREFIX ( /+/ )
POSTFIX ( /// ) LEVEL ( ! )
</code></pre>
<p>
In case the concrete syntax conflicts with keywords in your code,
it can be disabled by passing the option <code class="code">-no-pa-infix</code> to camlp4
(in which case only the first approach is possible).
<p>
<b>Remarks</b>
<p>
<ul>
<li>Standard OCaml operators (<code class="code">+</code>, <code class="code">-</code>,..., <code class="code">+.</code>,...) cannot be
changed. This is to prevent strange bugs from occurring by
changing the meaning of code that does not use new operators
(e.g. one certainly does not want <code class="code">+</code> to bind more tightly than
<code class="code">*</code> or <code class="code">-</code> to be right associative).
</li>
</ul>
<ul>
<li>Alphanetic operators are possible. Beware that setting an
alphabetic operator makes it a keyword, thus preventing it to be
used as a variable name anywhere else. To define an alphabetic
operator, say <code class="code">op</code>, use the syntax <code class="code">let ( op ) args = expr</code> --
just as you would do to redefine existing alphabetic operators
such as <code class="code">lsl</code>,... Beware that prefix and postfxix operators bind
more tightly than function evaluation (think of the dereference
operator <code class="code">!</code>). Use with care.
</li>
</ul>
<ul>
<li>If an operator is added even with its default level, the
operator will be considered as being set and it will not be
possible to change it further.</li>
</ul>
<br>
</div>
<hr width="100%">
<br>
<h1 id="api">Pa_infix API</h1><br>
<pre><span id="TYPEoperator"><span class="keyword">type</span> <code class="type"></code>operator</span> = <code class="type">string</code> </pre>
<div class="info">
Operators represented as their concrete string syntax.<br>
</div>
<pre><span id="EXCEPTIONNot_operator"><span class="keyword">exception</span> Not_operator</span> <span class="keyword">of</span> <code class="type"><a href="Pa_infix.html#TYPEoperator">operator</a></code></pre>
<div class="info">
<code class="code">Not_operator op</code> is raised if the string <code class="code">op</code> does not
designate a valid operator name.<br>
</div>
<pre><span id="EXCEPTIONForbidden"><span class="keyword">exception</span> Forbidden</span> <span class="keyword">of</span> <code class="type"><a href="Pa_infix.html#TYPEoperator">operator</a></code></pre>
<div class="info">
<code class="code">Forbidden op</code> is raised when the operator <code class="code">op</code> belongs to the
operators which precedence or associativity one is not allowed
to change.<br>
</div>
<pre><span class="keyword">module</span> <a href="Pa_infix.Level.html">Level</a>: <code class="code">sig</code> <a href="Pa_infix.Level.html">..</a> <code class="code">end</code></pre><div class="info">
Level of precedence of operators (also specifies their
associativity).
</div>
<pre><code><span id="TYPEkind"><span class="keyword">type</span> <code class="type"></code>kind</span> = </code></pre><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTkind.Prefix"><span class="constructor">Prefix</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTkind.Infix"><span class="constructor">Infix</span></span></code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTkind.Postfix"><span class="constructor">Postfix</span></span></code></td>
</tr></table>
<div class="info">
Possible kinds of operators.<br>
</div>
<pre><span id="EXCEPTIONConflicting_kind"><span class="keyword">exception</span> Conflicting_kind</span> <span class="keyword">of</span> <code class="type"><a href="Pa_infix.html#TYPEoperator">operator</a> * <a href="Pa_infix.html#TYPEkind">kind</a> * <a href="Pa_infix.html#TYPEkind">kind</a></code></pre>
<div class="info">
<code class="code">Conflicting_kind op k0 k</code> is raised when the kind of the operator
<code class="code">op</code> was <code class="code">k0</code> but now trying to set it to <code class="code">k</code>.<br>
</div>
<pre><span id="EXCEPTIONConflicting_level"><span class="keyword">exception</span> Conflicting_level</span> <span class="keyword">of</span> <code class="type"><a href="Pa_infix.html#TYPEoperator">operator</a> * string * string</code></pre>
<div class="info">
<code class="code">Conflicting_level op l0 l</code> is raised when the level of the operator
<code class="code">op</code> was <code class="code">l0</code> but now trying to set it to <code class="code">l</code>.<br>
</div>
<pre><span id="VALinfix"><span class="keyword">val</span> infix</span> : <code class="type"><a href="Pa_infix.html#TYPEoperator">operator</a> -><br> ?expr:(Camlp4.PreCast.Syntax.Ast.expr -><br> Camlp4.PreCast.Syntax.Ast.expr -><br> Camlp4.PreCast.Syntax.Ast.Loc.t -> Camlp4.PreCast.Syntax.Ast.expr) -><br> <a href="Pa_infix.Level.html#TYPEbinary">Level.binary</a> <a href="Pa_infix.Level.html#TYPEt">Level.t</a> -> unit</code></pre><div class="info">
<code class="code">infix op l</code> defines the operator <code class="code">op</code> as a binary infix
operator at level <code class="code">l</code>.<br>
<b>Raises</b><ul><li><code>Not_operator</code> if <code class="code">op</code> is not a valid operator name.</li>
<li><code>Forbidden</code> if the operator <code class="code">op</code> is not allowed.</li>
<li><code>Conflicting_kind</code> if there is a conflict with the kind of <code class="code">op</code>.</li>
<li><code>Conflicting_level</code> if there is a conflict with the level of <code class="code">op</code>.</li>
<li><code>Level.Bad_arity</code> if a <code class="code">'_a Level.t</code> is given which is not
a <code class="code">Level.binary Level.t</code>.</li>
</ul>
</div>
<div class="param_info"><code class="code">expr</code> : the function performing the operator subsititution:
the expression <code class="code">x op y</code> is transformed into <code class="code">expr x y _loc</code>. It
is the rewriting rule associated to <code class="code">x op y</code>. Note that this
can be used to simplify expressions <code class="code">x op y</code> but defines in no
way the <i>function</i> <code class="code">op</code> ; if you want <code class="code">op</code> also to work in
context where no arguments are provided immediately, you need to
bind <code class="code">op</code> to a compatible function: <code class="code">let (op) = ...</code>. The
default is to keep the function application: <code class="code">fun x y _loc ->
<:expr< $lid:op$ $x$ $y$ >></code>.</div>
<pre><span id="VALprefix"><span class="keyword">val</span> prefix</span> : <code class="type">?expr:(Camlp4.PreCast.Syntax.Ast.expr -><br> Camlp4.PreCast.Syntax.Ast.Loc.t -> Camlp4.PreCast.Syntax.Ast.expr) -><br> ?level:<a href="Pa_infix.Level.html#TYPEunary">Level.unary</a> <a href="Pa_infix.Level.html#TYPEt">Level.t</a> -> <a href="Pa_infix.html#TYPEoperator">operator</a> -> unit</code></pre><div class="info">
<code class="code">prefix op l</code> define the operator <code class="code">op</code> as a prefix operator at
level <code class="code">l</code>. Remark: if you use a prefix operator between braces,
make sure to put spaces between around the expressions. For
example, assuming you set <code class="code">/</code> as prefix, <code class="code">(/4)</code> is parsed as
"(/", "4" and ")", you have to write <code class="code">( /4 )</code> or <code class="code">( / 4 )</code> for
<code class="code">/</code> to be considered as a prefix operator. Note that, usually,
you will not need any braces as prefix operators bind more
tightly than evaluation: <code class="code">f /4 5</code> will be interpreted as <code class="code">f ( /4 ) 5</code>.<br>
<b>Raises</b><ul><li><code>Not_operator</code> if <code class="code">op</code> is not a valid operator name.</li>
<li><code>Forbidden</code> if the operator <code class="code">op</code> is not allowed.</li>
<li><code>Conflicting_kind</code> if there is a conflict with the kind of <code class="code">op</code>.</li>
<li><code>Conflicting_level</code> if there is a conflict with the level of <code class="code">op</code>.</li>
<li><code>Level.Bad_arity</code> if a <code class="code">'_a Level.t</code> is given which is not
a <code class="code">Level.unary Level.t</code>.</li>
</ul>
</div>
<div class="param_info"><code class="code">expr</code> : the function performing the operator subsititution:
the expression <code class="code">op x</code> is transformed into <code class="code">expr x _loc</code>.
Default: <code class="code">fun x _loc -> <:expr< $lid:op$ $x$ >></code>.</div>
<pre><span id="VALpostfix"><span class="keyword">val</span> postfix</span> : <code class="type">?expr:(Camlp4.PreCast.Syntax.Ast.expr -><br> Camlp4.PreCast.Syntax.Ast.Loc.t -> Camlp4.PreCast.Syntax.Ast.expr) -><br> ?level:<a href="Pa_infix.Level.html#TYPEunary">Level.unary</a> <a href="Pa_infix.Level.html#TYPEt">Level.t</a> -> <a href="Pa_infix.html#TYPEoperator">operator</a> -> unit</code></pre><div class="info">
<code class="code">postfix op l</code> define the operator <code class="code">op</code> as a postfix operator at
level <code class="code">l</code>. The same remarks as for <code class="code">prefix</code> apply.<br>
<b>Raises</b><ul><li><code>Not_operator</code> if <code class="code">op</code> is not a valid operator name.</li>
<li><code>Forbidden</code> if the operator <code class="code">op</code> is not allowed.</li>
<li><code>Conflicting_kind</code> if there is a conflict with the kind of <code class="code">op</code>.</li>
<li><code>Conflicting_level</code> if there is a conflict with the level of <code class="code">op</code>.</li>
<li><code>Level.Bad_arity</code> if a <code class="code">'_a Level.t</code> is given which is not a
<code class="code">Level.unary Level.t</code>.</li>
</ul>
</div>
<div class="param_info"><code class="code">expr</code> : the function performing the operator subsititution:
the expression <code class="code">x op</code> is transformed into <code class="code">expr x _loc</code>.
Default: <code class="code">fun x _loc -> <:expr< $lid:op$ $x$ >></code>.</div>
<pre><span id="VALassoc"><span class="keyword">val</span> assoc</span> : <code class="type"><a href="Pa_infix.html#TYPEoperator">operator</a> -> <a href="Pa_infix.Level.html#TYPEassoc">Level.assoc</a></code></pre><div class="info">
<code class="code">assoc op</code> returns the associativity of the operator <code class="code">op</code>.<br>
<b>Raises</b> <code>Not_operator</code> if <code class="code">op</code> is not a valid operator name.<br>
</div>
<pre><span id="VALlevel"><span class="keyword">val</span> level</span> : <code class="type"><a href="Pa_infix.html#TYPEoperator">operator</a> -> 'a <a href="Pa_infix.Level.html#TYPEt">Level.t</a></code></pre><div class="info">
<code class="code">pos op</code> returns the (default or assigned) level of the operator <code class="code">op</code>.<br>
<b>Raises</b> <code>Not_operator</code> if <code class="code">op</code> is not a valid operator name.<br>
</div>
<pre><span id="VALkind"><span class="keyword">val</span> kind</span> : <code class="type"><a href="Pa_infix.html#TYPEoperator">operator</a> -> <a href="Pa_infix.html#TYPEkind">kind</a></code></pre><div class="info">
<code class="code">kind op</code> returns the (default or assigned) kind of the operator <code class="code">op</code>.<br>
<b>Raises</b> <code>Not_operator</code> if <code class="code">op</code> is not a valid operator name.<br>
</div>
<pre><span id="VALis_operator"><span class="keyword">val</span> is_operator</span> : <code class="type"><a href="Pa_infix.html#TYPEoperator">operator</a> -> bool</code></pre><div class="info">
<code class="code">is_operator op</code> tells whether the string <code class="code">op</code> can be used as an
operator.<br>
</div>
<pre><span id="VALis_set"><span class="keyword">val</span> is_set</span> : <code class="type"><a href="Pa_infix.html#TYPEoperator">operator</a> -> bool</code></pre><div class="info">
<code class="code">is_set op</code> tells whether the operator <code class="code">op</code> has been set using
one of the functions of this API.<br>
<b>Raises</b> <code>Not_operator</code> if <code class="code">op</code> is not a valid operator name.<br>
</div>
<pre><span id="VALhandle_error"><span class="keyword">val</span> handle_error</span> : <code class="type">('a -> 'b) -> 'a -> 'b</code></pre><div class="info">
<code class="code">handle_error f a</code> applies <code class="code">f</code> to <code class="code">x</code> and returns the result.
If an exception of this library is raised, it prints a message
describing the error and exits with code 2.<br>
</div>
</body></html>
