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
55 -- Source coverage obligations are generated on a unit-by-unit basis in the
56 -- ALI file, using lines that start with the identifying character C. These
57 -- lines are generated if the -gnatC switch is set.
61 -- In several places in the SCO lines, Sloc ranges appear. These are used
62 -- to indicate the first and last Sloc of some construct in the tree and
63 -- they have the form:
67 -- Note that SCO's are generated only for generic templates, not for
68 -- generic instances (since only the first are part of the source). So
69 -- we don't need generic instantiation stuff in these line:col items.
73 -- The SCO information follows the cross-reference information, so it
74 -- need not be read by tools like gnatbind, gnatmake etc. The SCO output
75 -- is divided into sections, one section for each unit for which SCO's
76 -- are generated. A SCO section has a header of the form:
78 -- C dependency-number filename
80 -- This header precedes SCO information for the unit identified by
81 -- dependency number and file name. The dependency number is the
82 -- index into the generated D lines and is ones origin (i.e. 2 =
83 -- reference to second generated D line).
85 -- Note that the filename here will reflect the original name if
86 -- a Source_Reference pragma was encountered (since all line number
87 -- references will be with respect to the original file).
89 -- Note: the filename is redundant in that it could be deduced from
90 -- the corresponding D line, but it is convenient at least for human
91 -- reading of the SCO information, and means that the SCO information
92 -- can stand on its own without needing other parts of the ALI file.
96 -- For the purpose of SCO generation, the notion of statement includes
97 -- simple statements and also the following declaration types:
100 -- subtype_declaration
101 -- object_declaration
102 -- renaming_declaration
103 -- generic_instantiation
107 -- These lines correspond to a sequence of one or more statements which
108 -- are always executed in sequence, The first statement may be an entry
109 -- point (e.g. statement after a label), and the last statement may be
110 -- an exit point (e.g. an exit statement), but no other entry or exit
111 -- points may occur within the sequence of statements. The idea is that
112 -- the sequence can be treated as a single unit from a coverage point of
113 -- view, if any of the code for the statement sequence is executed, this
114 -- corresponds to coverage of the entire statement sequence. The form of
115 -- a statement line in the ALI file is:
121 -- An exit point is a statement that causes transfer of control. Examples
122 -- are exit statements, raise statements and return statements. The form
123 -- of an exit point in the ALI file is:
129 -- Decisions represent the most significant section of the SCO lines
131 -- Note: in the following description, logical operator includes the
132 -- short circuited forms (so can be any of AND, OR, XOR, NOT, AND THEN,
135 -- Decisions are either simple or complex. A simple decision is a boolean
136 -- expresssion that occurs in the context of a control structure in the
137 -- source program, including WHILE, IF, EXIT WHEN. Note that a boolean
138 -- expression in any other context, for example, on the right side of an
139 -- assignment, is not considered to be a decision.
141 -- A complex decision is an occurrence of a logical operator which is not
142 -- itself an operand of some other logical operator. If any operand of
143 -- the logical operator is itself a logical operator, this is not a
144 -- separate decision, it is part of the same decision.
146 -- So for example, if we have
148 -- A, B, C, D : Boolean;
149 -- function F (Arg : Boolean) return Boolean);
151 -- A and then (B or else F (C and then D))
153 -- There are two (complex) decisions here:
155 -- 1. X and then (Y or else Z)
157 -- where X = A, Y = B, and Z = F (C and then D)
161 -- For each decision, a decision line is generated with the form:
165 -- Here * is one of the following characters:
167 -- I decision in IF statement or conditional expression
168 -- E decision in EXIT WHEN statement
169 -- W decision in WHILE iteration scheme
170 -- X decision appearing in some other expression context
172 -- The expression is a prefix polish form indicating the structure of
173 -- the decision, including logical operators and short circuit forms.
174 -- The following is a grammar showing the structure of expression:
176 -- expression ::= term (if expr is not logical operator)
177 -- expression ::= & term term (if expr is AND or AND THEN)
178 -- expression ::= | term term (if expr is OR or OR ELSE)
179 -- expression ::= ^ term term (if expr is XOR)
180 -- expression ::= !term (if expr is NOT)
183 -- term ::= expression
185 -- element ::= outcome sloc-range
187 -- outcome is one of the following letters:
193 -- where t/f are used to mark a condition that has been recognized by
194 -- the compiler as always being true or false.
196 -- & indicates either AND or AND THEN connecting two conditions. In the
197 -- context of couverture we only permit AND THEN in the source in any
198 -- case, so & can always be understood to be AND THEN.
200 -- | indicates either OR or OR ELSE connection two conditions. In the
201 -- context of couverture we only permit OR ELSE in the source in any
202 -- case, so | can always be understood to be OR ELSE.
204 -- ^ indicates XOR connecting two conditions. In the context of
205 -- couverture, we do not permit XOR, so this will never appear.
207 -- ! indicates NOT applied to the expression.
209 ---------------------------------------------------------------------
210 -- Internal table used to store Source Coverage Obligations (SCOs) --
211 ---------------------------------------------------------------------
213 type Source_Location is record
214 Line : Logical_Line_Number;
218 No_Source_Location : Source_Location := (No_Line_Number, No_Column_Number);
220 type SCO_Table_Entry is record
221 From : Source_Location;
222 To : Source_Location;
228 package SCO_Table is new GNAT.Table (
229 Table_Component_Type => SCO_Table_Entry,
230 Table_Index_Type => Nat,
231 Table_Low_Bound => 1,
232 Table_Initial => 500,
233 Table_Increment => 300);
235 -- The SCO_Table_Entry values appear as follows:
240 -- From = starting source location
241 -- To = ending source location
247 -- From = starting source location
248 -- To = ending source location
252 -- C1 = 'I', 'E', 'W', 'X' (if/exit/while/expression)
253 -- C2 = 'c', 't', or 'f'
254 -- From = starting source location
255 -- To = ending source location
259 -- C1 = 'I', 'E', 'W', 'X' (if/exit/while/expression)
261 -- From = No_Source_Location
262 -- To = No_Source_Location
266 -- C1 = '!', '^', '&', '|'
268 -- From = No_Source_Location
269 -- To = No_Source_Location
274 -- C2 = 'c', 't', or 'f' (condition/true/false)
275 -- From = starting source location
276 -- To = ending source location
277 -- Last = False for all but the last entry, True for last entry
279 -- Note: the sequence starting with a decision, and continuing with
280 -- operators and elements up to and including the first one labeled with
281 -- Last=True, indicate the sequence to be output for a complex decision
282 -- on a single CD decision line.
288 -- This table keeps track of the units and the corresponding starting and
289 -- ending indexes (From, To) in the SCO table. Note that entry zero is
290 -- unused, it is for convenience in calling the sort routine. Thus the
291 -- real lower bound for active entries is 1.
293 type SCO_Unit_Index is new Int;
294 -- Used to index values in this table. Values start at 1 and are assigned
295 -- sequentially as entries are constructed.
297 type SCO_Unit_Table_Entry is record
298 File_Name : String_Ptr;
299 -- Pointer to file name in ALI file
302 -- Dependency number in ALI file
305 -- Starting index in SCO_Table of SCO information for this unit
308 -- Ending index in SCO_Table of SCO information for this unit
311 package SCO_Unit_Table is new GNAT.Table (
312 Table_Component_Type => SCO_Unit_Table_Entry,
313 Table_Index_Type => SCO_Unit_Index,
314 Table_Low_Bound => 0, -- see note above on sorting
316 Table_Increment => 200);
322 procedure Initialize;
323 -- Reset tables for a new compilation
326 (From : Source_Location := No_Source_Location;
327 To : Source_Location := No_Source_Location;
328 C1 : Character := ' ';
329 C2 : Character := ' ';
330 Last : Boolean := False);
331 -- Adds one entry to SCO table with given field values