<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<!-- $Id: locations.html 1823 2007-12-28 13:43:03Z deraugla $ -->
<!-- Copyright (c) 2007-2008 INRIA -->
<title>Locations</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<link rel="stylesheet" type="text/css" href="styles/base.css"
title="Normal" />
<link rel="alternate" type="application/rss+xml" href="rss/camlp5.rss"
title="Camlp5"/>
</head>
<body>
<div id="menu">
<h1>- <a href="http://pauillac.inria.fr/~ddr/camlp5">Camlp5</a> -</h1>
<p class="subtitle">Version 5.11</p>
<ul>
<li><a href="index.html">Introduction</a></li>
<li><a href="strict.html">Transitional and Strict</a></li>
<li><a href="ptools.html">Parsing and printing tools</a></li>
</ul>
<ul>
<li>Parsing tools
<ul>
<li><a href="parsers.html">Stream parsers</a></li>
<li><a href="lexers.html">Stream lexers</a></li>
<li><a href="fparsers.html">Functional parsers</a></li>
<li><a href="bparsers.html">Backtracking parsers</a></li>
<li><a href="grammars.html">Extensible grammars</a></li>
</ul>
</li>
<li>Printing tools
<ul>
<li><a href="printers.html">Extensible printers</a></li>
<li><a href="pprintf.html">Pprintf</a></li>
<li><a href="pretty.html">Pretty print</a></li>
</ul>
</li>
<li>Language extensions
<ul>
<li><a href="locations.html">Locations</a></li>
<li><a href="ml_ast.html">Syntax tree</a></li>
<li><a href="ast_transi.html">Syntax tree - transi</a></li>
<li><a href="ast_strict.html">Syntax tree - strict</a></li>
<li><a href="q_ast.html">Quotation kit q_ast.cmo</a></li>
<li><a href="pcaml.html">The Pcaml module</a></li>
<li><a href="syntext.html">Extensions of syntax</a></li>
<li><a href="opretty.html">Extensions of printing</a></li>
<li><a href="quot.html">Quotations</a></li>
<li><a href="revsynt.html">Revised syntax</a></li>
<li><a href="scheme.html">Scheme syntax</a></li>
<li><a href="macros.html">Macros</a></li>
<li><a href="pragma.html">Pragma directive</a></li>
<li><a href="extfun.html">Extensible functions</a></li>
</ul>
</li>
<li>Appendix
<ul>
<li><a href="commands.html">Commands and Files</a></li>
<li><a href="library.html">Library</a></li>
<li><a href="sources.html">Camlp5 sources</a></li>
<li><a href="about.html">About Camlp5</a></li>
</ul>
</li>
</ul>
</div>
<div id="content">
<h1 class="top">Locations</h1>
<p>The location is a concept often used in Camlp5, bound to where
errors occur in the source. The basic type is "<tt>Ploc.t</tt>"
which is an abstract type.</p>
<div id="tableofcontents">
<ol>
<li><a href="#a:Definitions">Definitions</a></li>
<li><a href="#a:Building-locations">Building locations</a></li>
<li><a href="#a:Raising-with-a-location">Raising with a location</a></li>
<li><a href="#a:Other-functions">Other functions</a></li>
</ol>
</div>
<h2 id="a:Definitions">Definitions</h2>
<p>Internally a location is a pair of source <em>positions</em>: the
beginning and the end of an element in the source (file or
interactive). A located element can be a character (the end is just
the beginning plus one), a token, or a longer sequence generally
corresponding to a grammar rule.</p>
<p>A <em>position</em> is a count of characters since the beginning of
the file, starting at zero. When a couple of positions define a
location, the first position is the position of the first character
of the element, and the last position is the first
character <em>not</em> part of the element. The location length is
the difference between those two numbers. Notice that the position
corresponds exactly to the character count in the streams of
characters.</p>
<p>In the <a href="grammars.html">extensible grammars</a>, a variable
with the specific name "<tt>loc</tt>" is predefined in all semantic
actions: it is the location of the associated rule. Since
the <a href="ml_ast.html">syntax tree quotations</a> generate nodes
with "<tt>loc</tt>" as location part, this allow to generate
grammars without having to consider source locations.</p>
<p>It is possible to change the name "<tt>loc</tt>" to another name,
through the parameter "<tt>-loc</tt>" of the Camlp5 commands.</p>
<p>Remark: the reason why the type "<tt>location</tt>" is abstract is
that in future versions, it may contain other informations, such as
the associated comments, the type (for expressions nodes), things
like that, without having to change the already written
programs.</p>
<h2 id="a:Building-locations">Building locations</h2>
<p>Tools are provided in the module "<tt>Ploc</tt>" to manage
locations.</p>
<p>First, "<tt>Ploc.dummy</tt>" is a dummy location used when the
element does not correspond to any source, or if the programmer does
not want to worry about locations.</p>
<p>The function "<tt>Ploc.make</tt>" builds a location from three
parameters:</p>
<ul>
<li>the line number, starting at 1</li>
<li>the position of the first column of the line</li>
<li>a couple of positions of the location: the first one belonging
to the given line, the second one being able to belong to another
line, further.</li>
</ul>
<p>If the line number is not known, it is possible to use the function
"<tt>Ploc.make_unlined</tt>" taking only the couple of positions of
the location. In this case, error messages may indicate the first
line and a big count of characters from this line (actually from the
beginning of the file). With a good text editor, it is possible, to
find the good location, anyway.</p>
<p>If the location is built with "<tt>Ploc.make_unlined</tt>", and if
your program displays a source location itself, it is possible to
use the function "<tt>Ploc.from_file</tt>" which takes the file
name and the location as parameters and return, by reading that
file, the line number, and the character positions of the
location.</p>
<h2 id="a:Raising-with-a-location">Raising with a location</h2>
<p>The function "<tt>Ploc.raise</tt>" allows one to raise an exception
together with a location. All exceptions raised in
the <a href="grammars.html">extensible grammars</a> use
"<tt>Ploc.raise</tt>". The raised exception is "<tt>Ploc.Exc</tt>"
with two parameters: the location and the exception itself.</p>
<p>Notice that "<tt>Ploc.raise</tt>" just reraises the exception
if it is already the exception "<tt>Ploc.Exc</tt>", ignoring then
the new given location.</p>
<p>A paradigm to print exceptions possibly enclosed by
"<tt>Ploc.Exc</tt>" is to write the "<tt>try..with</tt>" statement
like this:</p>
<pre>
try ... with exn ->
let exn =
match exn with
[ Ploc.Exc loc exn -> do { ... print the location ...; exn }
| _ -> exn ]
in
match exn with
...print the exception which is *not* located...
</pre>
<h2 id="a:Other-functions">Other functions</h2>
<p>Some other functions are provided:</p>
<dl>
<dt><tt>Ploc.first_pos</tt></dt>
<dd>returns the first position (an integer) of the location.</dd>
<dt><tt>Ploc.last_pos</tt></dt>
<dd>returns the last position (an integer) of the location (position
of the first character not belonging to the element.</dd>
<dt><tt>Ploc.line_nb</tt></dt>
<dd>returns the line number of the location or <tt>-1</tt> if the
location does not contain a line number (i.e. built by
"<tt>Ploc.make_unlined</tt>").</dd>
<dt><tt>Ploc.bol_pos</tt></dt>
<dd>returns the position of the beginning of the line of the
location. It is zero if the location does not contain a line
number (i.e. built by "<tt>Ploc.make_unlined</tt>").</dd>
</dl>
<p>And still other ones used in Camlp5 sources:</p>
<dl>
<dt><tt>Ploc.encl</tt></dt>
<dd>"<tt>Ploc.encl loc1 loc2</tt>" returns the location starting at
the smallest begin of "<tt>loc1</tt>" and "<tt>loc2</tt>" and
ending at their greatest end.. In simple words, it is the location
enclosing "<tt>loc1</tt>" and "<tt>loc2</tt>" and all what is
between them.</dd>
<dt><tt>Ploc.shift</tt></dt>
<dd>"<tt>Ploc.shift sh loc</tt>" returns the location "<tt>loc</tt>"
shifted with "<tt>sh</tt>" characters. The line number is not
recomputed.</dd>
<dt><tt>Ploc.sub</tt></dt>
<dd>"<tt>Ploc.sub loc sh len</tt>" is the location "<tt>loc</tt>"
shifted with "<tt>sh</tt>" characters and with length
"<tt>len</tt>". The previous ending position of the location is
lost.</dd>
<dt>"<tt>Ploc.after</tt>"</dt>
<dd>"<tt>Ploc.after loc sh len</tt>" is the location just after
"<tt>loc</tt>" (i.e. starting at the end position of
"<tt>loc</tt>"), shifted with "<tt>sh</tt>" characters, and of
length "<tt>len</tt>".</dd>
</dl>
<a class="toplink" href="locations.html">↑</a>
<div class="trailer">
<hr style="margin:0" /><div style="font-size: 80%"><em>Copyright 2007
Daniel de Rauglaudre (INRIA)</em></div>
<p class="bottom">
<a href="http://validator.w3.org/check?uri=referer"><img
src="images/valid-xhtml11.png" style="border:0"
alt="Valid XHTML 1.1" height="31" width="88" /></a>
</p>
</div>
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
15d4ac4853ddceb54c8d74e8c6e99bb2
>
files
>
17
