1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
<!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,v 6.3 2012-01-09 14:22:20 deraugla Exp $ -->
<!-- Copyright (c) INRIA 2007-2012 -->
<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" />
</head>
<body>
<div id="menu">
</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">
</div>
<h2>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>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>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>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>
<div class="trailer">
</div>
</div>
</body>
</html>
|
