1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
9 -- Copyright (C) 2009, Free Software Foundation, Inc. --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 3, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING3. If not, go to --
19 -- http://www.gnu.org/licenses for a complete copy of the license. --
21 -- GNAT was originally developed by the GNAT team at New York University. --
22 -- Extensive contributions were provided by Ada Core Technologies Inc. --
24 ------------------------------------------------------------------------------
26 -- This package defines tables used to store Source Coverage Obligations. It
27 -- is used by Par_SCO to build the SCO information before writing it out to
28 -- the ALI file, and by Get_SCO/Put_SCO to read and write the text form that
29 -- is used in the ALI file.
31 with Types
; use Types
;
37 -- SCO information can exist in one of two forms. In the ALI file, it is
38 -- represented using a text format that is described in this specification.
39 -- Internally it is stored using two tables SCO_Table and SCO_Unit_Table,
40 -- which are also defined in this unit.
42 -- Par_SCO is part of the compiler. It scans the parsed source tree and
43 -- populates the internal tables.
45 -- Get_SCO reads the text lines in ALI format and populates the internal
46 -- tables with corresponding information.
48 -- Put_SCO reads the internal tables and generates text lines in the ALI
51 -- ??? The specification below for the SCO ALI format and the internal
52 -- data structures have been modified, but the implementation has not been
53 -- updated yet to reflect these specification changes.
59 -- Source coverage obligations are generated on a unit-by-unit basis in the
60 -- ALI file, using lines that start with the identifying character C. These
61 -- lines are generated if the -gnateS switch is set.
65 -- In several places in the SCO lines, Sloc ranges appear. These are used
66 -- to indicate the first and last Sloc of some construct in the tree and
67 -- they have the form:
71 -- Note that SCO's are generated only for generic templates, not for
72 -- generic instances (since only the first are part of the source). So
73 -- we don't need generic instantiation stuff in these line:col items.
77 -- The SCO information follows the cross-reference information, so it
78 -- need not be read by tools like gnatbind, gnatmake etc. The SCO output
79 -- is divided into sections, one section for each unit for which SCO's
80 -- are generated. A SCO section has a header of the form:
82 -- C dependency-number filename
84 -- This header precedes SCO information for the unit identified by
85 -- dependency number and file name. The dependency number is the
86 -- index into the generated D lines and is ones origin (i.e. 2 =
87 -- reference to second generated D line).
89 -- Note that the filename here will reflect the original name if
90 -- a Source_Reference pragma was encountered (since all line number
91 -- references will be with respect to the original file).
93 -- Note: the filename is redundant in that it could be deduced from
94 -- the corresponding D line, but it is convenient at least for human
95 -- reading of the SCO information, and means that the SCO information
96 -- can stand on its own without needing other parts of the ALI file.
100 -- For the purpose of SCO generation, the notion of statement includes
101 -- simple statements and also the following declaration types:
104 -- subtype_declaration
105 -- object_declaration
106 -- renaming_declaration
107 -- generic_instantiation
109 -- and the following regions of the syntax tree:
111 -- the part of a case_statement from CASE up to the expression
112 -- the part of a FOR iteration scheme from FOR up to the
113 -- loop_parameter_specification
114 -- the part of an extended_return_statement from RETURN up to the
115 -- expression (if present) or to the return_subtype_indication (if
120 -- These lines correspond to one or more successive statements (in the
121 -- sense of the above list) which are always executed in sequence (in the
122 -- absence of exceptions or other external interruptions).
124 -- Entry points to such sequences are:
126 -- the first statement of any sequence_of_statements
127 -- the first statement after a compound statement
128 -- the first statement after an EXIT, RAISE or GOTO statement
129 -- any statement with a label
131 -- Each entry point must appear as the first entry on a CS line.
132 -- The idea is that if any simple statement on a CS line is known to have
133 -- been executed, then all statements that appear before it on the same
134 -- CS line are certain to also have been executed.
136 -- The form of a statement line in the ALI file is:
138 -- CS *sloc-range [*sloc-range...]
140 -- where each sloc-range corresponds to a single statement, and * is
143 -- t type declaration
144 -- s subtype declaration
145 -- o object declaration
146 -- r renaming declaration
147 -- i generic instantiation
149 -- F FOR loop statement
150 -- R extended RETURN statement
152 -- and is omitted for all other cases.
156 -- Note: in the following description, logical operator includes the
157 -- short circuited forms (so can be any of AND, OR, XOR, NOT, AND THEN,
160 -- Decisions are either simple or complex. A simple decision is a boolean
161 -- expresssion that occurs in the context of a control structure in the
162 -- source program, including WHILE, IF, EXIT WHEN. Note that a boolean
163 -- expression in any other context, for example, on the right side of an
164 -- assignment, is not considered to be a simple decision.
166 -- A complex decision is an occurrence of a logical operator which is not
167 -- itself an operand of some other logical operator. If any operand of
168 -- the logical operator is itself a logical operator, this is not a
169 -- separate decision, it is part of the same decision.
171 -- So for example, if we have
173 -- A, B, C, D : Boolean;
174 -- function F (Arg : Boolean) return Boolean);
176 -- A and then (B or else F (C and then D))
178 -- There are two (complex) decisions here:
180 -- 1. X and then (Y or else Z)
182 -- where X = A, Y = B, and Z = F (C and then D)
186 -- For each decision, a decision line is generated with the form:
190 -- Here * is one of the following characters:
192 -- I decision in IF statement or conditional expression
193 -- E decision in EXIT WHEN statement
194 -- W decision in WHILE iteration scheme
195 -- X decision appearing in some other expression context
197 -- For I, E, W, sloc is the source location of the IF, EXIT or WHILE
200 -- For X, sloc is omitted.
202 -- The expression is a prefix polish form indicating the structure of
203 -- the decision, including logical operators and short circuit forms.
204 -- The following is a grammar showing the structure of expression:
206 -- expression ::= term (if expr is not logical operator)
207 -- expression ::= &sloc term term (if expr is AND or AND THEN)
208 -- expression ::= |sloc term term (if expr is OR or OR ELSE)
209 -- expression ::= ^sloc term term (if expr is XOR)
210 -- expression ::= !sloc term (if expr is NOT)
212 -- In the last four cases, sloc is the source location of the AND, OR,
213 -- XOR or NOT token, respectively.
216 -- term ::= expression
218 -- element ::= outcome sloc-range
220 -- outcome is one of the following letters:
226 -- where t/f are used to mark a condition that has been recognized by
227 -- the compiler as always being true or false.
229 -- & indicates either AND or AND THEN connecting two conditions. In the
230 -- context of Couverture we only permit AND THEN in the source in any
231 -- case, so & can always be understood to be AND THEN.
233 -- | indicates either OR or OR ELSE connection two conditions. In the
234 -- context of Couverture we only permit OR ELSE in the source in any
235 -- case, so | can always be understood to be OR ELSE.
237 -- ^ indicates XOR connecting two conditions. In the context of
238 -- Couverture, we do not permit XOR, so this will never appear.
240 -- ! indicates NOT applied to the expression.
242 ---------------------------------------------------------------------
243 -- Internal table used to store Source Coverage Obligations (SCOs) --
244 ---------------------------------------------------------------------
246 type Source_Location
is record
247 Line
: Logical_Line_Number
;
251 No_Source_Location
: Source_Location
:= (No_Line_Number
, No_Column_Number
);
253 type SCO_Table_Entry
is record
254 From
: Source_Location
;
255 To
: Source_Location
;
261 package SCO_Table
is new GNAT
.Table
(
262 Table_Component_Type
=> SCO_Table_Entry
,
263 Table_Index_Type
=> Nat
,
264 Table_Low_Bound
=> 1,
265 Table_Initial
=> 500,
266 Table_Increment
=> 300);
268 -- The SCO_Table_Entry values appear as follows:
271 -- C1 = 'S' for entry point, 's' otherwise
272 -- C2 = 't', 's', 'o', 'r', 'i', 'C', 'F', 'R', ' '
273 -- (type/subtype/object/renaming/instantiation/CASE/FOR/RETURN)
274 -- From = starting source location
275 -- To = ending source location
276 -- Last = False for all but the last entry, True for last entry
278 -- Note: successive statements (possibly interspersed with entries of
279 -- other kinds, that are ignored for this purpose), starting with one
280 -- labeled with C1 = 'S', up to and including the first one labeled with
281 -- Last=True, indicate the sequence to be output for a sequence of
282 -- statements on a single CS line.
285 -- C1 = 'I', 'E', 'W', 'X' (if/exit/while/expression)
287 -- From = location of IF/EXIT/WHILE token, No_Source_Location for X
288 -- To = No_Source_Location
292 -- C1 = '!', '^', '&', '|'
294 -- From = location of NOT/XOR/AND/OR token
295 -- To = No_Source_Location
298 -- Element (condition)
300 -- C2 = 'c', 't', or 'f' (condition/true/false)
301 -- From = starting source location
302 -- To = ending source location
303 -- Last = False for all but the last entry, True for last entry
305 -- Note: the sequence starting with a decision, and continuing with
306 -- operators and elements up to and including the first one labeled with
307 -- Last=True, indicate the sequence to be output for a complex decision
308 -- on a single CD decision line.
314 -- This table keeps track of the units and the corresponding starting and
315 -- ending indexes (From, To) in the SCO table. Note that entry zero is
316 -- unused, it is for convenience in calling the sort routine. Thus the
317 -- real lower bound for active entries is 1.
319 type SCO_Unit_Index
is new Int
;
320 -- Used to index values in this table. Values start at 1 and are assigned
321 -- sequentially as entries are constructed.
323 type SCO_Unit_Table_Entry
is record
324 File_Name
: String_Ptr
;
325 -- Pointer to file name in ALI file
328 -- Dependency number in ALI file
331 -- Starting index in SCO_Table of SCO information for this unit
334 -- Ending index in SCO_Table of SCO information for this unit
337 package SCO_Unit_Table
is new GNAT
.Table
(
338 Table_Component_Type
=> SCO_Unit_Table_Entry
,
339 Table_Index_Type
=> SCO_Unit_Index
,
340 Table_Low_Bound
=> 0, -- see note above on sorting
342 Table_Increment
=> 200);
348 procedure Initialize
;
349 -- Reset tables for a new compilation
352 (From
: Source_Location
:= No_Source_Location
;
353 To
: Source_Location
:= No_Source_Location
;
354 C1
: Character := ' ';
355 C2
: Character := ' ';
356 Last
: Boolean := False);
357 -- Adds one entry to SCO table with given field values