1 /* Map (unsigned int) keys to (source file, line, column) triples.
2 Copyright (C) 2001-2020 Free Software Foundation, Inc.
4 This program is free software; you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by the
6 Free Software Foundation; either version 3, or (at your option) any
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
14 You should have received a copy of the GNU General Public License
15 along with this program; see the file COPYING3. If not see
16 <http://www.gnu.org/licenses/>.
18 In other words, you are welcome to use, share and improve this program.
19 You are forbidden to forbid anyone else to use, share and improve
20 what you give them. Help stamp out software-hoarding! */
22 #ifndef LIBCPP_LINE_MAP_H
23 #define LIBCPP_LINE_MAP_H
26 #define GTY(x) /* nothing */
29 /* Both gcc and emacs number source *lines* starting at 1, but
30 they have differing conventions for *columns*.
32 GCC uses a 1-based convention for source columns,
33 whereas Emacs's M-x column-number-mode uses a 0-based convention.
35 For example, an error in the initial, left-hand
36 column of source line 3 is reported by GCC as:
38 some-file.c:3:1: error: ...etc...
40 On navigating to the location of that error in Emacs
41 (e.g. via "next-error"),
42 the locus is reported in the Mode Line
43 (assuming M-x column-number-mode) as:
45 some-file.c 10% (3, 0)
47 i.e. "3:1:" in GCC corresponds to "(3, 0)" in Emacs. */
49 /* The type of line numbers. */
50 typedef unsigned int linenum_type
;
52 /* A type for doing arithmetic on line numbers. */
53 typedef long long linenum_arith_t
;
55 /* A function for for use by qsort for comparing line numbers. */
57 inline int compare (linenum_type lhs
, linenum_type rhs
)
59 /* Avoid truncation issues by using linenum_arith_t for the comparison,
60 and only consider the sign of the result. */
61 linenum_arith_t diff
= (linenum_arith_t
)lhs
- (linenum_arith_t
)rhs
;
63 return diff
> 0 ? 1 : -1;
67 /* Reason for creating a new line map with linemap_add. */
70 LC_ENTER
= 0, /* Begin #include. */
71 LC_LEAVE
, /* Return to including file. */
72 LC_RENAME
, /* Other reason for name change. */
73 LC_RENAME_VERBATIM
, /* Likewise, but "" != stdin. */
74 LC_ENTER_MACRO
, /* Begin macro expansion. */
75 LC_MODULE
, /* A (C++) Module. */
76 /* FIXME: add support for stringize and paste. */
77 LC_HWM
/* High Water Mark. */
80 /* The typedef "location_t" is a key within the location database,
81 identifying a source location or macro expansion, along with range
82 information, and (optionally) a pointer for use by gcc.
84 This key only has meaning in relation to a line_maps instance. Within
85 gcc there is a single line_maps instance: "line_table", declared in
86 gcc/input.h and defined in gcc/input.c.
88 The values of the keys are intended to be internal to libcpp,
89 but for ease-of-understanding the implementation, they are currently
92 Actual | Value | Meaning
93 -----------+-------------------------------+-------------------------------
94 0x00000000 | UNKNOWN_LOCATION (gcc/input.h)| Unknown/invalid location.
95 -----------+-------------------------------+-------------------------------
96 0x00000001 | BUILTINS_LOCATION | The location for declarations
97 | (gcc/input.h) | in "<built-in>"
98 -----------+-------------------------------+-------------------------------
99 0x00000002 | RESERVED_LOCATION_COUNT | The first location to be
100 | (also | handed out, and the
101 | ordmap[0]->start_location) | first line in ordmap 0
102 -----------+-------------------------------+-------------------------------
103 | ordmap[1]->start_location | First line in ordmap 1
104 | ordmap[1]->start_location+32 | First column in that line
105 | (assuming range_bits == 5) |
106 | ordmap[1]->start_location+64 | 2nd column in that line
107 | ordmap[1]->start_location+4096| Second line in ordmap 1
108 | (assuming column_bits == 12)
110 | Subsequent lines are offset by (1 << column_bits),
111 | e.g. 4096 for 12 bits, with a column value of 0 representing
114 | Within a line, the low "range_bits" (typically 5) are used for
115 | storing short ranges, so that there's an offset of
116 | (1 << range_bits) between individual columns within a line,
118 | The low range_bits store the offset of the end point from the
119 | start point, and the start point is found by masking away
123 | ordmap[1]->start_location+64 "2nd column in that line"
124 | above means a caret at that location, with a range
125 | starting and finishing at the same place (the range bits
126 | are 0), a range of length 1.
129 | ordmap[1]->start_location+68
130 | has range bits 0x4, meaning a caret with a range starting at
131 | that location, but with endpoint 4 columns further on: a range
134 | Ranges that have caret != start, or have an endpoint too
135 | far away to fit in range_bits are instead stored as ad-hoc
136 | locations. Hence for range_bits == 5 we can compactly store
137 | tokens of length <= 32 without needing to use the ad-hoc
140 | This packing scheme means we effectively have
141 | (column_bits - range_bits)
142 | of bits for the columns, typically (12 - 5) = 7, for 128
143 | columns; longer line widths are accomodated by starting a
144 | new ordmap with a higher column_bits.
146 | ordmap[2]->start_location-1 | Final location in ordmap 1
147 -----------+-------------------------------+-------------------------------
148 | ordmap[2]->start_location | First line in ordmap 2
149 | ordmap[3]->start_location-1 | Final location in ordmap 2
150 -----------+-------------------------------+-------------------------------
152 -----------+-------------------------------+-------------------------------
153 | ordmap[n-1]->start_location | First line in final ord map
155 | set->highest_location - 1 | Final location in that ordmap
156 -----------+-------------------------------+-------------------------------
157 | set->highest_location | Location of the where the next
158 | | ordinary linemap would start
159 -----------+-------------------------------+-------------------------------
161 | VVVVVVVVVVVVVVVVVVVVVVVVVVV
162 | Ordinary maps grow this way
164 | (unallocated integers)
166 0x60000000 | LINE_MAP_MAX_LOCATION_WITH_COLS
167 | Beyond this point, ordinary linemaps have 0 bits per column:
168 | each increment of the value corresponds to a new source line.
170 0x70000000 | LINE_MAP_MAX_LOCATION
171 | Beyond the point, we give up on ordinary maps; attempts to
172 | create locations in them lead to UNKNOWN_LOCATION (0).
174 | (unallocated integers)
176 | Macro maps grow this way
177 | ^^^^^^^^^^^^^^^^^^^^^^^^
179 -----------+-------------------------------+-------------------------------
180 | LINEMAPS_MACRO_LOWEST_LOCATION| Locations within macro maps
181 | macromap[m-1]->start_location | Start of last macro map
183 -----------+-------------------------------+-------------------------------
184 | macromap[m-2]->start_location | Start of penultimate macro map
185 -----------+-------------------------------+-------------------------------
186 | macromap[1]->start_location | Start of macro map 1
187 -----------+-------------------------------+-------------------------------
188 | macromap[0]->start_location | Start of macro map 0
189 0x7fffffff | MAX_LOCATION_T | Also used as a mask for
190 | | accessing the ad-hoc data table
191 -----------+-------------------------------+-------------------------------
192 0x80000000 | Start of ad-hoc values; the lower 31 bits are used as an index
193 ... | into the line_table->location_adhoc_data_map.data array.
194 0xffffffff | UINT_MAX |
195 -----------+-------------------------------+-------------------------------
197 Examples of location encoding.
202 Consider encoding the location of a token "foo", seen underlined here
203 on line 523, within an ordinary line_map that starts at line 500:
208 523 return foo + bar;
212 The location's caret and start are both at line 523, column 11; the
213 location's finish is on the same line, at column 13 (an offset of 2
214 columns, for length 3).
216 Line 523 is offset 23 from the starting line of the ordinary line_map.
218 caret == start, and the offset of the finish fits within 5 bits, so
219 this can be stored as a packed range.
223 + (line_offset << ordmap->m_column_and_range_bits)
224 + (column << ordmap->m_range_bits)
226 i.e. (for line offset 23, column 11, range offset 2):
232 ordmap->start + 0x17162
233 assuming that the line_map uses the default of 7 bits for columns and
234 5 bits for packed range (giving 12 bits for m_column_and_range_bits).
240 These are a special case of the above, where
241 caret == start == finish
242 They are stored as packed ranges with offset == 0.
243 For example, the location of the "f" of "foo" could be stored
244 as above, but with range offset 0, giving:
250 ordmap->start + 0x17160
256 Consider encoding the location of the binary expression
262 523 return foo + bar;
266 The location's caret is at the "+", line 523 column 15, but starts
267 earlier, at the "f" of "foo" at column 11. The finish is at the "r"
268 of "bar" at column 19.
270 This can't be stored as a packed range since start != caret.
271 Hence it is stored as an ad-hoc location e.g. 0x80000003.
273 Stripping off the top bit gives us an index into the ad-hoc
276 line_table->location_adhoc_data_map.data[0x3]
278 from which the caret, start and finish can be looked up,
279 encoded as "pure" locations:
281 start == ordmap->start + (23 << 12) + (11 << 5)
282 == ordmap->start + 0x17160 (as above; the "f" of "foo")
284 caret == ordmap->start + (23 << 12) + (15 << 5)
285 == ordmap->start + 0x171e0
287 finish == ordmap->start + (23 << 12) + (19 << 5)
288 == ordmap->start + 0x17260
290 To further see how location_t works in practice, see the
291 worked example in libcpp/location-example.txt. */
292 typedef unsigned int location_t
;
294 /* Do not track column numbers higher than this one. As a result, the
295 range of column_bits is [12, 18] (or 0 if column numbers are
297 const unsigned int LINE_MAP_MAX_COLUMN_NUMBER
= (1U << 12);
299 /* Do not pack ranges if locations get higher than this.
300 If you change this, update:
301 gcc.dg/plugin/location-overflow-test-*.c. */
302 const location_t LINE_MAP_MAX_LOCATION_WITH_PACKED_RANGES
= 0x50000000;
304 /* Do not track column numbers if locations get higher than this.
305 If you change this, update:
306 gcc.dg/plugin/location-overflow-test-*.c. */
307 const location_t LINE_MAP_MAX_LOCATION_WITH_COLS
= 0x60000000;
309 /* Highest possible source location encoded within an ordinary map. */
310 const location_t LINE_MAP_MAX_LOCATION
= 0x70000000;
312 /* A range of source locations.
315 m_start is the first location within the range,
316 m_finish is the last location within the range.
318 We may need a more compact way to store these, but for now,
319 let's do it the simple way, as a pair. */
320 struct GTY(()) source_range
325 /* We avoid using constructors, since various structs that
326 don't yet have constructors will embed instances of
329 /* Make a source_range from a location_t. */
330 static source_range
from_location (location_t loc
)
333 result
.m_start
= loc
;
334 result
.m_finish
= loc
;
338 /* Make a source_range from a pair of location_t. */
339 static source_range
from_locations (location_t start
,
343 result
.m_start
= start
;
344 result
.m_finish
= finish
;
349 /* Memory allocation function typedef. Works like xrealloc. */
350 typedef void *(*line_map_realloc
) (void *, size_t);
352 /* Memory allocator function that returns the actual allocated size,
353 for a given requested allocation. */
354 typedef size_t (*line_map_round_alloc_size_func
) (size_t);
356 /* A line_map encodes a sequence of locations.
357 There are two kinds of maps. Ordinary maps and macro expansion
358 maps, a.k.a macro maps.
360 A macro map encodes source locations of tokens that are part of a
361 macro replacement-list, at a macro expansion point. E.g, in:
363 #define PLUS(A,B) A + B
365 No macro map is going to be created there, because we are not at a
366 macro expansion point. We are at a macro /definition/ point. So the
367 locations of the tokens of the macro replacement-list (i.e, A + B)
368 will be locations in an ordinary map, not a macro map.
370 On the other hand, if we later do:
374 The invocation of PLUS here is a macro expansion. So we are at a
375 macro expansion point. The preprocessor expands PLUS (1,2) and
376 replaces it with the tokens of its replacement-list: 1 + 2. A macro
377 map is going to be created to hold (or rather to map, haha ...) the
378 locations of the tokens 1, + and 2. The macro map also records the
379 location of the expansion point of PLUS. That location is mapped in
380 the map that is active right before the location of the invocation
383 /* This contains GTY mark-up to support precompiled headers.
384 line_map is an abstract class, only derived objects exist. */
385 struct GTY((tag ("0"), desc ("MAP_ORDINARY_P (&%h) ? 1 : 2"))) line_map
{
386 location_t start_location
;
388 /* Size and alignment is (usually) 4 bytes. */
391 /* An ordinary line map encodes physical source locations. Those
392 physical source locations are called "spelling locations".
394 Physical source file TO_FILE at line TO_LINE at column 0 is represented
395 by the logical START_LOCATION. TO_LINE+L at column C is represented by
396 START_LOCATION+(L*(1<<m_column_and_range_bits))+(C*1<<m_range_bits), as
397 long as C<(1<<effective range bits), and the result_location is less than
398 the next line_map's start_location.
399 (The top line is line 1 and the leftmost column is column 1; line/column 0
400 means "entire file/line" or "unknown line/column" or "not applicable".)
402 The highest possible source location is MAX_LOCATION_T. */
403 struct GTY((tag ("1"))) line_map_ordinary
: public line_map
{
404 /* Base class is 4 bytes. */
406 /* 4 bytes of integers, each 1 byte for easy extraction/insertion. */
408 /* The reason for creation of this line map. */
409 ENUM_BITFIELD (lc_reason
) reason
: 8;
411 /* SYSP is one for a system header, two for a C system header file
412 that therefore needs to be extern "C" protected in C++, and zero
413 otherwise. This field isn't really needed now that it's in
417 /* Number of the low-order location_t bits used for column numbers
419 unsigned int m_column_and_range_bits
: 8;
421 /* Number of the low-order "column" bits used for storing short ranges
422 inline, rather than in the ad-hoc table.
425 +-------------------------+-------------------------------------------+
426 | |<---map->column_and_range_bits (e.g. 12)-->|
427 +-------------------------+-----------------------+-------------------+
428 | | column_and_range_bits | map->range_bits |
430 +-------------------------+-----------------------+-------------------+
431 | row bits | effective column bits | short range bits |
432 | | (e.g. 7) | (e.g. 5) |
433 +-------------------------+-----------------------+-------------------+ */
434 unsigned int m_range_bits
: 8;
436 /* Pointer alignment boundary on both 32 and 64-bit systems. */
439 linenum_type to_line
;
441 /* Location from whence this line map was included. For regular
442 #includes, this location will be the last location of a map. For
443 outermost file, this is 0. For modules it could be anywhere
445 location_t included_from
;
447 /* Size is 20 or 24 bytes, no padding */
450 /* This is the highest possible source location encoded within an
451 ordinary or macro map. */
452 const location_t MAX_LOCATION_T
= 0x7FFFFFFF;
456 /* A macro line map encodes location of tokens coming from a macro
459 The offset from START_LOCATION is used to index into
460 MACRO_LOCATIONS; this holds the original location of the token. */
461 struct GTY((tag ("2"))) line_map_macro
: public line_map
{
462 /* Base is 4 bytes. */
464 /* The number of tokens inside the replacement-list of MACRO. */
465 unsigned int n_tokens
;
467 /* Pointer alignment boundary. */
469 /* The cpp macro whose expansion gave birth to this macro map. */
470 struct cpp_hashnode
*
471 GTY ((nested_ptr (union tree_node
,
472 "%h ? CPP_HASHNODE (GCC_IDENT_TO_HT_IDENT (%h)) : NULL",
473 "%h ? HT_IDENT_TO_GCC_IDENT (HT_NODE (%h)) : NULL")))
476 /* This array of location is actually an array of pairs of
477 locations. The elements inside it thus look like:
479 x0,y0, x1,y1, x2,y2, ...., xn,yn.
483 Remember that these xI,yI are collected when libcpp is about to
484 expand a given macro.
486 yI is the location in the macro definition, either of the token
487 itself or of a macro parameter that it replaces.
491 #define PLUS(A, B) A + B <--- #1
493 int a = PLUS (1,2); <--- #2
495 There is a macro map for the expansion of PLUS in #2. PLUS is
496 expanded into its expansion-list. The expansion-list is the
497 replacement-list of PLUS where the macro parameters are replaced
498 with their arguments. So the replacement-list of PLUS is made of
503 and the expansion-list is made of the tokens:
507 Let's consider the case of token "+". Its y1 [yI for I == 1] is
508 its spelling location in #1.
510 y0 (thus for token "1") is the spelling location of A in #1.
512 And y2 (of token "2") is the spelling location of B in #1.
514 When the token is /not/ an argument for a macro, xI is the same
515 location as yI. Otherwise, xI is the location of the token
516 outside this macro expansion. If this macro was expanded from
517 another macro expansion, xI is a virtual location representing
518 the token in that macro expansion; otherwise, it is the spelling
519 location of the token.
521 Note that a virtual location is a location returned by
522 linemap_add_macro_token. It encodes the relevant locations (x,y
523 pairs) of that token across the macro expansions from which it
524 (the token) might come from.
526 In the example above x1 (for token "+") is going to be the same
527 as y1. x0 is the spelling location for the argument token "1",
528 and x2 is the spelling location for the argument token "2". */
529 location_t
* GTY((atomic
)) macro_locations
;
531 /* This is the location of the expansion point of the current macro
532 map. It's the location of the macro name. That location is held
533 by the map that was current right before the current one. It
534 could have been either a macro or an ordinary map, depending on
535 if we are in a nested expansion context not. */
536 location_t expansion
;
538 /* Size is 20 or 32 (4 bytes padding on 64-bit). */
541 #if CHECKING_P && (GCC_VERSION >= 2007)
543 /* Assertion macro to be used in line-map code. */
544 #define linemap_assert(EXPR) \
550 /* Assert that becomes a conditional expression when checking is disabled at
551 compilation time. Use this for conditions that should not happen but if
552 they happen, it is better to handle them gracefully rather than crash
556 if (linemap_assert_fails(EXPR)) handle_error(); */
557 #define linemap_assert_fails(EXPR) __extension__ \
558 ({linemap_assert (EXPR); false;})
561 /* Include EXPR, so that unused variable warnings do not occur. */
562 #define linemap_assert(EXPR) ((void)(0 && (EXPR)))
563 #define linemap_assert_fails(EXPR) (! (EXPR))
566 /* Get whether location LOC is an ad-hoc, ordinary or macro location. */
569 IS_ORDINARY_LOC (location_t loc
)
571 return loc
< LINE_MAP_MAX_LOCATION
;
575 IS_ADHOC_LOC (location_t loc
)
577 return loc
> MAX_LOCATION_T
;
581 IS_MACRO_LOC (location_t loc
)
583 return !IS_ORDINARY_LOC (loc
) && !IS_ADHOC_LOC (loc
);
586 /* Categorize line map kinds. */
589 MAP_ORDINARY_P (const line_map
*map
)
591 return IS_ORDINARY_LOC (map
->start_location
);
594 /* Return TRUE if MAP encodes locations coming from a macro
595 replacement-list at macro expansion point. */
597 linemap_macro_expansion_map_p (const line_map
*);
599 /* Assert that MAP encodes locations of tokens that are not part of
600 the replacement-list of a macro expansion, downcasting from
601 line_map * to line_map_ordinary *. */
603 inline line_map_ordinary
*
604 linemap_check_ordinary (line_map
*map
)
606 linemap_assert (MAP_ORDINARY_P (map
));
607 return (line_map_ordinary
*)map
;
610 /* Assert that MAP encodes locations of tokens that are not part of
611 the replacement-list of a macro expansion, downcasting from
612 const line_map * to const line_map_ordinary *. */
614 inline const line_map_ordinary
*
615 linemap_check_ordinary (const line_map
*map
)
617 linemap_assert (MAP_ORDINARY_P (map
));
618 return (const line_map_ordinary
*)map
;
621 /* Assert that MAP is a macro expansion and downcast to the appropriate
624 inline line_map_macro
*linemap_check_macro (line_map
*map
)
626 linemap_assert (!MAP_ORDINARY_P (map
));
627 return (line_map_macro
*)map
;
630 /* Assert that MAP is a macro expansion and downcast to the appropriate
633 inline const line_map_macro
*
634 linemap_check_macro (const line_map
*map
)
636 linemap_assert (!MAP_ORDINARY_P (map
));
637 return (const line_map_macro
*)map
;
640 /* Read the start location of MAP. */
643 MAP_START_LOCATION (const line_map
*map
)
645 return map
->start_location
;
648 /* Get the starting line number of ordinary map MAP. */
651 ORDINARY_MAP_STARTING_LINE_NUMBER (const line_map_ordinary
*ord_map
)
653 return ord_map
->to_line
;
656 /* Return a positive value if map encodes locations from a system
657 header, 0 otherwise. Returns 1 if ordinary map MAP encodes locations
658 in a system header and 2 if it encodes locations in a C system header
659 that therefore needs to be extern "C" protected in C++. */
662 ORDINARY_MAP_IN_SYSTEM_HEADER_P (const line_map_ordinary
*ord_map
)
664 return ord_map
->sysp
;
667 /* TRUE if this line map is for a module (not a source file). */
670 MAP_MODULE_P (const line_map
*map
)
672 return (MAP_ORDINARY_P (map
)
673 && linemap_check_ordinary (map
)->reason
== LC_MODULE
);
676 /* Get the filename of ordinary map MAP. */
679 ORDINARY_MAP_FILE_NAME (const line_map_ordinary
*ord_map
)
681 return ord_map
->to_file
;
684 /* Get the cpp macro whose expansion gave birth to macro map MAP. */
686 inline cpp_hashnode
*
687 MACRO_MAP_MACRO (const line_map_macro
*macro_map
)
689 return macro_map
->macro
;
692 /* Get the number of tokens inside the replacement-list of the macro
693 that led to macro map MAP. */
696 MACRO_MAP_NUM_MACRO_TOKENS (const line_map_macro
*macro_map
)
698 return macro_map
->n_tokens
;
701 /* Get the array of pairs of locations within macro map MAP.
702 See the declaration of line_map_macro for more information. */
705 MACRO_MAP_LOCATIONS (const line_map_macro
*macro_map
)
707 return macro_map
->macro_locations
;
710 /* Get the location of the expansion point of the macro map MAP. */
713 MACRO_MAP_EXPANSION_POINT_LOCATION (const line_map_macro
*macro_map
)
715 return macro_map
->expansion
;
718 /* The abstraction of a set of location maps. There can be several
719 types of location maps. This abstraction contains the attributes
720 that are independent from the type of the map.
722 Essentially this is just a vector of T_linemap_subclass,
723 which can only ever grow in size. */
725 struct GTY(()) maps_info_ordinary
{
726 /* This array contains the "ordinary" line maps, for all
727 events other than macro expansion
728 (e.g. when a new preprocessing unit starts or ends). */
729 line_map_ordinary
* GTY ((length ("%h.used"))) maps
;
731 /* The total number of allocated maps. */
732 unsigned int allocated
;
734 /* The number of elements used in maps. This number is smaller
735 or equal to ALLOCATED. */
738 mutable unsigned int cache
;
741 struct GTY(()) maps_info_macro
{
742 /* This array contains the macro line maps.
743 A macro line map is created whenever a macro expansion occurs. */
744 line_map_macro
* GTY ((length ("%h.used"))) maps
;
746 /* The total number of allocated maps. */
747 unsigned int allocated
;
749 /* The number of elements used in maps. This number is smaller
750 or equal to ALLOCATED. */
753 mutable unsigned int cache
;
756 /* Data structure to associate a source_range together with an arbitrary
757 data pointer with a source location. */
758 struct GTY(()) location_adhoc_data
{
760 source_range src_range
;
761 void * GTY((skip
)) data
;
766 /* The following data structure encodes a location with some adhoc data
767 and maps it to a new unsigned integer (called an adhoc location)
768 that replaces the original location to represent the mapping.
770 The new adhoc_loc uses the highest bit as the enabling bit, i.e. if the
771 highest bit is 1, then the number is adhoc_loc. Otherwise, it serves as
772 the original location. Once identified as the adhoc_loc, the lower 31
773 bits of the integer is used to index the location_adhoc_data array,
774 in which the locus and associated data is stored. */
776 struct GTY(()) location_adhoc_data_map
{
777 struct htab
* GTY((skip
)) htab
;
779 unsigned int allocated
;
780 struct location_adhoc_data
GTY((length ("%h.allocated"))) *data
;
783 /* A set of chronological line_map structures. */
784 class GTY(()) line_maps
{
789 maps_info_ordinary info_ordinary
;
791 maps_info_macro info_macro
;
793 /* Depth of the include stack, including the current file. */
796 /* If true, prints an include trace a la -H. */
799 /* Highest location_t "given out". */
800 location_t highest_location
;
802 /* Start of line of highest location_t "given out". */
803 location_t highest_line
;
805 /* The maximum column number we can quickly allocate. Higher numbers
806 may require allocating a new line_map. */
807 unsigned int max_column_hint
;
809 /* The allocator to use when resizing 'maps', defaults to xrealloc. */
810 line_map_realloc reallocator
;
812 /* The allocators' function used to know the actual size it
813 allocated, for a certain allocation size requested. */
814 line_map_round_alloc_size_func round_alloc_size
;
816 struct location_adhoc_data_map location_adhoc_data_map
;
818 /* The special location value that is used as spelling location for
820 location_t builtin_location
;
822 /* True if we've seen a #line or # 44 "file" directive. */
823 bool seen_line_directive
;
825 /* The default value of range_bits in ordinary line maps. */
826 unsigned int default_range_bits
;
828 unsigned int num_optimized_ranges
;
829 unsigned int num_unoptimized_ranges
;
832 /* Returns the number of allocated maps so far. MAP_KIND shall be TRUE
833 if we are interested in macro maps, FALSE otherwise. */
835 LINEMAPS_ALLOCATED (const line_maps
*set
, bool map_kind
)
838 return set
->info_macro
.allocated
;
840 return set
->info_ordinary
.allocated
;
843 /* As above, but by reference (e.g. as an lvalue). */
845 inline unsigned int &
846 LINEMAPS_ALLOCATED (line_maps
*set
, bool map_kind
)
849 return set
->info_macro
.allocated
;
851 return set
->info_ordinary
.allocated
;
854 /* Returns the number of used maps so far. MAP_KIND shall be TRUE if
855 we are interested in macro maps, FALSE otherwise.*/
857 LINEMAPS_USED (const line_maps
*set
, bool map_kind
)
860 return set
->info_macro
.used
;
862 return set
->info_ordinary
.used
;
865 /* As above, but by reference (e.g. as an lvalue). */
867 inline unsigned int &
868 LINEMAPS_USED (line_maps
*set
, bool map_kind
)
871 return set
->info_macro
.used
;
873 return set
->info_ordinary
.used
;
876 /* Returns the index of the last map that was looked up with
877 linemap_lookup. MAP_KIND shall be TRUE if we are interested in
878 macro maps, FALSE otherwise. */
879 inline unsigned int &
880 LINEMAPS_CACHE (const line_maps
*set
, bool map_kind
)
883 return set
->info_macro
.cache
;
885 return set
->info_ordinary
.cache
;
888 /* Return the map at a given index. */
890 LINEMAPS_MAP_AT (const line_maps
*set
, bool map_kind
, int index
)
893 return &set
->info_macro
.maps
[index
];
895 return &set
->info_ordinary
.maps
[index
];
898 /* Returns the last map used in the line table SET. MAP_KIND
899 shall be TRUE if we are interested in macro maps, FALSE
902 LINEMAPS_LAST_MAP (const line_maps
*set
, bool map_kind
)
904 return LINEMAPS_MAP_AT (set
, map_kind
,
905 LINEMAPS_USED (set
, map_kind
) - 1);
908 /* Returns the last map that was allocated in the line table SET.
909 MAP_KIND shall be TRUE if we are interested in macro maps, FALSE
912 LINEMAPS_LAST_ALLOCATED_MAP (const line_maps
*set
, bool map_kind
)
914 return LINEMAPS_MAP_AT (set
, map_kind
,
915 LINEMAPS_ALLOCATED (set
, map_kind
) - 1);
918 /* Returns a pointer to the memory region where ordinary maps are
919 allocated in the line table SET. */
920 inline line_map_ordinary
*
921 LINEMAPS_ORDINARY_MAPS (const line_maps
*set
)
923 return set
->info_ordinary
.maps
;
926 /* Returns the INDEXth ordinary map. */
927 inline line_map_ordinary
*
928 LINEMAPS_ORDINARY_MAP_AT (const line_maps
*set
, int index
)
930 linemap_assert (index
>= 0
931 && (unsigned int)index
< LINEMAPS_USED (set
, false));
932 return (line_map_ordinary
*)LINEMAPS_MAP_AT (set
, false, index
);
935 /* Return the number of ordinary maps allocated in the line table
938 LINEMAPS_ORDINARY_ALLOCATED (const line_maps
*set
)
940 return LINEMAPS_ALLOCATED (set
, false);
943 /* Return the number of ordinary maps used in the line table SET. */
945 LINEMAPS_ORDINARY_USED (const line_maps
*set
)
947 return LINEMAPS_USED (set
, false);
950 /* Return the index of the last ordinary map that was looked up with
952 inline unsigned int &
953 LINEMAPS_ORDINARY_CACHE (const line_maps
*set
)
955 return LINEMAPS_CACHE (set
, false);
958 /* Returns a pointer to the last ordinary map used in the line table
960 inline line_map_ordinary
*
961 LINEMAPS_LAST_ORDINARY_MAP (const line_maps
*set
)
963 return (line_map_ordinary
*)LINEMAPS_LAST_MAP (set
, false);
966 /* Returns a pointer to the last ordinary map allocated the line table
968 inline line_map_ordinary
*
969 LINEMAPS_LAST_ALLOCATED_ORDINARY_MAP (const line_maps
*set
)
971 return (line_map_ordinary
*)LINEMAPS_LAST_ALLOCATED_MAP (set
, false);
974 /* Returns a pointer to the beginning of the region where macro maps
976 inline line_map_macro
*
977 LINEMAPS_MACRO_MAPS (const line_maps
*set
)
979 return set
->info_macro
.maps
;
982 /* Returns the INDEXth macro map. */
983 inline line_map_macro
*
984 LINEMAPS_MACRO_MAP_AT (const line_maps
*set
, int index
)
986 linemap_assert (index
>= 0
987 && (unsigned int)index
< LINEMAPS_USED (set
, true));
988 return (line_map_macro
*)LINEMAPS_MAP_AT (set
, true, index
);
991 /* Returns the number of macro maps that were allocated in the line
994 LINEMAPS_MACRO_ALLOCATED (const line_maps
*set
)
996 return LINEMAPS_ALLOCATED (set
, true);
999 /* Returns the number of macro maps used in the line table SET. */
1001 LINEMAPS_MACRO_USED (const line_maps
*set
)
1003 return LINEMAPS_USED (set
, true);
1006 /* Return the index of the last macro map that was looked up with
1008 inline unsigned int &
1009 LINEMAPS_MACRO_CACHE (const line_maps
*set
)
1011 return LINEMAPS_CACHE (set
, true);
1014 /* Returns the last macro map used in the line table SET. */
1015 inline line_map_macro
*
1016 LINEMAPS_LAST_MACRO_MAP (const line_maps
*set
)
1018 return (line_map_macro
*)LINEMAPS_LAST_MAP (set
, true);
1021 /* Returns the lowest location [of a token resulting from macro
1022 expansion] encoded in this line table. */
1024 LINEMAPS_MACRO_LOWEST_LOCATION (const line_maps
*set
)
1026 return LINEMAPS_MACRO_USED (set
)
1027 ? MAP_START_LOCATION (LINEMAPS_LAST_MACRO_MAP (set
))
1028 : MAX_LOCATION_T
+ 1;
1031 /* Returns the last macro map allocated in the line table SET. */
1032 inline line_map_macro
*
1033 LINEMAPS_LAST_ALLOCATED_MACRO_MAP (const line_maps
*set
)
1035 return (line_map_macro
*)LINEMAPS_LAST_ALLOCATED_MAP (set
, true);
1038 extern location_t
get_combined_adhoc_loc (line_maps
*, location_t
,
1039 source_range
, void *);
1040 extern void *get_data_from_adhoc_loc (const line_maps
*, location_t
);
1041 extern location_t
get_location_from_adhoc_loc (const line_maps
*,
1044 extern source_range
get_range_from_loc (line_maps
*set
, location_t loc
);
1046 /* Get whether location LOC is a "pure" location, or
1047 whether it is an ad-hoc location, or embeds range information. */
1050 pure_location_p (line_maps
*set
, location_t loc
);
1052 /* Given location LOC within SET, strip away any packed range information
1053 or ad-hoc information. */
1055 extern location_t
get_pure_location (line_maps
*set
, location_t loc
);
1057 /* Combine LOC and BLOCK, giving a combined adhoc location. */
1060 COMBINE_LOCATION_DATA (class line_maps
*set
,
1062 source_range src_range
,
1065 return get_combined_adhoc_loc (set
, loc
, src_range
, block
);
1068 extern void rebuild_location_adhoc_htab (class line_maps
*);
1070 /* Initialize a line map set. SET is the line map set to initialize
1071 and BUILTIN_LOCATION is the special location value to be used as
1072 spelling location for built-in tokens. This BUILTIN_LOCATION has
1073 to be strictly less than RESERVED_LOCATION_COUNT. */
1074 extern void linemap_init (class line_maps
*set
,
1075 location_t builtin_location
);
1077 /* Check for and warn about line_maps entered but not exited. */
1079 extern void linemap_check_files_exited (class line_maps
*);
1081 /* Return a location_t for the start (i.e. column==0) of
1082 (physical) line TO_LINE in the current source file (as in the
1083 most recent linemap_add). MAX_COLUMN_HINT is the highest column
1084 number we expect to use in this line (but it does not change
1085 the highest_location). */
1087 extern location_t linemap_line_start
1088 (class line_maps
*set
, linenum_type to_line
, unsigned int max_column_hint
);
1090 /* Allocate a raw block of line maps, zero initialized. */
1091 extern line_map
*line_map_new_raw (line_maps
*, bool, unsigned);
1093 /* Add a mapping of logical source line to physical source file and
1094 line number. This function creates an "ordinary map", which is a
1095 map that records locations of tokens that are not part of macro
1096 replacement-lists present at a macro expansion point.
1098 The text pointed to by TO_FILE must have a lifetime
1099 at least as long as the lifetime of SET. An empty
1100 TO_FILE means standard input. If reason is LC_LEAVE, and
1101 TO_FILE is NULL, then TO_FILE, TO_LINE and SYSP are given their
1102 natural values considering the file we are returning to.
1104 A call to this function can relocate the previous set of
1105 maps, so any stored line_map pointers should not be used. */
1106 extern const line_map
*linemap_add
1107 (class line_maps
*, enum lc_reason
, unsigned int sysp
,
1108 const char *to_file
, linenum_type to_line
);
1110 /* Create a macro map. A macro map encodes source locations of tokens
1111 that are part of a macro replacement-list, at a macro expansion
1112 point. See the extensive comments of struct line_map and struct
1113 line_map_macro, in line-map.h.
1115 This map shall be created when the macro is expanded. The map
1116 encodes the source location of the expansion point of the macro as
1117 well as the "original" source location of each token that is part
1118 of the macro replacement-list. If a macro is defined but never
1119 expanded, it has no macro map. SET is the set of maps the macro
1120 map should be part of. MACRO_NODE is the macro which the new macro
1121 map should encode source locations for. EXPANSION is the location
1122 of the expansion point of MACRO. For function-like macros
1123 invocations, it's best to make it point to the closing parenthesis
1124 of the macro, rather than the the location of the first character
1125 of the macro. NUM_TOKENS is the number of tokens that are part of
1126 the replacement-list of MACRO. */
1127 const line_map_macro
*linemap_enter_macro (line_maps
*, cpp_hashnode
*,
1128 location_t
, unsigned int);
1130 /* Create a source location for a module. The creator must either do
1131 this after the TU is tokenized, or deal with saving and restoring
1134 extern location_t linemap_module_loc
1135 (line_maps
*, location_t from
, const char *name
);
1136 extern void linemap_module_reparent
1137 (line_maps
*, location_t loc
, location_t new_parent
);
1139 /* Restore the linemap state such that the map at LWM-1 continues. */
1140 extern void linemap_module_restore
1141 (line_maps
*, unsigned lwm
);
1143 /* Given a logical source location, returns the map which the
1144 corresponding (source file, line, column) triplet can be deduced
1145 from. Since the set is built chronologically, the logical lines are
1146 monotonic increasing, and so the list is sorted and we can use a
1147 binary search. If no line map have been allocated yet, this
1148 function returns NULL. */
1149 extern const line_map
*linemap_lookup
1150 (const line_maps
*, location_t
);
1152 unsigned linemap_lookup_macro_index (const line_maps
*, location_t
);
1154 /* Returns TRUE if the line table set tracks token locations across
1155 macro expansion, FALSE otherwise. */
1156 bool linemap_tracks_macro_expansion_locs_p (class line_maps
*);
1158 /* Return the name of the macro associated to MACRO_MAP. */
1159 const char* linemap_map_get_macro_name (const line_map_macro
*);
1161 /* Return a positive value if LOCATION is the locus of a token that is
1162 located in a system header, O otherwise. It returns 1 if LOCATION
1163 is the locus of a token that is located in a system header, and 2
1164 if LOCATION is the locus of a token located in a C system header
1165 that therefore needs to be extern "C" protected in C++.
1167 Note that this function returns 1 if LOCATION belongs to a token
1168 that is part of a macro replacement-list defined in a system
1169 header, but expanded in a non-system file. */
1170 int linemap_location_in_system_header_p (class line_maps
*,
1173 /* Return TRUE if LOCATION is a source code location of a token that is part of
1174 a macro expansion, FALSE otherwise. */
1175 bool linemap_location_from_macro_expansion_p (const line_maps
*,
1178 /* TRUE if LOCATION is a source code location of a token that is part of the
1179 definition of a macro, FALSE otherwise. */
1180 bool linemap_location_from_macro_definition_p (class line_maps
*,
1183 /* With the precondition that LOCATION is the locus of a token that is
1184 an argument of a function-like macro MACRO_MAP and appears in the
1185 expansion of MACRO_MAP, return the locus of that argument in the
1186 context of the caller of MACRO_MAP. */
1188 extern location_t linemap_macro_map_loc_unwind_toward_spelling
1189 (line_maps
*set
, const line_map_macro
*macro_map
, location_t location
);
1191 /* location_t values from 0 to RESERVED_LOCATION_COUNT-1 will
1192 be reserved for libcpp user as special values, no token from libcpp
1193 will contain any of those locations. */
1194 const location_t RESERVED_LOCATION_COUNT
= 2;
1196 /* Converts a map and a location_t to source line. */
1198 SOURCE_LINE (const line_map_ordinary
*ord_map
, location_t loc
)
1200 return ((loc
- ord_map
->start_location
)
1201 >> ord_map
->m_column_and_range_bits
) + ord_map
->to_line
;
1204 /* Convert a map and location_t to source column number. */
1206 SOURCE_COLUMN (const line_map_ordinary
*ord_map
, location_t loc
)
1208 return ((loc
- ord_map
->start_location
)
1209 & ((1 << ord_map
->m_column_and_range_bits
) - 1)) >> ord_map
->m_range_bits
;
1214 linemap_included_from (const line_map_ordinary
*ord_map
)
1216 return ord_map
->included_from
;
1219 /* The linemap containing the included-from location of MAP. */
1220 const line_map_ordinary
*linemap_included_from_linemap
1221 (line_maps
*set
, const line_map_ordinary
*map
);
1223 /* True if the map is at the bottom of the include stack. */
1226 MAIN_FILE_P (const line_map_ordinary
*ord_map
)
1228 return ord_map
->included_from
== 0;
1231 /* Encode and return a location_t from a column number. The
1232 source line considered is the last source line used to call
1233 linemap_line_start, i.e, the last source line which a location was
1236 linemap_position_for_column (class line_maps
*, unsigned int);
1238 /* Encode and return a source location from a given line and
1241 linemap_position_for_line_and_column (line_maps
*set
,
1242 const line_map_ordinary
*,
1243 linenum_type
, unsigned int);
1245 /* Encode and return a location_t starting from location LOC and
1246 shifting it by OFFSET columns. This function does not support
1247 virtual locations. */
1249 linemap_position_for_loc_and_offset (class line_maps
*set
,
1251 unsigned int offset
);
1253 /* Return the file this map is for. */
1255 LINEMAP_FILE (const line_map_ordinary
*ord_map
)
1257 return ord_map
->to_file
;
1260 /* Return the line number this map started encoding location from. */
1262 LINEMAP_LINE (const line_map_ordinary
*ord_map
)
1264 return ord_map
->to_line
;
1267 /* Return a positive value if map encodes locations from a system
1268 header, 0 otherwise. Returns 1 if MAP encodes locations in a
1269 system header and 2 if it encodes locations in a C system header
1270 that therefore needs to be extern "C" protected in C++. */
1271 inline unsigned char
1272 LINEMAP_SYSP (const line_map_ordinary
*ord_map
)
1274 return ord_map
->sysp
;
1277 const struct line_map
*first_map_in_common (line_maps
*set
,
1280 location_t
*res_loc0
,
1281 location_t
*res_loc1
);
1283 /* Return a positive value if PRE denotes the location of a token that
1284 comes before the token of POST, 0 if PRE denotes the location of
1285 the same token as the token for POST, and a negative value
1287 int linemap_compare_locations (class line_maps
*set
,
1291 /* Return TRUE if LOC_A denotes the location a token that comes
1292 topogically before the token denoted by location LOC_B, or if they
1295 linemap_location_before_p (class line_maps
*set
,
1299 return linemap_compare_locations (set
, loc_a
, loc_b
) >= 0;
1304 /* The name of the source file involved. */
1307 /* The line-location in the source file. */
1314 /* In a system header?. */
1316 } expanded_location
;
1320 /* A hint to diagnostic_show_locus on how to print a source range within a
1323 Typically this is SHOW_RANGE_WITH_CARET for the 0th range, and
1324 SHOW_RANGE_WITHOUT_CARET for subsequent ranges,
1325 but the Fortran frontend uses SHOW_RANGE_WITH_CARET repeatedly for
1326 printing things like:
1330 Error: Shapes for operands at (1) and (2) are not conformable
1332 where "1" and "2" are notionally carets. */
1334 enum range_display_kind
1336 /* Show the pertinent source line(s), the caret, and underline(s). */
1337 SHOW_RANGE_WITH_CARET
,
1339 /* Show the pertinent source line(s) and underline(s), but don't
1340 show the caret (just an underline). */
1341 SHOW_RANGE_WITHOUT_CARET
,
1343 /* Just show the source lines; don't show the range itself.
1344 This is for use when displaying some line-insertion fix-it hints (for
1345 showing the user context on the change, for when it doesn't make sense
1346 to highlight the first column on the next line). */
1347 SHOW_LINES_WITHOUT_RANGE
1350 /* A location within a rich_location: a caret&range, with
1351 the caret potentially flagged for display, and an optional
1354 struct location_range
1358 enum range_display_kind m_range_display_kind
;
1360 /* If non-NULL, the label for this range. */
1361 const range_label
*m_label
;
1364 /* A partially-embedded vec for use within rich_location for storing
1365 ranges and fix-it hints.
1367 Elements [0..NUM_EMBEDDED) are allocated within m_embed, after
1368 that they are within the dynamically-allocated m_extra.
1370 This allows for static allocation in the common case, whilst
1371 supporting the rarer case of an arbitrary number of elements.
1373 Dynamic allocation is not performed unless it's needed. */
1375 template <typename T
, int NUM_EMBEDDED
>
1376 class semi_embedded_vec
1379 semi_embedded_vec ();
1380 ~semi_embedded_vec ();
1382 unsigned int count () const { return m_num
; }
1383 T
& operator[] (int idx
);
1384 const T
& operator[] (int idx
) const;
1386 void push (const T
&);
1387 void truncate (int len
);
1391 T m_embedded
[NUM_EMBEDDED
];
1396 /* Constructor for semi_embedded_vec. In particular, no dynamic allocation
1399 template <typename T
, int NUM_EMBEDDED
>
1400 semi_embedded_vec
<T
, NUM_EMBEDDED
>::semi_embedded_vec ()
1401 : m_num (0), m_alloc (0), m_extra (NULL
)
1405 /* semi_embedded_vec's dtor. Release any dynamically-allocated memory. */
1407 template <typename T
, int NUM_EMBEDDED
>
1408 semi_embedded_vec
<T
, NUM_EMBEDDED
>::~semi_embedded_vec ()
1410 XDELETEVEC (m_extra
);
1413 /* Look up element IDX, mutably. */
1415 template <typename T
, int NUM_EMBEDDED
>
1417 semi_embedded_vec
<T
, NUM_EMBEDDED
>::operator[] (int idx
)
1419 linemap_assert (idx
< m_num
);
1420 if (idx
< NUM_EMBEDDED
)
1421 return m_embedded
[idx
];
1424 linemap_assert (m_extra
!= NULL
);
1425 return m_extra
[idx
- NUM_EMBEDDED
];
1429 /* Look up element IDX (const). */
1431 template <typename T
, int NUM_EMBEDDED
>
1433 semi_embedded_vec
<T
, NUM_EMBEDDED
>::operator[] (int idx
) const
1435 linemap_assert (idx
< m_num
);
1436 if (idx
< NUM_EMBEDDED
)
1437 return m_embedded
[idx
];
1440 linemap_assert (m_extra
!= NULL
);
1441 return m_extra
[idx
- NUM_EMBEDDED
];
1445 /* Append VALUE to the end of the semi_embedded_vec. */
1447 template <typename T
, int NUM_EMBEDDED
>
1449 semi_embedded_vec
<T
, NUM_EMBEDDED
>::push (const T
& value
)
1452 if (idx
< NUM_EMBEDDED
)
1453 m_embedded
[idx
] = value
;
1456 /* Offset "idx" to be an index within m_extra. */
1457 idx
-= NUM_EMBEDDED
;
1458 if (NULL
== m_extra
)
1460 linemap_assert (m_alloc
== 0);
1462 m_extra
= XNEWVEC (T
, m_alloc
);
1464 else if (idx
>= m_alloc
)
1466 linemap_assert (m_alloc
> 0);
1468 m_extra
= XRESIZEVEC (T
, m_extra
, m_alloc
);
1470 linemap_assert (m_extra
);
1471 linemap_assert (idx
< m_alloc
);
1472 m_extra
[idx
] = value
;
1476 /* Truncate to length LEN. No deallocation is performed. */
1478 template <typename T
, int NUM_EMBEDDED
>
1480 semi_embedded_vec
<T
, NUM_EMBEDDED
>::truncate (int len
)
1482 linemap_assert (len
<= m_num
);
1487 class diagnostic_path
;
1489 /* A "rich" source code location, for use when printing diagnostics.
1490 A rich_location has one or more carets&ranges, where the carets
1491 are optional. These are referred to as "ranges" from here.
1492 Typically the zeroth range has a caret; other ranges sometimes
1495 The "primary" location of a rich_location is the caret of range 0,
1496 used for determining the line/column when printing diagnostic
1499 some-file.c:3:1: error: ...etc...
1501 Additional ranges may be added to help the user identify other
1502 pertinent clauses in a diagnostic.
1504 Ranges can (optionally) be given labels via class range_label.
1506 rich_location instances are intended to be allocated on the stack
1507 when generating diagnostics, and to be short-lived.
1509 Examples of rich locations
1510 --------------------------
1516 This "rich" location is simply a single range (range 0), with
1517 caret = start = finish at the given point.
1523 This rich location has a single range (range 0), with the caret
1524 at the first "&", and the start/finish at the parentheses.
1525 Compare with example C below.
1531 This rich location has three ranges:
1532 - Range 0 has its caret and start location at the first "&" and
1533 end at the second "&.
1534 - Range 1 has its start and finish at the "f" and "o" of "foo";
1535 the caret is not flagged for display, but is perhaps at the "f"
1537 - Similarly, range 2 has its start and finish at the "b" and "r" of
1538 "bar"; the caret is not flagged for display, but is perhaps at the
1540 Compare with example B above.
1542 Example D (Fortran frontend)
1543 ****************************
1546 This rich location has range 0 at "1", and range 1 at "2".
1547 Both are flagged for caret display. Both ranges have start/finish
1548 equal to their caret point. The frontend overrides the diagnostic
1549 context's default caret character for these ranges.
1551 Example E (range labels)
1552 ************************
1553 printf ("arg0: %i arg1: %s arg2: %i",
1561 This rich location has two ranges:
1562 - range 0 is at the "%s" with start = caret = "%" and finish at
1563 the "s". It has a range_label ("const char *").
1564 - range 1 has start/finish covering the "101" and is not flagged for
1565 caret printing. The caret is at the start of "101", where its
1566 range_label is printed ("int").
1571 Rich locations can also contain "fix-it hints", giving suggestions
1572 for the user on how to edit their code to fix a problem. These
1573 can be expressed as insertions, replacements, and removals of text.
1574 The edits by default are relative to the zeroth range within the
1575 rich_location, but optionally they can be expressed relative to
1576 other locations (using various overloaded methods of the form
1577 rich_location::add_fixit_*).
1581 Example F: fix-it hint: insert_before
1582 *************************************
1586 This rich location has a single range (range 0) covering "arr[0]",
1587 with the caret at the start. The rich location has a single
1588 insertion fix-it hint, inserted before range 0, added via
1589 richloc.add_fixit_insert_before ("&");
1591 Example G: multiple fix-it hints: insert_before and insert_after
1592 ****************************************************************
1593 #define FN(ARG0, ARG1, ARG2) fn(ARG0, ARG1, ARG2)
1596 This rich location has three ranges, covering "arg0", "arg1",
1597 and "arg2", all with caret-printing enabled.
1598 The rich location has 6 insertion fix-it hints: each arg
1599 has a pair of insertion fix-it hints, suggesting wrapping
1600 them with parentheses: one a '(' inserted before,
1601 the other a ')' inserted after, added via
1602 richloc.add_fixit_insert_before (LOC, "(");
1604 richloc.add_fixit_insert_after (LOC, ")");
1606 Example H: fix-it hint: removal
1607 *******************************
1611 This rich location has a single range at the stray trailing
1612 semicolon, along with a single removal fix-it hint, covering
1613 the same range, added via:
1614 richloc.add_fixit_remove ();
1616 Example I: fix-it hint: replace
1617 *******************************
1621 This rich location has a single range (range 0) covering "colour",
1622 and a single "replace" fix-it hint, covering the same range,
1624 richloc.add_fixit_replace ("color");
1626 Example J: fix-it hint: line insertion
1627 **************************************
1629 3 | #include <stddef.h>
1630 + |+#include <stdio.h>
1631 4 | int the_next_line;
1633 This rich location has a single range at line 4 column 1, marked
1634 with SHOW_LINES_WITHOUT_RANGE (to avoid printing a meaningless caret
1635 on the "i" of int). It has a insertion fix-it hint of the string
1636 "#include <stdio.h>\n".
1638 Adding a fix-it hint can fail: for example, attempts to insert content
1639 at the transition between two line maps may fail due to there being no
1640 location_t value to express the new location.
1642 Attempts to add a fix-it hint within a macro expansion will fail.
1644 There is only limited support for newline characters in fix-it hints:
1645 only hints with newlines which insert an entire new line are permitted,
1646 inserting at the start of a line, and finishing with a newline
1647 (with no interior newline characters). Other attempts to add
1648 fix-it hints containing newline characters will fail.
1649 Similarly, attempts to delete or replace a range *affecting* multiple
1652 The rich_location API handles these failures gracefully, so that
1653 diagnostics can attempt to add fix-it hints without each needing
1656 Fix-it hints within a rich_location are "atomic": if any hints can't
1657 be applied, none of them will be (tracked by the m_seen_impossible_fixit
1658 flag), and no fix-its hints will be displayed for that rich_location.
1659 This implies that diagnostic messages need to be worded in such a way
1660 that they make sense whether or not the fix-it hints are displayed,
1661 or that richloc.seen_impossible_fixit_p () should be checked before
1662 issuing the diagnostics. */
1669 /* Constructing from a location. */
1670 rich_location (line_maps
*set
, location_t loc
,
1671 const range_label
*label
= NULL
);
1677 location_t
get_loc () const { return get_loc (0); }
1678 location_t
get_loc (unsigned int idx
) const;
1681 add_range (location_t loc
,
1682 enum range_display_kind range_display_kind
1683 = SHOW_RANGE_WITHOUT_CARET
,
1684 const range_label
*label
= NULL
);
1687 set_range (unsigned int idx
, location_t loc
,
1688 enum range_display_kind range_display_kind
);
1690 unsigned int get_num_locations () const { return m_ranges
.count (); }
1692 const location_range
*get_range (unsigned int idx
) const;
1693 location_range
*get_range (unsigned int idx
);
1695 expanded_location
get_expanded_location (unsigned int idx
);
1698 override_column (int column
);
1702 /* Methods for adding insertion fix-it hints. */
1704 /* Suggest inserting NEW_CONTENT immediately before the primary
1707 add_fixit_insert_before (const char *new_content
);
1709 /* Suggest inserting NEW_CONTENT immediately before the start of WHERE. */
1711 add_fixit_insert_before (location_t where
,
1712 const char *new_content
);
1714 /* Suggest inserting NEW_CONTENT immediately after the end of the primary
1717 add_fixit_insert_after (const char *new_content
);
1719 /* Suggest inserting NEW_CONTENT immediately after the end of WHERE. */
1721 add_fixit_insert_after (location_t where
,
1722 const char *new_content
);
1724 /* Methods for adding removal fix-it hints. */
1726 /* Suggest removing the content covered by range 0. */
1728 add_fixit_remove ();
1730 /* Suggest removing the content covered between the start and finish
1733 add_fixit_remove (location_t where
);
1735 /* Suggest removing the content covered by SRC_RANGE. */
1737 add_fixit_remove (source_range src_range
);
1739 /* Methods for adding "replace" fix-it hints. */
1741 /* Suggest replacing the content covered by range 0 with NEW_CONTENT. */
1743 add_fixit_replace (const char *new_content
);
1745 /* Suggest replacing the content between the start and finish of
1746 WHERE with NEW_CONTENT. */
1748 add_fixit_replace (location_t where
,
1749 const char *new_content
);
1751 /* Suggest replacing the content covered by SRC_RANGE with
1754 add_fixit_replace (source_range src_range
,
1755 const char *new_content
);
1757 unsigned int get_num_fixit_hints () const { return m_fixit_hints
.count (); }
1758 fixit_hint
*get_fixit_hint (int idx
) const { return m_fixit_hints
[idx
]; }
1759 fixit_hint
*get_last_fixit_hint () const;
1760 bool seen_impossible_fixit_p () const { return m_seen_impossible_fixit
; }
1762 /* Set this if the fix-it hints are not suitable to be
1763 automatically applied.
1765 For example, if you are suggesting more than one
1766 mutually exclusive solution to a problem, then
1767 it doesn't make sense to apply all of the solutions;
1768 manual intervention is required.
1770 If set, then the fix-it hints in the rich_location will
1771 be printed, but will not be added to generated patches,
1772 or affect the modified version of the file. */
1773 void fixits_cannot_be_auto_applied ()
1775 m_fixits_cannot_be_auto_applied
= true;
1778 bool fixits_can_be_auto_applied_p () const
1780 return !m_fixits_cannot_be_auto_applied
;
1783 /* An optional path through the code. */
1784 const diagnostic_path
*get_path () const { return m_path
; }
1785 void set_path (const diagnostic_path
*path
) { m_path
= path
; }
1788 bool reject_impossible_fixit (location_t where
);
1789 void stop_supporting_fixits ();
1790 void maybe_add_fixit (location_t start
,
1791 location_t next_loc
,
1792 const char *new_content
);
1795 static const int STATICALLY_ALLOCATED_RANGES
= 3;
1798 line_maps
*m_line_table
;
1799 semi_embedded_vec
<location_range
, STATICALLY_ALLOCATED_RANGES
> m_ranges
;
1801 int m_column_override
;
1803 bool m_have_expanded_location
;
1804 expanded_location m_expanded_location
;
1806 static const int MAX_STATIC_FIXIT_HINTS
= 2;
1807 semi_embedded_vec
<fixit_hint
*, MAX_STATIC_FIXIT_HINTS
> m_fixit_hints
;
1809 bool m_seen_impossible_fixit
;
1810 bool m_fixits_cannot_be_auto_applied
;
1812 const diagnostic_path
*m_path
;
1815 /* A struct for the result of range_label::get_text: a NUL-terminated buffer
1816 of localized text, and a flag to determine if the caller should "free" the
1823 : m_buffer (NULL
), m_caller_owned (false)
1832 /* Create a label_text instance that borrows BUFFER from a
1833 longer-lived owner. */
1834 static label_text
borrow (const char *buffer
)
1836 return label_text (const_cast <char *> (buffer
), false);
1839 /* Create a label_text instance that takes ownership of BUFFER. */
1840 static label_text
take (char *buffer
)
1842 return label_text (buffer
, true);
1845 /* Take ownership of the buffer, copying if necessary. */
1846 char *take_or_copy ()
1851 return xstrdup (m_buffer
);
1855 bool m_caller_owned
;
1858 label_text (char *buffer
, bool owned
)
1859 : m_buffer (buffer
), m_caller_owned (owned
)
1863 /* Abstract base class for labelling a range within a rich_location
1864 (e.g. for labelling expressions with their type).
1866 Generating the text could require non-trivial work, so this work
1867 is delayed (via the "get_text" virtual function) until the diagnostic
1868 printing code "knows" it needs it, thus avoiding doing it e.g. for
1869 warnings that are filtered by command-line flags. This virtual
1870 function also isolates libcpp and the diagnostics subsystem from
1871 the front-end and middle-end-specific code for generating the text
1874 Like the rich_location instances they annotate, range_label instances
1875 are intended to be allocated on the stack when generating diagnostics,
1876 and to be short-lived. */
1881 virtual ~range_label () {}
1883 /* Get localized text for the label.
1884 The RANGE_IDX is provided, allowing for range_label instances to be
1885 shared by multiple ranges if need be (the "flyweight" design pattern). */
1886 virtual label_text
get_text (unsigned range_idx
) const = 0;
1889 /* A fix-it hint: a suggested insertion, replacement, or deletion of text.
1890 We handle these three types of edit with one class, by representing
1891 them as replacement of a half-open range:
1893 Insertions have start == next_loc: "replace" the empty string at the
1894 start location with the new string.
1895 Deletions are replacement with the empty string.
1897 There is only limited support for newline characters in fix-it hints
1898 as noted above in the comment for class rich_location.
1899 A fixit_hint instance can have at most one newline character; if
1900 present, the newline character must be the final character of
1901 the content (preventing e.g. fix-its that split a pre-existing line). */
1906 fixit_hint (location_t start
,
1907 location_t next_loc
,
1908 const char *new_content
);
1909 ~fixit_hint () { free (m_bytes
); }
1911 bool affects_line_p (const char *file
, int line
) const;
1912 location_t
get_start_loc () const { return m_start
; }
1913 location_t
get_next_loc () const { return m_next_loc
; }
1914 bool maybe_append (location_t start
,
1915 location_t next_loc
,
1916 const char *new_content
);
1918 const char *get_string () const { return m_bytes
; }
1919 size_t get_length () const { return m_len
; }
1921 bool insertion_p () const { return m_start
== m_next_loc
; }
1923 bool ends_with_newline_p () const;
1926 /* We don't use source_range here since, unlike most places,
1927 this is a half-open/half-closed range:
1929 so that we can support insertion via start == next_loc. */
1931 location_t m_next_loc
;
1937 /* This is enum is used by the function linemap_resolve_location
1938 below. The meaning of the values is explained in the comment of
1940 enum location_resolution_kind
1942 LRK_MACRO_EXPANSION_POINT
,
1943 LRK_SPELLING_LOCATION
,
1944 LRK_MACRO_DEFINITION_LOCATION
1947 /* Resolve a virtual location into either a spelling location, an
1948 expansion point location or a token argument replacement point
1949 location. Return the map that encodes the virtual location as well
1950 as the resolved location.
1952 If LOC is *NOT* the location of a token resulting from the
1953 expansion of a macro, then the parameter LRK (which stands for
1954 Location Resolution Kind) is ignored and the resulting location
1955 just equals the one given in argument.
1957 Now if LOC *IS* the location of a token resulting from the
1958 expansion of a macro, this is what happens.
1960 * If LRK is set to LRK_MACRO_EXPANSION_POINT
1961 -------------------------------
1963 The virtual location is resolved to the first macro expansion point
1964 that led to this macro expansion.
1966 * If LRK is set to LRK_SPELLING_LOCATION
1967 -------------------------------------
1969 The virtual location is resolved to the locus where the token has
1970 been spelled in the source. This can follow through all the macro
1971 expansions that led to the token.
1973 * If LRK is set to LRK_MACRO_DEFINITION_LOCATION
1974 --------------------------------------
1976 The virtual location is resolved to the locus of the token in the
1977 context of the macro definition.
1979 If LOC is the locus of a token that is an argument of a
1980 function-like macro [replacing a parameter in the replacement list
1981 of the macro] the virtual location is resolved to the locus of the
1982 parameter that is replaced, in the context of the definition of the
1985 If LOC is the locus of a token that is not an argument of a
1986 function-like macro, then the function behaves as if LRK was set to
1987 LRK_SPELLING_LOCATION.
1989 If LOC_MAP is not NULL, *LOC_MAP is set to the map encoding the
1990 returned location. Note that if the returned location wasn't originally
1991 encoded by a map, the *MAP is set to NULL. This can happen if LOC
1992 resolves to a location reserved for the client code, like
1993 UNKNOWN_LOCATION or BUILTINS_LOCATION in GCC. */
1995 location_t
linemap_resolve_location (class line_maps
*,
1997 enum location_resolution_kind lrk
,
1998 const line_map_ordinary
**loc_map
);
2000 /* Suppose that LOC is the virtual location of a token coming from the
2001 expansion of a macro M. This function then steps up to get the
2002 location L of the point where M got expanded. If L is a spelling
2003 location inside a macro expansion M', then this function returns
2004 the point where M' was expanded. LOC_MAP is an output parameter.
2005 When non-NULL, *LOC_MAP is set to the map of the returned
2007 location_t
linemap_unwind_toward_expansion (class line_maps
*,
2009 const line_map
**loc_map
);
2011 /* If LOC is the virtual location of a token coming from the expansion
2012 of a macro M and if its spelling location is reserved (e.g, a
2013 location for a built-in token), then this function unwinds (using
2014 linemap_unwind_toward_expansion) the location until a location that
2015 is not reserved and is not in a system header is reached. In other
2016 words, this unwinds the reserved location until a location that is
2017 in real source code is reached.
2019 Otherwise, if the spelling location for LOC is not reserved or if
2020 LOC doesn't come from the expansion of a macro, the function
2021 returns LOC as is and *MAP is not touched.
2023 *MAP is set to the map of the returned location if the later is
2024 different from LOC. */
2025 location_t
linemap_unwind_to_first_non_reserved_loc (class line_maps
*,
2027 const line_map
**map
);
2029 /* Expand source code location LOC and return a user readable source
2030 code location. LOC must be a spelling (non-virtual) location. If
2031 it's a location < RESERVED_LOCATION_COUNT a zeroed expanded source
2032 location is returned. */
2033 expanded_location
linemap_expand_location (class line_maps
*,
2037 /* Statistics about maps allocation and usage as returned by
2038 linemap_get_statistics. */
2039 struct linemap_stats
2041 long num_ordinary_maps_allocated
;
2042 long num_ordinary_maps_used
;
2043 long ordinary_maps_allocated_size
;
2044 long ordinary_maps_used_size
;
2045 long num_expanded_macros
;
2046 long num_macro_tokens
;
2047 long num_macro_maps_used
;
2048 long macro_maps_allocated_size
;
2049 long macro_maps_used_size
;
2050 long macro_maps_locations_size
;
2051 long duplicated_macro_maps_locations_size
;
2052 long adhoc_table_size
;
2053 long adhoc_table_entries_used
;
2056 /* Return the highest location emitted for a given file for which
2057 there is a line map in SET. FILE_NAME is the file name to
2058 consider. If the function returns TRUE, *LOC is set to the highest
2059 location emitted for that file. */
2060 bool linemap_get_file_highest_location (class line_maps
* set
,
2061 const char *file_name
,
2064 /* Compute and return statistics about the memory consumption of some
2065 parts of the line table SET. */
2066 void linemap_get_statistics (line_maps
*, struct linemap_stats
*);
2068 /* Dump debugging information about source location LOC into the file
2069 stream STREAM. SET is the line map set LOC comes from. */
2070 void linemap_dump_location (line_maps
*, location_t
, FILE *);
2072 /* Dump line map at index IX in line table SET to STREAM. If STREAM
2073 is NULL, use stderr. IS_MACRO is true if the caller wants to
2074 dump a macro map, false otherwise. */
2075 void linemap_dump (FILE *, line_maps
*, unsigned, bool);
2077 /* Dump line table SET to STREAM. If STREAM is NULL, stderr is used.
2078 NUM_ORDINARY specifies how many ordinary maps to dump. NUM_MACRO
2079 specifies how many macro maps to dump. */
2080 void line_table_dump (FILE *, line_maps
*, unsigned int, unsigned int);
2082 /* An enum for distinguishing the various parts within a location_t. */
2084 enum location_aspect
2086 LOCATION_ASPECT_CARET
,
2087 LOCATION_ASPECT_START
,
2088 LOCATION_ASPECT_FINISH
2091 /* The rich_location class requires a way to expand location_t instances.
2092 We would directly use expand_location_to_spelling_point, which is
2093 implemented in gcc/input.c, but we also need to use it for rich_location
2095 Hence we require client code of libcpp to implement the following
2097 extern expanded_location
2098 linemap_client_expand_location_to_spelling_point (location_t
,
2099 enum location_aspect
);
2101 #endif /* !LIBCPP_LINE_MAP_H */