From 936c88d178d432aecafc40c53598249249991b35 Mon Sep 17 00:00:00 2001 From: Akim Demaille Date: Sat, 31 Mar 2012 09:46:12 +0200 Subject: [PATCH 1/2] doc: c++: complete the location documentation. * data/location.cc (position::initialize, location::initialize): Also accept line and column, with default values. * doc/bison.texinfo (C++ position, C++ location): New nodes. Describe more thoroughly these classes. Fix several Texinfo misuses. --- NEWS | 6 ++++ data/location.cc | 14 +++++--- doc/bison.texinfo | 102 +++++++++++++++++++++++++++++++++++++++++------------ 3 files changed, 95 insertions(+), 27 deletions(-) diff --git a/NEWS b/NEWS index d972d85..f552c32 100644 --- a/NEWS +++ b/NEWS @@ -34,6 +34,12 @@ Bison News C and C++ parsers use nullptr instead of 0 when __cplusplus is 201103L or higher. +** C++ locations: + + The position and location constructors (and their initialize + methods) accept new arguments for line and column. Several issues + in the documentation were fixed. + * Changes in version 2.5 (2011-05-14): ** Grammar symbol names can now contain non-initial dashes: diff --git a/data/location.cc b/data/location.cc index da70d9d..624c3c1 100644 --- a/data/location.cc +++ b/data/location.cc @@ -54,11 +54,13 @@ b4_copyright([Positions for Bison parsers in C++], ]])[ /// Initialization. - void initialize (]b4_percent_define_get([[filename_type]])[* fn = YY_NULL) + void initialize (]b4_percent_define_get([[filename_type]])[* fn = YY_NULL, + unsigned int l = ]b4_location_initial_line[u, + unsigned int c = ]b4_location_initial_column[u) { filename = fn; - line = ]b4_location_initial_line[u; - column = ]b4_location_initial_column[u; + line = l; + column = c; } /** \name Line and Column related manipulators @@ -195,9 +197,11 @@ b4_copyright([Locations for Bison parsers in C++], ])[ /// Initialization. - void initialize (]b4_percent_define_get([[filename_type]])[* fn = YY_NULL) + void initialize (]b4_percent_define_get([[filename_type]])[* f = YY_NULL, + unsigned int l = ]b4_location_initial_line[u, + unsigned int c = ]b4_location_initial_column[u) { - begin.initialize (fn); + begin.initialize (f, l, c); end = begin; } diff --git a/doc/bison.texinfo b/doc/bison.texinfo index 97cd961..76a7dba 100644 --- a/doc/bison.texinfo +++ b/doc/bison.texinfo @@ -316,6 +316,11 @@ C++ Parsers * C++ Scanner Interface:: Exchanges between yylex and parse * A Complete C++ Example:: Demonstrating their use +C++ Location Values + +* C++ position:: One point in the source file +* C++ location:: Two points in the source file + A Complete C++ Example * Calc++ --- C++ Calculator:: The specifications @@ -8882,55 +8887,98 @@ define a @code{position}, a single point in a file, and a @code{location}, a range composed of a pair of @code{position}s (possibly spanning several files). -@deftypemethod {position} {std::string*} file +@tindex uint +In this section @code{uint} is an abbreviation for @code{unsigned int}: in +genuine code only the latter is used. + +@menu +* C++ position:: One point in the source file +* C++ location:: Two points in the source file +@end menu + +@node C++ position +@subsubsection C++ @code{position} + +@deftypeop {Constructor} {position} {} position (std::string* @var{file} = 0, uint @var{line} = 1, uint @var{col} = 1) +Create a @code{position} denoting a given point. Note that @code{file} is +not reclaimed when the @code{position} is destroyed: memory managed must be +handled elsewhere. +@end deftypeop + +@deftypemethod {position} {void} initialize (std::string* @var{file} = 0, uint @var{line} = 1, uint @var{col} = 1) +Reset the position to the given values. +@end deftypemethod + +@deftypeivar {position} {std::string*} file The name of the file. It will always be handled as a pointer, the parser will never duplicate nor deallocate it. As an experimental feature you may change it to @samp{@var{type}*} using @samp{%define filename_type "@var{type}"}. -@end deftypemethod +@end deftypeivar -@deftypemethod {position} {unsigned int} line +@deftypeivar {position} {uint} line The line, starting at 1. -@end deftypemethod +@end deftypeivar -@deftypemethod {position} {unsigned int} lines (int @var{height} = 1) +@deftypemethod {position} {uint} lines (int @var{height} = 1) Advance by @var{height} lines, resetting the column number. @end deftypemethod -@deftypemethod {position} {unsigned int} column -The column, starting at 0. -@end deftypemethod +@deftypeivar {position} {uint} column +The column, starting at 1. +@end deftypeivar -@deftypemethod {position} {unsigned int} columns (int @var{width} = 1) +@deftypemethod {position} {uint} columns (int @var{width} = 1) Advance by @var{width} columns, without changing the line number. @end deftypemethod -@deftypemethod {position} {position&} operator+= (position& @var{pos}, int @var{width}) -@deftypemethodx {position} {position} operator+ (const position& @var{pos}, int @var{width}) -@deftypemethodx {position} {position&} operator-= (const position& @var{pos}, int @var{width}) -@deftypemethodx {position} {position} operator- (position& @var{pos}, int @var{width}) +@deftypemethod {position} {position&} operator+= (int @var{width}) +@deftypemethodx {position} {position} operator+ (int @var{width}) +@deftypemethodx {position} {position&} operator-= (int @var{width}) +@deftypemethodx {position} {position} operator- (int @var{width}) Various forms of syntactic sugar for @code{columns}. @end deftypemethod -@deftypemethod {position} {position} operator<< (std::ostream @var{o}, const position& @var{p}) +@deftypemethod {position} {bool} operator== (const position& @var{that}) +@deftypemethodx {position} {bool} operator!= (const position& @var{that}) +Whether @code{*this} and @code{that} denote equal/different positions. +@end deftypemethod + +@deftypefun {std::ostream&} operator<< (std::ostream& @var{o}, const position& @var{p}) Report @var{p} on @var{o} like this: @samp{@var{file}:@var{line}.@var{column}}, or @samp{@var{line}.@var{column}} if @var{file} is null. +@end deftypefun + +@node C++ location +@subsubsection C++ @code{location} + +@deftypeop {Constructor} {location} {} location (const position& @var{begin}, const position& @var{end}) +Create a @code{Location} from the endpoints of the range. +@end deftypeop + +@deftypeop {Constructor} {location} {} location (const position& @var{pos} = position()) +@deftypeopx {Constructor} {location} {} location (std::string* @var{file}, uint @var{line}, uint @var{col}) +Create a @code{Location} denoting an empty range located at a given point. +@end deftypeop + +@deftypemethod {location} {void} initialize (std::string* @var{file} = 0, uint @var{line} = 1, uint @var{col} = 1) +Reset the location to an empty range at the given values. @end deftypemethod -@deftypemethod {location} {position} begin -@deftypemethodx {location} {position} end +@deftypeivar {location} {position} begin +@deftypeivarx {location} {position} end The first, inclusive, position of the range, and the first beyond. -@end deftypemethod +@end deftypeivar -@deftypemethod {location} {unsigned int} columns (int @var{width} = 1) -@deftypemethodx {location} {unsigned int} lines (int @var{height} = 1) +@deftypemethod {location} {uint} columns (int @var{width} = 1) +@deftypemethodx {location} {uint} lines (int @var{height} = 1) Advance the @code{end} position. @end deftypemethod -@deftypemethod {location} {location} operator+ (const location& @var{begin}, const location& @var{end}) -@deftypemethodx {location} {location} operator+ (const location& @var{begin}, int @var{width}) -@deftypemethodx {location} {location} operator+= (const location& @var{loc}, int @var{width}) +@deftypemethod {location} {location} operator+ (const location& @var{end}) +@deftypemethodx {location} {location} operator+ (int @var{width}) +@deftypemethodx {location} {location} operator+= (int @var{width}) Various forms of syntactic sugar. @end deftypemethod @@ -8938,6 +8986,16 @@ Various forms of syntactic sugar. Move @code{begin} onto @code{end}. @end deftypemethod +@deftypemethod {location} {bool} operator== (const location& @var{that}) +@deftypemethodx {location} {bool} operator!= (const location& @var{that}) +Whether @code{*this} and @code{that} denote equal/different ranges of +positions. +@end deftypemethod + +@deftypefun {std::ostream&} operator<< (std::ostream& @var{o}, const location& @var{p}) +Report @var{p} on @var{o}, taking care of special cases such as: no +@code{filename} defined, or equal filename/line or column. +@end deftypefun @node C++ Parser Interface @subsection C++ Parser Interface -- 1.7.9.4