Source location API - Revision history

Gray: /* Deprecated interface */

2017-06-15T18:40:08Z

Deprecated interface

Gray: /* Data Structures */

2017-06-15T18:38:09Z

Data Structures

Gray: /* Data Structures */

2017-06-15T18:37:44Z

Data Structures

Gray at 14:55, 15 June 2017

2017-06-15T14:55:39Z

Gray: /* Line Tracker */

2017-06-15T12:29:25Z

Line Tracker

Gray at 11:45, 15 June 2017

2017-06-15T11:45:18Z

Gray at 11:16, 15 June 2017

2017-06-15T11:16:11Z

Gray at 11:10, 15 June 2017

2017-06-15T11:10:10Z

Gray at 10:17, 15 June 2017

2017-06-15T10:17:29Z

Gray: Created page with "The source location API is designed to keep track of locations in source files for the diagnostic purposes. It is especially useful in parsers and lexical analyzers. == Data St..."

2017-06-15T09:55:20Z

Created page with "The source location API is designed to keep track of locations in source files for the diagnostic purposes. It is especially useful in parsers and lexical analyzers. == Data St..."

New page

The source location API is designed to keep track of locations in
source files for the diagnostic purposes. It is especially useful
in parsers and lexical analyzers.

== Data Structures ==

The basic data structure is <tt>mu_locus_point</tt>, which identifies
a point (''locus'') in the source text by the source file name, line
and column numbers:

<source lang="C">
struct mu_locus_point
{
char const *mu_file; /* Name of the source file */
unsigned mu_line; /* Line number */
unsigned mu_col; /* Column number */
};
</source>

Both line and column numbers start at <tt>1</tt>. The value of
<tt>0</tt> means ''information not available''.

The <tt>mu_file</tt> member merits special attention. In practice,
when writing a lexer, locations are assigned to each token extracted
from the source, so that all tokens returned when processing a given
file will have the same <tt>mu_file</tt> value. Obviously, it would
be a waste of memory to keep a newly allocated copy of the same string
in each <tt>mu_locus_point</tt>. Therefore a special interface is
provided for storing such identifiers:

<source lang="C">
int mu_locus_point_set_file (struct mu_locus_point *pt, const char *filename);
</source>

The <tt>filename</tt> argument is not directly stored in the structure
and can be safely disposed of after successful return. It is
guaranteed that any two points that's been assigned the ''filename''
arguments equal in the sense of <tt>strcmp</tt>, will have the same
pointer stored in their <tt>mu_file</tt> member. This means that,
given two <tt>mu_locus_point</tt> structures <tt>a</tt> and
<tt>b</tt>, the following check suffices to ensure they both refer to
the same source file:

<source lang="C">
if (a.mu_file == b.mu_file) ...
</source>

The similar function

<source lang="C">
int mu_locus_point_init (struct mu_locus_point *pt, const char *filename);
</source>

calls ''mu_locus_point_set_file'', and sets <tt>mu_line</tt> and
<tt>mu_col</tt> members to 0. It provides a way of dynamically
initializing the structure. A point can also be initialized
statically, like that:

<source lang="C">
struct mu_locus_point pt = MU_LOCUS_POINT_INITIALIZER;
</source>

This initializes all members to 0, which is treated by all diagnostic
functions as ''lack of location information''.

Both <tt>mu_locus_point_set_file</tt> and <tt>mu_locus_point_init</tt>
return 0 on success, and a non-zero error description on error<ref>
Possible error codes are:

; ENOMEM
: Not enough memory to allocate the resource.
; MU_ERR_OUT_PTR_NULL
: ''refname'' argument is NULL.
; MU_ERR_BUFSPACE
: Symbol table is full.
</ref>.

To deallocate a point when it is no longer needed, use

<source lang="C">
void mu_locus_point_deinit (struct mu_locus_point *pt);
</source>

Internally, a reference counter is kept for each value of
<tt>mu_file</tt> used. It is guaranteed that the memory allocated
for the identifier will be freed when <tt>mu_locus_point_deinit</tt>
has been called exactly so many times as
<tt>mu_locus_point_set_file</tt> with the same ''filename'' previously
(including any implicit calls from <tt>mu_locus_point_init</tt>).

