1 /* Map (unsigned int) keys to (source file, line, column) triples.
2 Copyright (C) 2001-2021 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 ordinary location. */
569 IS_ORDINARY_LOC (location_t loc
)
571 return loc
< LINE_MAP_MAX_LOCATION
;
574 /* Get whether location LOC is an ad-hoc location. */
577 IS_ADHOC_LOC (location_t loc
)
579 return loc
> MAX_LOCATION_T
;
582 /* Categorize line map kinds. */
585 MAP_ORDINARY_P (const line_map
*map
)
587 return IS_ORDINARY_LOC (map
->start_location
);
590 /* Return TRUE if MAP encodes locations coming from a macro
591 replacement-list at macro expansion point. */
593 linemap_macro_expansion_map_p (const line_map
*);
595 /* Assert that MAP encodes locations of tokens that are not part of
596 the replacement-list of a macro expansion, downcasting from
597 line_map * to line_map_ordinary *. */
599 inline line_map_ordinary
*
600 linemap_check_ordinary (line_map
*map
)
602 linemap_assert (MAP_ORDINARY_P (map
));
603 return (line_map_ordinary
*)map
;
606 /* Assert that MAP encodes locations of tokens that are not part of
607 the replacement-list of a macro expansion, downcasting from
608 const line_map * to const line_map_ordinary *. */
610 inline const line_map_ordinary
*
611 linemap_check_ordinary (const line_map
*map
)
613 linemap_assert (MAP_ORDINARY_P (map
));
614 return (const line_map_ordinary
*)map
;
617 /* Assert that MAP is a macro expansion and downcast to the appropriate
620 inline line_map_macro
*linemap_check_macro (line_map
*map
)
622 linemap_assert (!MAP_ORDINARY_P (map
));
623 return (line_map_macro
*)map
;
626 /* Assert that MAP is a macro expansion and downcast to the appropriate
629 inline const line_map_macro
*
630 linemap_check_macro (const line_map
*map
)
632 linemap_assert (!MAP_ORDINARY_P (map
));
633 return (const line_map_macro
*)map
;
636 /* Read the start location of MAP. */
639 MAP_START_LOCATION (const line_map
*map
)
641 return map
->start_location
;
644 /* Get the starting line number of ordinary map MAP. */
647 ORDINARY_MAP_STARTING_LINE_NUMBER (const line_map_ordinary
*ord_map
)
649 return ord_map
->to_line
;
652 /* Return a positive value if map encodes locations from a system
653 header, 0 otherwise. Returns 1 if ordinary map MAP encodes locations
654 in a system header and 2 if it encodes locations in a C system header
655 that therefore needs to be extern "C" protected in C++. */
658 ORDINARY_MAP_IN_SYSTEM_HEADER_P (const line_map_ordinary
*ord_map
)
660 return ord_map
->sysp
;
663 /* TRUE if this line map is for a module (not a source file). */
666 MAP_MODULE_P (const line_map
*map
)
668 return (MAP_ORDINARY_P (map
)
669 && linemap_check_ordinary (map
)->reason
== LC_MODULE
);
672 /* Get the filename of ordinary map MAP. */
675 ORDINARY_MAP_FILE_NAME (const line_map_ordinary
*ord_map
)
677 return ord_map
->to_file
;
680 /* Get the cpp macro whose expansion gave birth to macro map MAP. */
682 inline cpp_hashnode
*
683 MACRO_MAP_MACRO (const line_map_macro
*macro_map
)
685 return macro_map
->macro
;
688 /* Get the number of tokens inside the replacement-list of the macro
689 that led to macro map MAP. */
692 MACRO_MAP_NUM_MACRO_TOKENS (const line_map_macro
*macro_map
)
694 return macro_map
->n_tokens
;
697 /* Get the array of pairs of locations within macro map MAP.
698 See the declaration of line_map_macro for more information. */
701 MACRO_MAP_LOCATIONS (const line_map_macro
*macro_map
)
703 return macro_map
->macro_locations
;
706 /* Get the location of the expansion point of the macro map MAP. */
709 MACRO_MAP_EXPANSION_POINT_LOCATION (const line_map_macro
*macro_map
)
711 return macro_map
->expansion
;
714 /* The abstraction of a set of location maps. There can be several
715 types of location maps. This abstraction contains the attributes
716 that are independent from the type of the map.
718 Essentially this is just a vector of T_linemap_subclass,
719 which can only ever grow in size. */
721 struct GTY(()) maps_info_ordinary
{
722 /* This array contains the "ordinary" line maps, for all
723 events other than macro expansion
724 (e.g. when a new preprocessing unit starts or ends). */
725 line_map_ordinary
* GTY ((length ("%h.used"))) maps
;
727 /* The total number of allocated maps. */
728 unsigned int allocated
;
730 /* The number of elements used in maps. This number is smaller
731 or equal to ALLOCATED. */
734 mutable unsigned int cache
;
737 struct GTY(()) maps_info_macro
{
738 /* This array contains the macro line maps.
739 A macro line map is created whenever a macro expansion occurs. */
740 line_map_macro
* GTY ((length ("%h.used"))) maps
;
742 /* The total number of allocated maps. */
743 unsigned int allocated
;
745 /* The number of elements used in maps. This number is smaller
746 or equal to ALLOCATED. */
749 mutable unsigned int cache
;
752 /* Data structure to associate a source_range together with an arbitrary
753 data pointer with a source location. */
754 struct GTY(()) location_adhoc_data
{
756 source_range src_range
;
757 void * GTY((skip
)) data
;
762 /* The following data structure encodes a location with some adhoc data
763 and maps it to a new unsigned integer (called an adhoc location)
764 that replaces the original location to represent the mapping.
766 The new adhoc_loc uses the highest bit as the enabling bit, i.e. if the
767 highest bit is 1, then the number is adhoc_loc. Otherwise, it serves as
768 the original location. Once identified as the adhoc_loc, the lower 31
769 bits of the integer is used to index the location_adhoc_data array,
770 in which the locus and associated data is stored. */
772 struct GTY(()) location_adhoc_data_map
{
773 struct htab
* GTY((skip
)) htab
;
775 unsigned int allocated
;
776 struct location_adhoc_data
GTY((length ("%h.allocated"))) *data
;
779 /* A set of chronological line_map structures. */
780 class GTY(()) line_maps
{
785 maps_info_ordinary info_ordinary
;
787 maps_info_macro info_macro
;
789 /* Depth of the include stack, including the current file. */
792 /* If true, prints an include trace a la -H. */
795 /* Highest location_t "given out". */
796 location_t highest_location
;
798 /* Start of line of highest location_t "given out". */
799 location_t highest_line
;
801 /* The maximum column number we can quickly allocate. Higher numbers
802 may require allocating a new line_map. */
803 unsigned int max_column_hint
;
805 /* The allocator to use when resizing 'maps', defaults to xrealloc. */
806 line_map_realloc reallocator
;
808 /* The allocators' function used to know the actual size it
809 allocated, for a certain allocation size requested. */
810 line_map_round_alloc_size_func round_alloc_size
;
812 struct location_adhoc_data_map location_adhoc_data_map
;
814 /* The special location value that is used as spelling location for
816 location_t builtin_location
;
818 /* True if we've seen a #line or # 44 "file" directive. */
819 bool seen_line_directive
;
821 /* The default value of range_bits in ordinary line maps. */
822 unsigned int default_range_bits
;
824 unsigned int num_optimized_ranges
;
825 unsigned int num_unoptimized_ranges
;
828 /* Returns the number of allocated maps so far. MAP_KIND shall be TRUE
829 if we are interested in macro maps, FALSE otherwise. */
831 LINEMAPS_ALLOCATED (const line_maps
*set
, bool map_kind
)
834 return set
->info_macro
.allocated
;
836 return set
->info_ordinary
.allocated
;
839 /* As above, but by reference (e.g. as an lvalue). */
841 inline unsigned int &
842 LINEMAPS_ALLOCATED (line_maps
*set
, bool map_kind
)
845 return set
->info_macro
.allocated
;
847 return set
->info_ordinary
.allocated
;
850 /* Returns the number of used maps so far. MAP_KIND shall be TRUE if
851 we are interested in macro maps, FALSE otherwise.*/
853 LINEMAPS_USED (const line_maps
*set
, bool map_kind
)
856 return set
->info_macro
.used
;
858 return set
->info_ordinary
.used
;
861 /* As above, but by reference (e.g. as an lvalue). */
863 inline unsigned int &
864 LINEMAPS_USED (line_maps
*set
, bool map_kind
)
867 return set
->info_macro
.used
;
869 return set
->info_ordinary
.used
;
872 /* Returns the index of the last map that was looked up with
873 linemap_lookup. MAP_KIND shall be TRUE if we are interested in
874 macro maps, FALSE otherwise. */
875 inline unsigned int &
876 LINEMAPS_CACHE (const line_maps
*set
, bool map_kind
)
879 return set
->info_macro
.cache
;
881 return set
->info_ordinary
.cache
;
884 /* Return the map at a given index. */
886 LINEMAPS_MAP_AT (const line_maps
*set
, bool map_kind
, int index
)
889 return &set
->info_macro
.maps
[index
];
891 return &set
->info_ordinary
.maps
[index
];
894 /* Returns the last map used in the line table SET. MAP_KIND
895 shall be TRUE if we are interested in macro maps, FALSE
898 LINEMAPS_LAST_MAP (const line_maps
*set
, bool map_kind
)
900 return LINEMAPS_MAP_AT (set
, map_kind
,
901 LINEMAPS_USED (set
, map_kind
) - 1);
904 /* Returns the last map that was allocated in the line table SET.
905 MAP_KIND shall be TRUE if we are interested in macro maps, FALSE
908 LINEMAPS_LAST_ALLOCATED_MAP (const line_maps
*set
, bool map_kind
)
910 return LINEMAPS_MAP_AT (set
, map_kind
,
911 LINEMAPS_ALLOCATED (set
, map_kind
) - 1);
914 /* Returns a pointer to the memory region where ordinary maps are
915 allocated in the line table SET. */
916 inline line_map_ordinary
*
917 LINEMAPS_ORDINARY_MAPS (const line_maps
*set
)
919 return set
->info_ordinary
.maps
;
922 /* Returns the INDEXth ordinary map. */
923 inline line_map_ordinary
*
924 LINEMAPS_ORDINARY_MAP_AT (const line_maps
*set
, int index
)
926 linemap_assert (index
>= 0
927 && (unsigned int)index
< LINEMAPS_USED (set
, false));
928 return (line_map_ordinary
*)LINEMAPS_MAP_AT (set
, false, index
);
931 /* Return the number of ordinary maps allocated in the line table
934 LINEMAPS_ORDINARY_ALLOCATED (const line_maps
*set
)
936 return LINEMAPS_ALLOCATED (set
, false);
939 /* Return the number of ordinary maps used in the line table SET. */
941 LINEMAPS_ORDINARY_USED (const line_maps
*set
)
943 return LINEMAPS_USED (set
, false);
946 /* Return the index of the last ordinary map that was looked up with
948 inline unsigned int &
949 LINEMAPS_ORDINARY_CACHE (const line_maps
*set
)
951 return LINEMAPS_CACHE (set
, false);
954 /* Returns a pointer to the last ordinary map used in the line table
956 inline line_map_ordinary
*
957 LINEMAPS_LAST_ORDINARY_MAP (const line_maps
*set
)
959 return (line_map_ordinary
*)LINEMAPS_LAST_MAP (set
, false);
962 /* Returns a pointer to the last ordinary map allocated the line table
964 inline line_map_ordinary
*
965 LINEMAPS_LAST_ALLOCATED_ORDINARY_MAP (const line_maps
*set
)
967 return (line_map_ordinary
*)LINEMAPS_LAST_ALLOCATED_MAP (set
, false);
970 /* Returns a pointer to the beginning of the region where macro maps
972 inline line_map_macro
*
973 LINEMAPS_MACRO_MAPS (const line_maps
*set
)
975 return set
->info_macro
.maps
;
978 /* Returns the INDEXth macro map. */
979 inline line_map_macro
*
980 LINEMAPS_MACRO_MAP_AT (const line_maps
*set
, int index
)
982 linemap_assert (index
>= 0
983 && (unsigned int)index
< LINEMAPS_USED (set
, true));
984 return (line_map_macro
*)LINEMAPS_MAP_AT (set
, true, index
);
987 /* Returns the number of macro maps that were allocated in the line
990 LINEMAPS_MACRO_ALLOCATED (const line_maps
*set
)
992 return LINEMAPS_ALLOCATED (set
, true);
995 /* Returns the number of macro maps used in the line table SET. */
997 LINEMAPS_MACRO_USED (const line_maps
*set
)
999 return LINEMAPS_USED (set
, true);
1002 /* Return the index of the last macro map that was looked up with
1004 inline unsigned int &
1005 LINEMAPS_MACRO_CACHE (const line_maps
*set
)
1007 return LINEMAPS_CACHE (set
, true);
1010 /* Returns the last macro map used in the line table SET. */
1011 inline line_map_macro
*
1012 LINEMAPS_LAST_MACRO_MAP (const line_maps
*set
)
1014 return (line_map_macro
*)LINEMAPS_LAST_MAP (set
, true);
1017 /* Returns the lowest location [of a token resulting from macro
1018 expansion] encoded in this line table. */
1020 LINEMAPS_MACRO_LOWEST_LOCATION (const line_maps
*set
)
1022 return LINEMAPS_MACRO_USED (set
)
1023 ? MAP_START_LOCATION (LINEMAPS_LAST_MACRO_MAP (set
))
1024 : MAX_LOCATION_T
+ 1;
1027 /* Returns the last macro map allocated in the line table SET. */
1028 inline line_map_macro
*
1029 LINEMAPS_LAST_ALLOCATED_MACRO_MAP (const line_maps
*set
)
1031 return (line_map_macro
*)LINEMAPS_LAST_ALLOCATED_MAP (set
, true);
1034 extern location_t
get_combined_adhoc_loc (line_maps
*, location_t
,
1035 source_range
, void *);
1036 extern void *get_data_from_adhoc_loc (const line_maps
*, location_t
);
1037 extern location_t
get_location_from_adhoc_loc (const line_maps
*,
1040 extern source_range
get_range_from_loc (line_maps
*set
, location_t loc
);
1042 /* Get whether location LOC is a "pure" location, or
1043 whether it is an ad-hoc location, or embeds range information. */
1046 pure_location_p (line_maps
*set
, location_t loc
);
1048 /* Given location LOC within SET, strip away any packed range information
1049 or ad-hoc information. */
1051 extern location_t
get_pure_location (line_maps
*set
, location_t loc
);
1053 /* Combine LOC and BLOCK, giving a combined adhoc location. */
1056 COMBINE_LOCATION_DATA (class line_maps
*set
,
1058 source_range src_range
,
1061 return get_combined_adhoc_loc (set
, loc
, src_range
, block
);
1064 extern void rebuild_location_adhoc_htab (class line_maps
*);
1066 /* Initialize a line map set. SET is the line map set to initialize
1067 and BUILTIN_LOCATION is the special location value to be used as
1068 spelling location for built-in tokens. This BUILTIN_LOCATION has
1069 to be strictly less than RESERVED_LOCATION_COUNT. */
1070 extern void linemap_init (class line_maps
*set
,
1071 location_t builtin_location
);
1073 /* Check for and warn about line_maps entered but not exited. */
1075 extern void linemap_check_files_exited (class line_maps
*);
1077 /* Return a location_t for the start (i.e. column==0) of
1078 (physical) line TO_LINE in the current source file (as in the
1079 most recent linemap_add). MAX_COLUMN_HINT is the highest column
1080 number we expect to use in this line (but it does not change
1081 the highest_location). */
1083 extern location_t linemap_line_start
1084 (class line_maps
*set
, linenum_type to_line
, unsigned int max_column_hint
);
1086 /* Allocate a raw block of line maps, zero initialized. */
1087 extern line_map
*line_map_new_raw (line_maps
*, bool, unsigned);
1089 /* Add a mapping of logical source line to physical source file and
1090 line number. This function creates an "ordinary map", which is a
1091 map that records locations of tokens that are not part of macro
1092 replacement-lists present at a macro expansion point.
1094 The text pointed to by TO_FILE must have a lifetime
1095 at least as long as the lifetime of SET. An empty
1096 TO_FILE means standard input. If reason is LC_LEAVE, and
1097 TO_FILE is NULL, then TO_FILE, TO_LINE and SYSP are given their
1098 natural values considering the file we are returning to.
1100 A call to this function can relocate the previous set of
1101 maps, so any stored line_map pointers should not be used. */
1102 extern const line_map
*linemap_add
1103 (class line_maps
*, enum lc_reason
, unsigned int sysp
,
1104 const char *to_file
, linenum_type to_line
);
1106 /* Create a macro map. A macro map encodes source locations of tokens
1107 that are part of a macro replacement-list, at a macro expansion
1108 point. See the extensive comments of struct line_map and struct
1109 line_map_macro, in line-map.h.
1111 This map shall be created when the macro is expanded. The map
1112 encodes the source location of the expansion point of the macro as
1113 well as the "original" source location of each token that is part
1114 of the macro replacement-list. If a macro is defined but never
1115 expanded, it has no macro map. SET is the set of maps the macro
1116 map should be part of. MACRO_NODE is the macro which the new macro
1117 map should encode source locations for. EXPANSION is the location
1118 of the expansion point of MACRO. For function-like macros
1119 invocations, it's best to make it point to the closing parenthesis
1120 of the macro, rather than the the location of the first character
1121 of the macro. NUM_TOKENS is the number of tokens that are part of
1122 the replacement-list of MACRO. */
1123 const line_map_macro
*linemap_enter_macro (line_maps
*, cpp_hashnode
*,
1124 location_t
, unsigned int);
1126 /* Create a source location for a module. The creator must either do
1127 this after the TU is tokenized, or deal with saving and restoring
1130 extern location_t linemap_module_loc
1131 (line_maps
*, location_t from
, const char *name
);
1132 extern void linemap_module_reparent
1133 (line_maps
*, location_t loc
, location_t new_parent
);
1135 /* Restore the linemap state such that the map at LWM-1 continues.
1136 Return start location of the new map. */
1137 extern unsigned linemap_module_restore
1138 (line_maps
*, unsigned lwm
);
1140 /* Given a logical source location, returns the map which the
1141 corresponding (source file, line, column) triplet can be deduced
1142 from. Since the set is built chronologically, the logical lines are
1143 monotonic increasing, and so the list is sorted and we can use a
1144 binary search. If no line map have been allocated yet, this
1145 function returns NULL. */
1146 extern const line_map
*linemap_lookup
1147 (const line_maps
*, location_t
);
1149 unsigned linemap_lookup_macro_index (const line_maps
*, location_t
);
1151 /* Returns TRUE if the line table set tracks token locations across
1152 macro expansion, FALSE otherwise. */
1153 bool linemap_tracks_macro_expansion_locs_p (class line_maps
*);
1155 /* Return the name of the macro associated to MACRO_MAP. */
1156 const char* linemap_map_get_macro_name (const line_map_macro
*);
1158 /* Return a positive value if LOCATION is the locus of a token that is
1159 located in a system header, O otherwise. It returns 1 if LOCATION
1160 is the locus of a token that is located in a system header, and 2
1161 if LOCATION is the locus of a token located in a C system header
1162 that therefore needs to be extern "C" protected in C++.
1164 Note that this function returns 1 if LOCATION belongs to a token
1165 that is part of a macro replacement-list defined in a system
1166 header, but expanded in a non-system file. */
1167 int linemap_location_in_system_header_p (class line_maps
*,
1170 /* Return TRUE if LOCATION is a source code location of a token that is part of
1171 a macro expansion, FALSE otherwise. */
1172 bool linemap_location_from_macro_expansion_p (const line_maps
*,
1175 /* TRUE if LOCATION is a source code location of a token that is part of the
1176 definition of a macro, FALSE otherwise. */
1177 bool linemap_location_from_macro_definition_p (class line_maps
*,
1180 /* With the precondition that LOCATION is the locus of a token that is
1181 an argument of a function-like macro MACRO_MAP and appears in the
1182 expansion of MACRO_MAP, return the locus of that argument in the
1183 context of the caller of MACRO_MAP. */
1185 extern location_t linemap_macro_map_loc_unwind_toward_spelling
1186 (line_maps
*set
, const line_map_macro
*macro_map
, location_t location
);
1188 /* location_t values from 0 to RESERVED_LOCATION_COUNT-1 will
1189 be reserved for libcpp user as special values, no token from libcpp
1190 will contain any of those locations. */
1191 const location_t RESERVED_LOCATION_COUNT
= 2;
1193 /* Converts a map and a location_t to source line. */
1195 SOURCE_LINE (const line_map_ordinary
*ord_map
, location_t loc
)
1197 return ((loc
- ord_map
->start_location
)
1198 >> ord_map
->m_column_and_range_bits
) + ord_map
->to_line
;
1201 /* Convert a map and location_t to source column number. */
1203 SOURCE_COLUMN (const line_map_ordinary
*ord_map
, location_t loc
)
1205 return ((loc
- ord_map
->start_location
)
1206 & ((1 << ord_map
->m_column_and_range_bits
) - 1)) >> ord_map
->m_range_bits
;
1211 linemap_included_from (const line_map_ordinary
*ord_map
)
1213 return ord_map
->included_from
;
1216 /* The linemap containing the included-from location of MAP. */
1217 const line_map_ordinary
*linemap_included_from_linemap
1218 (line_maps
*set
, const line_map_ordinary
*map
);
1220 /* True if the map is at the bottom of the include stack. */
1223 MAIN_FILE_P (const line_map_ordinary
*ord_map
)
1225 return ord_map
->included_from
== 0;
1228 /* Encode and return a location_t from a column number. The
1229 source line considered is the last source line used to call
1230 linemap_line_start, i.e, the last source line which a location was
1233 linemap_position_for_column (class line_maps
*, unsigned int);
1235 /* Encode and return a source location from a given line and
1238 linemap_position_for_line_and_column (line_maps
*set
,
1239 const line_map_ordinary
*,
1240 linenum_type
, unsigned int);
1242 /* Encode and return a location_t starting from location LOC and
1243 shifting it by OFFSET columns. This function does not support
1244 virtual locations. */
1246 linemap_position_for_loc_and_offset (class line_maps
*set
,
1248 unsigned int offset
);
1250 /* Return the file this map is for. */
1252 LINEMAP_FILE (const line_map_ordinary
*ord_map
)
1254 return ord_map
->to_file
;
1257 /* Return the line number this map started encoding location from. */
1259 LINEMAP_LINE (const line_map_ordinary
*ord_map
)
1261 return ord_map
->to_line
;
1264 /* Return a positive value if map encodes locations from a system
1265 header, 0 otherwise. Returns 1 if MAP encodes locations in a
1266 system header and 2 if it encodes locations in a C system header
1267 that therefore needs to be extern "C" protected in C++. */
1268 inline unsigned char
1269 LINEMAP_SYSP (const line_map_ordinary
*ord_map
)
1271 return ord_map
->sysp
;
1274 const struct line_map
*first_map_in_common (line_maps
*set
,
1277 location_t
*res_loc0
,
1278 location_t
*res_loc1
);
1280 /* Return a positive value if PRE denotes the location of a token that
1281 comes before the token of POST, 0 if PRE denotes the location of
1282 the same token as the token for POST, and a negative value
1284 int linemap_compare_locations (class line_maps
*set
,
1288 /* Return TRUE if LOC_A denotes the location a token that comes
1289 topogically before the token denoted by location LOC_B, or if they
1292 linemap_location_before_p (class line_maps
*set
,
1296 return linemap_compare_locations (set
, loc_a
, loc_b
) >= 0;
1301 /* The name of the source file involved. */
1304 /* The line-location in the source file. */
1311 /* In a system header?. */
1313 } expanded_location
;
1317 /* A hint to diagnostic_show_locus on how to print a source range within a
1320 Typically this is SHOW_RANGE_WITH_CARET for the 0th range, and
1321 SHOW_RANGE_WITHOUT_CARET for subsequent ranges,
1322 but the Fortran frontend uses SHOW_RANGE_WITH_CARET repeatedly for
1323 printing things like:
1327 Error: Shapes for operands at (1) and (2) are not conformable
1329 where "1" and "2" are notionally carets. */
1331 enum range_display_kind
1333 /* Show the pertinent source line(s), the caret, and underline(s). */
1334 SHOW_RANGE_WITH_CARET
,
1336 /* Show the pertinent source line(s) and underline(s), but don't
1337 show the caret (just an underline). */
1338 SHOW_RANGE_WITHOUT_CARET
,
1340 /* Just show the source lines; don't show the range itself.
1341 This is for use when displaying some line-insertion fix-it hints (for
1342 showing the user context on the change, for when it doesn't make sense
1343 to highlight the first column on the next line). */
1344 SHOW_LINES_WITHOUT_RANGE
1347 /* A location within a rich_location: a caret&range, with
1348 the caret potentially flagged for display, and an optional
1351 struct location_range
1355 enum range_display_kind m_range_display_kind
;
1357 /* If non-NULL, the label for this range. */
1358 const range_label
*m_label
;
1361 /* A partially-embedded vec for use within rich_location for storing
1362 ranges and fix-it hints.
1364 Elements [0..NUM_EMBEDDED) are allocated within m_embed, after
1365 that they are within the dynamically-allocated m_extra.
1367 This allows for static allocation in the common case, whilst
1368 supporting the rarer case of an arbitrary number of elements.
1370 Dynamic allocation is not performed unless it's needed. */
1372 template <typename T
, int NUM_EMBEDDED
>
1373 class semi_embedded_vec
1376 semi_embedded_vec ();
1377 ~semi_embedded_vec ();
1379 unsigned int count () const { return m_num
; }
1380 T
& operator[] (int idx
);
1381 const T
& operator[] (int idx
) const;
1383 void push (const T
&);
1384 void truncate (int len
);
1388 T m_embedded
[NUM_EMBEDDED
];
1393 /* Constructor for semi_embedded_vec. In particular, no dynamic allocation
1396 template <typename T
, int NUM_EMBEDDED
>
1397 semi_embedded_vec
<T
, NUM_EMBEDDED
>::semi_embedded_vec ()
1398 : m_num (0), m_alloc (0), m_extra (NULL
)
1402 /* semi_embedded_vec's dtor. Release any dynamically-allocated memory. */
1404 template <typename T
, int NUM_EMBEDDED
>
1405 semi_embedded_vec
<T
, NUM_EMBEDDED
>::~semi_embedded_vec ()
1407 XDELETEVEC (m_extra
);
1410 /* Look up element IDX, mutably. */
1412 template <typename T
, int NUM_EMBEDDED
>
1414 semi_embedded_vec
<T
, NUM_EMBEDDED
>::operator[] (int idx
)
1416 linemap_assert (idx
< m_num
);
1417 if (idx
< NUM_EMBEDDED
)
1418 return m_embedded
[idx
];
1421 linemap_assert (m_extra
!= NULL
);
1422 return m_extra
[idx
- NUM_EMBEDDED
];
1426 /* Look up element IDX (const). */
1428 template <typename T
, int NUM_EMBEDDED
>
1430 semi_embedded_vec
<T
, NUM_EMBEDDED
>::operator[] (int idx
) const
1432 linemap_assert (idx
< m_num
);
1433 if (idx
< NUM_EMBEDDED
)
1434 return m_embedded
[idx
];
1437 linemap_assert (m_extra
!= NULL
);
1438 return m_extra
[idx
- NUM_EMBEDDED
];
1442 /* Append VALUE to the end of the semi_embedded_vec. */
1444 template <typename T
, int NUM_EMBEDDED
>
1446 semi_embedded_vec
<T
, NUM_EMBEDDED
>::push (const T
& value
)
1449 if (idx
< NUM_EMBEDDED
)
1450 m_embedded
[idx
] = value
;
1453 /* Offset "idx" to be an index within m_extra. */
1454 idx
-= NUM_EMBEDDED
;
1455 if (NULL
== m_extra
)
1457 linemap_assert (m_alloc
== 0);
1459 m_extra
= XNEWVEC (T
, m_alloc
);
1461 else if (idx
>= m_alloc
)
1463 linemap_assert (m_alloc
> 0);
1465 m_extra
= XRESIZEVEC (T
, m_extra
, m_alloc
);
1467 linemap_assert (m_extra
);
1468 linemap_assert (idx
< m_alloc
);
1469 m_extra
[idx
] = value
;
1473 /* Truncate to length LEN. No deallocation is performed. */
1475 template <typename T
, int NUM_EMBEDDED
>
1477 semi_embedded_vec
<T
, NUM_EMBEDDED
>::truncate (int len
)
1479 linemap_assert (len
<= m_num
);
1484 class diagnostic_path
;
1486 /* A "rich" source code location, for use when printing diagnostics.
1487 A rich_location has one or more carets&ranges, where the carets
1488 are optional. These are referred to as "ranges" from here.
1489 Typically the zeroth range has a caret; other ranges sometimes
1492 The "primary" location of a rich_location is the caret of range 0,
1493 used for determining the line/column when printing diagnostic
1496 some-file.c:3:1: error: ...etc...
1498 Additional ranges may be added to help the user identify other
1499 pertinent clauses in a diagnostic.
1501 Ranges can (optionally) be given labels via class range_label.
1503 rich_location instances are intended to be allocated on the stack
1504 when generating diagnostics, and to be short-lived.
1506 Examples of rich locations
1507 --------------------------
1513 This "rich" location is simply a single range (range 0), with
1514 caret = start = finish at the given point.
1520 This rich location has a single range (range 0), with the caret
1521 at the first "&", and the start/finish at the parentheses.
1522 Compare with example C below.
1528 This rich location has three ranges:
1529 - Range 0 has its caret and start location at the first "&" and
1530 end at the second "&.
1531 - Range 1 has its start and finish at the "f" and "o" of "foo";
1532 the caret is not flagged for display, but is perhaps at the "f"
1534 - Similarly, range 2 has its start and finish at the "b" and "r" of
1535 "bar"; the caret is not flagged for display, but is perhaps at the
1537 Compare with example B above.
1539 Example D (Fortran frontend)
1540 ****************************
1543 This rich location has range 0 at "1", and range 1 at "2".
1544 Both are flagged for caret display. Both ranges have start/finish
1545 equal to their caret point. The frontend overrides the diagnostic
1546 context's default caret character for these ranges.
1548 Example E (range labels)
1549 ************************
1550 printf ("arg0: %i arg1: %s arg2: %i",
1558 This rich location has two ranges:
1559 - range 0 is at the "%s" with start = caret = "%" and finish at
1560 the "s". It has a range_label ("const char *").
1561 - range 1 has start/finish covering the "101" and is not flagged for
1562 caret printing. The caret is at the start of "101", where its
1563 range_label is printed ("int").
1568 Rich locations can also contain "fix-it hints", giving suggestions
1569 for the user on how to edit their code to fix a problem. These
1570 can be expressed as insertions, replacements, and removals of text.
1571 The edits by default are relative to the zeroth range within the
1572 rich_location, but optionally they can be expressed relative to
1573 other locations (using various overloaded methods of the form
1574 rich_location::add_fixit_*).
1578 Example F: fix-it hint: insert_before
1579 *************************************
1583 This rich location has a single range (range 0) covering "arr[0]",
1584 with the caret at the start. The rich location has a single
1585 insertion fix-it hint, inserted before range 0, added via
1586 richloc.add_fixit_insert_before ("&");
1588 Example G: multiple fix-it hints: insert_before and insert_after
1589 ****************************************************************
1590 #define FN(ARG0, ARG1, ARG2) fn(ARG0, ARG1, ARG2)
1593 This rich location has three ranges, covering "arg0", "arg1",
1594 and "arg2", all with caret-printing enabled.
1595 The rich location has 6 insertion fix-it hints: each arg
1596 has a pair of insertion fix-it hints, suggesting wrapping
1597 them with parentheses: one a '(' inserted before,
1598 the other a ')' inserted after, added via
1599 richloc.add_fixit_insert_before (LOC, "(");
1601 richloc.add_fixit_insert_after (LOC, ")");
1603 Example H: fix-it hint: removal
1604 *******************************
1608 This rich location has a single range at the stray trailing
1609 semicolon, along with a single removal fix-it hint, covering
1610 the same range, added via:
1611 richloc.add_fixit_remove ();
1613 Example I: fix-it hint: replace
1614 *******************************
1618 This rich location has a single range (range 0) covering "colour",
1619 and a single "replace" fix-it hint, covering the same range,
1621 richloc.add_fixit_replace ("color");
1623 Example J: fix-it hint: line insertion
1624 **************************************
1626 3 | #include <stddef.h>
1627 + |+#include <stdio.h>
1628 4 | int the_next_line;
1630 This rich location has a single range at line 4 column 1, marked
1631 with SHOW_LINES_WITHOUT_RANGE (to avoid printing a meaningless caret
1632 on the "i" of int). It has a insertion fix-it hint of the string
1633 "#include <stdio.h>\n".
1635 Adding a fix-it hint can fail: for example, attempts to insert content
1636 at the transition between two line maps may fail due to there being no
1637 location_t value to express the new location.
1639 Attempts to add a fix-it hint within a macro expansion will fail.
1641 There is only limited support for newline characters in fix-it hints:
1642 only hints with newlines which insert an entire new line are permitted,
1643 inserting at the start of a line, and finishing with a newline
1644 (with no interior newline characters). Other attempts to add
1645 fix-it hints containing newline characters will fail.
1646 Similarly, attempts to delete or replace a range *affecting* multiple
1649 The rich_location API handles these failures gracefully, so that
1650 diagnostics can attempt to add fix-it hints without each needing
1653 Fix-it hints within a rich_location are "atomic": if any hints can't
1654 be applied, none of them will be (tracked by the m_seen_impossible_fixit
1655 flag), and no fix-its hints will be displayed for that rich_location.
1656 This implies that diagnostic messages need to be worded in such a way
1657 that they make sense whether or not the fix-it hints are displayed,
1658 or that richloc.seen_impossible_fixit_p () should be checked before
1659 issuing the diagnostics. */
1666 /* Constructing from a location. */
1667 rich_location (line_maps
*set
, location_t loc
,
1668 const range_label
*label
= NULL
);
1674 location_t
get_loc () const { return get_loc (0); }
1675 location_t
get_loc (unsigned int idx
) const;
1678 add_range (location_t loc
,
1679 enum range_display_kind range_display_kind
1680 = SHOW_RANGE_WITHOUT_CARET
,
1681 const range_label
*label
= NULL
);
1684 set_range (unsigned int idx
, location_t loc
,
1685 enum range_display_kind range_display_kind
);
1687 unsigned int get_num_locations () const { return m_ranges
.count (); }
1689 const location_range
*get_range (unsigned int idx
) const;
1690 location_range
*get_range (unsigned int idx
);
1692 expanded_location
get_expanded_location (unsigned int idx
);
1695 override_column (int column
);
1699 /* Methods for adding insertion fix-it hints. */
1701 /* Suggest inserting NEW_CONTENT immediately before the primary
1704 add_fixit_insert_before (const char *new_content
);
1706 /* Suggest inserting NEW_CONTENT immediately before the start of WHERE. */
1708 add_fixit_insert_before (location_t where
,
1709 const char *new_content
);
1711 /* Suggest inserting NEW_CONTENT immediately after the end of the primary
1714 add_fixit_insert_after (const char *new_content
);
1716 /* Suggest inserting NEW_CONTENT immediately after the end of WHERE. */
1718 add_fixit_insert_after (location_t where
,
1719 const char *new_content
);
1721 /* Methods for adding removal fix-it hints. */
1723 /* Suggest removing the content covered by range 0. */
1725 add_fixit_remove ();
1727 /* Suggest removing the content covered between the start and finish
1730 add_fixit_remove (location_t where
);
1732 /* Suggest removing the content covered by SRC_RANGE. */
1734 add_fixit_remove (source_range src_range
);
1736 /* Methods for adding "replace" fix-it hints. */
1738 /* Suggest replacing the content covered by range 0 with NEW_CONTENT. */
1740 add_fixit_replace (const char *new_content
);
1742 /* Suggest replacing the content between the start and finish of
1743 WHERE with NEW_CONTENT. */
1745 add_fixit_replace (location_t where
,
1746 const char *new_content
);
1748 /* Suggest replacing the content covered by SRC_RANGE with
1751 add_fixit_replace (source_range src_range
,
1752 const char *new_content
);
1754 unsigned int get_num_fixit_hints () const { return m_fixit_hints
.count (); }
1755 fixit_hint
*get_fixit_hint (int idx
) const { return m_fixit_hints
[idx
]; }
1756 fixit_hint
*get_last_fixit_hint () const;
1757 bool seen_impossible_fixit_p () const { return m_seen_impossible_fixit
; }
1759 /* Set this if the fix-it hints are not suitable to be
1760 automatically applied.
1762 For example, if you are suggesting more than one
1763 mutually exclusive solution to a problem, then
1764 it doesn't make sense to apply all of the solutions;
1765 manual intervention is required.
1767 If set, then the fix-it hints in the rich_location will
1768 be printed, but will not be added to generated patches,
1769 or affect the modified version of the file. */
1770 void fixits_cannot_be_auto_applied ()
1772 m_fixits_cannot_be_auto_applied
= true;
1775 bool fixits_can_be_auto_applied_p () const
1777 return !m_fixits_cannot_be_auto_applied
;
1780 /* An optional path through the code. */
1781 const diagnostic_path
*get_path () const { return m_path
; }
1782 void set_path (const diagnostic_path
*path
) { m_path
= path
; }
1785 bool reject_impossible_fixit (location_t where
);
1786 void stop_supporting_fixits ();
1787 void maybe_add_fixit (location_t start
,
1788 location_t next_loc
,
1789 const char *new_content
);
1792 static const int STATICALLY_ALLOCATED_RANGES
= 3;
1795 line_maps
*m_line_table
;
1796 semi_embedded_vec
<location_range
, STATICALLY_ALLOCATED_RANGES
> m_ranges
;
1798 int m_column_override
;
1800 bool m_have_expanded_location
;
1801 expanded_location m_expanded_location
;
1803 static const int MAX_STATIC_FIXIT_HINTS
= 2;
1804 semi_embedded_vec
<fixit_hint
*, MAX_STATIC_FIXIT_HINTS
> m_fixit_hints
;
1806 bool m_seen_impossible_fixit
;
1807 bool m_fixits_cannot_be_auto_applied
;
1809 const diagnostic_path
*m_path
;
1812 /* A struct for the result of range_label::get_text: a NUL-terminated buffer
1813 of localized text, and a flag to determine if the caller should "free" the
1820 : m_buffer (NULL
), m_caller_owned (false)
1829 /* Create a label_text instance that borrows BUFFER from a
1830 longer-lived owner. */
1831 static label_text
borrow (const char *buffer
)
1833 return label_text (const_cast <char *> (buffer
), false);
1836 /* Create a label_text instance that takes ownership of BUFFER. */
1837 static label_text
take (char *buffer
)
1839 return label_text (buffer
, true);
1842 /* Take ownership of the buffer, copying if necessary. */
1843 char *take_or_copy ()
1848 return xstrdup (m_buffer
);
1852 bool m_caller_owned
;
1855 label_text (char *buffer
, bool owned
)
1856 : m_buffer (buffer
), m_caller_owned (owned
)
1860 /* Abstract base class for labelling a range within a rich_location
1861 (e.g. for labelling expressions with their type).
1863 Generating the text could require non-trivial work, so this work
1864 is delayed (via the "get_text" virtual function) until the diagnostic
1865 printing code "knows" it needs it, thus avoiding doing it e.g. for
1866 warnings that are filtered by command-line flags. This virtual
1867 function also isolates libcpp and the diagnostics subsystem from
1868 the front-end and middle-end-specific code for generating the text
1871 Like the rich_location instances they annotate, range_label instances
1872 are intended to be allocated on the stack when generating diagnostics,
1873 and to be short-lived. */
1878 virtual ~range_label () {}
1880 /* Get localized text for the label.
1881 The RANGE_IDX is provided, allowing for range_label instances to be
1882 shared by multiple ranges if need be (the "flyweight" design pattern). */
1883 virtual label_text
get_text (unsigned range_idx
) const = 0;
1886 /* A fix-it hint: a suggested insertion, replacement, or deletion of text.
1887 We handle these three types of edit with one class, by representing
1888 them as replacement of a half-open range:
1890 Insertions have start == next_loc: "replace" the empty string at the
1891 start location with the new string.
1892 Deletions are replacement with the empty string.
1894 There is only limited support for newline characters in fix-it hints
1895 as noted above in the comment for class rich_location.
1896 A fixit_hint instance can have at most one newline character; if
1897 present, the newline character must be the final character of
1898 the content (preventing e.g. fix-its that split a pre-existing line). */
1903 fixit_hint (location_t start
,
1904 location_t next_loc
,
1905 const char *new_content
);
1906 ~fixit_hint () { free (m_bytes
); }
1908 bool affects_line_p (const char *file
, int line
) const;
1909 location_t
get_start_loc () const { return m_start
; }
1910 location_t
get_next_loc () const { return m_next_loc
; }
1911 bool maybe_append (location_t start
,
1912 location_t next_loc
,
1913 const char *new_content
);
1915 const char *get_string () const { return m_bytes
; }
1916 size_t get_length () const { return m_len
; }
1918 bool insertion_p () const { return m_start
== m_next_loc
; }
1920 bool ends_with_newline_p () const;
1923 /* We don't use source_range here since, unlike most places,
1924 this is a half-open/half-closed range:
1926 so that we can support insertion via start == next_loc. */
1928 location_t m_next_loc
;
1934 /* This is enum is used by the function linemap_resolve_location
1935 below. The meaning of the values is explained in the comment of
1937 enum location_resolution_kind
1939 LRK_MACRO_EXPANSION_POINT
,
1940 LRK_SPELLING_LOCATION
,
1941 LRK_MACRO_DEFINITION_LOCATION
1944 /* Resolve a virtual location into either a spelling location, an
1945 expansion point location or a token argument replacement point
1946 location. Return the map that encodes the virtual location as well
1947 as the resolved location.
1949 If LOC is *NOT* the location of a token resulting from the
1950 expansion of a macro, then the parameter LRK (which stands for
1951 Location Resolution Kind) is ignored and the resulting location
1952 just equals the one given in argument.
1954 Now if LOC *IS* the location of a token resulting from the
1955 expansion of a macro, this is what happens.
1957 * If LRK is set to LRK_MACRO_EXPANSION_POINT
1958 -------------------------------
1960 The virtual location is resolved to the first macro expansion point
1961 that led to this macro expansion.
1963 * If LRK is set to LRK_SPELLING_LOCATION
1964 -------------------------------------
1966 The virtual location is resolved to the locus where the token has
1967 been spelled in the source. This can follow through all the macro
1968 expansions that led to the token.
1970 * If LRK is set to LRK_MACRO_DEFINITION_LOCATION
1971 --------------------------------------
1973 The virtual location is resolved to the locus of the token in the
1974 context of the macro definition.
1976 If LOC is the locus of a token that is an argument of a
1977 function-like macro [replacing a parameter in the replacement list
1978 of the macro] the virtual location is resolved to the locus of the
1979 parameter that is replaced, in the context of the definition of the
1982 If LOC is the locus of a token that is not an argument of a
1983 function-like macro, then the function behaves as if LRK was set to
1984 LRK_SPELLING_LOCATION.
1986 If LOC_MAP is not NULL, *LOC_MAP is set to the map encoding the
1987 returned location. Note that if the returned location wasn't originally
1988 encoded by a map, the *MAP is set to NULL. This can happen if LOC
1989 resolves to a location reserved for the client code, like
1990 UNKNOWN_LOCATION or BUILTINS_LOCATION in GCC. */
1992 location_t
linemap_resolve_location (class line_maps
*,
1994 enum location_resolution_kind lrk
,
1995 const line_map_ordinary
**loc_map
);
1997 /* Suppose that LOC is the virtual location of a token coming from the
1998 expansion of a macro M. This function then steps up to get the
1999 location L of the point where M got expanded. If L is a spelling
2000 location inside a macro expansion M', then this function returns
2001 the point where M' was expanded. LOC_MAP is an output parameter.
2002 When non-NULL, *LOC_MAP is set to the map of the returned
2004 location_t
linemap_unwind_toward_expansion (class line_maps
*,
2006 const line_map
**loc_map
);
2008 /* If LOC is the virtual location of a token coming from the expansion
2009 of a macro M and if its spelling location is reserved (e.g, a
2010 location for a built-in token), then this function unwinds (using
2011 linemap_unwind_toward_expansion) the location until a location that
2012 is not reserved and is not in a system header is reached. In other
2013 words, this unwinds the reserved location until a location that is
2014 in real source code is reached.
2016 Otherwise, if the spelling location for LOC is not reserved or if
2017 LOC doesn't come from the expansion of a macro, the function
2018 returns LOC as is and *MAP is not touched.
2020 *MAP is set to the map of the returned location if the later is
2021 different from LOC. */
2022 location_t
linemap_unwind_to_first_non_reserved_loc (class line_maps
*,
2024 const line_map
**map
);
2026 /* Expand source code location LOC and return a user readable source
2027 code location. LOC must be a spelling (non-virtual) location. If
2028 it's a location < RESERVED_LOCATION_COUNT a zeroed expanded source
2029 location is returned. */
2030 expanded_location
linemap_expand_location (class line_maps
*,
2034 /* Statistics about maps allocation and usage as returned by
2035 linemap_get_statistics. */
2036 struct linemap_stats
2038 long num_ordinary_maps_allocated
;
2039 long num_ordinary_maps_used
;
2040 long ordinary_maps_allocated_size
;
2041 long ordinary_maps_used_size
;
2042 long num_expanded_macros
;
2043 long num_macro_tokens
;
2044 long num_macro_maps_used
;
2045 long macro_maps_allocated_size
;
2046 long macro_maps_used_size
;
2047 long macro_maps_locations_size
;
2048 long duplicated_macro_maps_locations_size
;
2049 long adhoc_table_size
;
2050 long adhoc_table_entries_used
;
2053 /* Return the highest location emitted for a given file for which
2054 there is a line map in SET. FILE_NAME is the file name to
2055 consider. If the function returns TRUE, *LOC is set to the highest
2056 location emitted for that file. */
2057 bool linemap_get_file_highest_location (class line_maps
* set
,
2058 const char *file_name
,
2061 /* Compute and return statistics about the memory consumption of some
2062 parts of the line table SET. */
2063 void linemap_get_statistics (line_maps
*, struct linemap_stats
*);
2065 /* Dump debugging information about source location LOC into the file
2066 stream STREAM. SET is the line map set LOC comes from. */
2067 void linemap_dump_location (line_maps
*, location_t
, FILE *);
2069 /* Dump line map at index IX in line table SET to STREAM. If STREAM
2070 is NULL, use stderr. IS_MACRO is true if the caller wants to
2071 dump a macro map, false otherwise. */
2072 void linemap_dump (FILE *, line_maps
*, unsigned, bool);
2074 /* Dump line table SET to STREAM. If STREAM is NULL, stderr is used.
2075 NUM_ORDINARY specifies how many ordinary maps to dump. NUM_MACRO
2076 specifies how many macro maps to dump. */
2077 void line_table_dump (FILE *, line_maps
*, unsigned int, unsigned int);
2079 /* An enum for distinguishing the various parts within a location_t. */
2081 enum location_aspect
2083 LOCATION_ASPECT_CARET
,
2084 LOCATION_ASPECT_START
,
2085 LOCATION_ASPECT_FINISH
2088 /* The rich_location class requires a way to expand location_t instances.
2089 We would directly use expand_location_to_spelling_point, which is
2090 implemented in gcc/input.c, but we also need to use it for rich_location
2092 Hence we require client code of libcpp to implement the following
2094 extern expanded_location
2095 linemap_client_expand_location_to_spelling_point (location_t
,
2096 enum location_aspect
);
2098 #endif /* !LIBCPP_LINE_MAP_H */