To copy information between two points use the following function:

<source lang="C">
int mu_locus_point_copy (struct mu_locus_point *dest, struct mu_locus_point const *src);
</source>

It takes care to call <tt>mu_locus_deinit</tt> on ''dest'', prior to
copying data. The return codes are the same as described above.

The following structure indicates a source range:

<source lang="C">
struct mu_locus_range
{
struct mu_locus_point beg;
struct mu_locus_point end;
};
</source>

and is preferred for more exact diagnostics. The structure can be
initialized statically as follows:

<source lang="C">
struct mu_locus_range lr = MU_LOCUS_RANGE_INITIALIZER;
</source>

For dynamic initialization, <tt>mu_locus_point_init</tt> should be
called on its <tt>beg</tt> and <tt>end</tt> members.

To copy one range to another, the following function is provided:

<source lang="C">
int mu_locus_range_copy (struct mu_locus_range *dest, struct mu_locus_range const *src);
</source>

A range is deallocated with the following function:

<source lang="C">
void mu_locus_range_deinit (struct mu_locus_range *lr);
</source>

== Formatting ==

Several functions are provided for formatting locations for the
output.

;<source lang="C">void mu_stream_print_locus_point (mu_stream_t stream, struct mu_locus_point const *lpt);</source>
:Formats a point to the output stream. The formatting rules are as follows:
:# If all three members are not zero, the output format is '''FILE''':'''LINE'''.'''COL''', e.g.
:#: <tt>filter.siv:160.15</tt>
:# If <tt>mu_col</tt> is 0, the format is '''FILE''':'''LINE''', as in:
:#: <tt>filter.siv:160</tt>
:# If only <tt>mu_file</tt> is set, it is printed.
:# Finally, if all members are 0, nothing is output.
:Notice that in any case no delimiters are output after the formatted point.

;<source lang="C">void mu_stream_print_locus_range (mu_stream_t stream, struct mu_locus_range const *loc);</source>
:Prints a locus range. The rules for printing ranges are:
:
:# The <tt>beg</tt> member is formatted as described above.
:# If the <tt>end</tt> member is initialized to nulls, it is omitted.
:# Otherwise, a dash is printed and the <tt>end</tt> member is formatted as follows:
:## If its <tt>mu_file</tt> differs from that of <tt>beg</tt>, the point is printed following the same set of rules as above.
:## Otherwise, if the <tt>mu_line</tt> differs, it is printed followed by the <tt>mu_col</tt>, unless it is zero.
:## Otherwise, only the <tt>mu_col</tt> is printed (unless it is 0).
:
:This gives the following possible outputs:
:
:; <tt>filter.sv:160.15-include.sv:2-10</tt>
:: Range spans two source files (e.g. an include statement)
:; <tt>filter.sv:160.15-162.10</tt>
:: Range occupies several lines in the same source file.
:; <tt>filter.sv:160.15-30</tt>
:: Range spans several columns on the same line.
:; <tt>filter.sv:160-180</tt>
:: Range spans several lines (no column information available).
:; <tt>filter.sv:160</tt>
:: Single line in file (no column information available).
:; <tt>filter.sv</tt>
:: Only source name information available.

The following functions are available for formatting complex
diagnostic messages:

;<source lang="C">void mu_stream_vlprintf (mu_stream_t stream, struct mu_locus_range const *loc, char const *fmt, va_list ap);</source>
;<source lang="C">void mu_stream_lprintf (mu_stream_t stream, struct mu_locus_range const *loc, char const *fmt, ...);</source>
:These two functions output locus range ''loc'', followed by a column and a space, then format their arguments according to printf-style format <tt>fmt</tt>.
;<source lang="C">void mu_lrange_debug (struct mu_locus_range const *loc, char const *fmt, ...);</source>
:Does the same using <tt>mu_strerr</tt> as output stream.

==Notes==
<references/>

@@ Line 288: / Line 288: @@
 <source lang="C">
-   struct mu_locus_range range;
+   struct mu_locus_range range = MU_LOCUS_RANGE_INITIALIZER;
    int rc = mu_stream_ioctl (mu_strerr, MU_IOCTL_LOGSTREAM, MU_IOCTL_LOGSTREAM_GET_LOCUS_RANGE, &range);
    if (rc == 0)
@@ Line 316: / Line 316: @@
    struct mu_locus_range range = MU_LOCUS_RANGE_INITIALIZER;
-   mu_locus_point_init (&range.beg, "file.in");
+   mu_locus_point_set_file (&range.beg, "file.in");
    range.beg.mu_line = 1;
    range.beg.mu_col = 10;
@@ Line 322: / Line 322: @@
    mu_locus_range_deinit (&range);
 </source>
-−
 ==Line Tracker==

@@ Line 31: / Line 31: @@
    /* Dynamic initialization */
    struct mu_locus_point pt;
    mu_locus_point_init (&pt);
 </source>

← Older revision		Revision as of 14:55, 15 June 2017
Line 1:		Line 1:
−	The source location API is designed to keep track of locations in	+	The source location API is designed to keep track of locations in source files for diagnostic purposes. It is especially useful
−	source files for ~~the~~ diagnostic purposes. It is especially useful
	in parsers and lexical analyzers.		in parsers and lexical analyzers.

@@ Line 326: / Line 326: @@
 ==Line Tracker==
-Line tracker is an auxiliary facility for updating current location
+Line tracker is an auxiliary facility for updating current location during lexical analysis phase.  It is represented by the <tt>mu_linetrack_t</tt> data type.  The tracker is created using the
 <tt>mu_linetrack_create</tt> function:
 ;<source lang="C">int mu_linetrack_create (mu_linetrack_t *ret, char const *file_name, size_t max_lines);</source>
@@ Line 360: / Line 358: @@
 int mu_linetrack_locus (struct mu_linetrack *trk, struct mu_locus_point *lp);
 </source>
 ==Notes==
 <references/>

@@ Line 203: / Line 203: @@
 As an example, the following function increments the beginning line
-number of the range associated with the standard error stream:
+number of the range associated with the standard error stream<ref>This operation can be done using the <tt>MU_IOCTL_LOGSTREAM_ADVANCE_LOCUS_LINE</tt> opcode</ref>:
 <source style="C" line="1">
@@ Line 223: / Line 223: @@
+}
 </source>
 ==Notes==
 <references/>

@@ Line 19: / Line 19: @@
 </source>
-Both line and column numbers start at <tt>1</tt>.  The value of
+Prior to use any other functions discussed in this article, the <tt>mu_locus_point</tt> structure must be ''initialized''.  There are two ways of doing so:
 The <tt>mu_file</tt> member merits special attention.  In practice,
 when writing a lexer, locations are assigned to each token extracted
@@ Line 47: / Line 64: @@
 </source>
-The similar function
+The <tt>mu_locus_point_set_file</tt> function returns 0 on success, and a non-zero error description on error<ref>
 Possible error codes are:
@@ Line 87: / Line 85: @@
 for the identifier will be freed when <tt>mu_locus_point_deinit</tt>
 has been called exactly so many times as
-<tt>mu_locus_point_set_file</tt> with the same ''filename'' previously
+<tt>mu_locus_point_set_file</tt> with the same ''filename'' previously.
 To copy information between two points use the following function:
@@ Line 116: / Line 113: @@
 </source>
-For dynamic initialization, <tt>mu_locus_point_init</tt> should be
+or dynamically, as in
-called on its <tt>beg</tt> and <tt>end</tt> members.
 To copy one range to another, the following function is provided:

@@ Line 1: / Line 1: @@
 The source location API is designed to keep track of locations in
 source files for the diagnostic purposes.  It is especially useful
 in parsers and lexical analyzers.
 == Data Structures ==

@@ Line 178: / Line 178: @@
 ;<source lang="C">void mu_lrange_debug (struct mu_locus_range const *loc, char const *fmt, ...);</source>
 :Does the same using <tt>mu_strerr</tt> as output stream.
 ==Notes==
 <references/>