← Back to branch summary

~ubuntu-branches/ubuntu/raring/adacontrol/raring

« back to all changes in this revision

Viewing changes to doc/adacontrol_pm.html

  • Committer: Bazaar Package Importer
  • Author(s): Ludovic Brenta
  • Date: 2010-03-13 14:01:37 UTC
  • mfrom: (1.1.5 upstream) (9.1.1 sid)
  • Revision ID: james.westby@ubuntu.com-20100313140137-50ia1bbb5qld97fd
Tags: 1.12~b1-1
http://bugs.debian.org/566061
New upstream beta version.  Really closes: #566061 even on i386.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/adacontrol_pm.html
1
1
<html lang="en">
2
2
<head>
3
 
<title>AdaControl Programmer Manual V1.9r4</title>
 
3
<title>AdaControl Programmer Manual V1.12b1</title>
4
4
<meta http-equiv="Content-Type" content="text/html">
5
 
<meta name="description" content="AdaControl Programmer Manual V1.9r4">
6
 
<meta name="generator" content="makeinfo 4.8">
 
5
<meta name="description" content="AdaControl Programmer Manual V1.12b1">
 
6
<meta name="generator" content="makeinfo 4.13">
7
7
<link title="Top" rel="top" href="#Top">
8
8
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
9
9
<meta http-equiv="Content-Style-Type" content="text/css">
20
20
--></style>
21
21
</head>
22
22
<body>
23
 
<h1 class="settitle">AdaControl Programmer Manual V1.9r4</h1>
 
23
<h1 class="settitle">AdaControl Programmer Manual V1.12b1</h1>
24
24
<div class="node">
25
 
<p><hr>
26
25
<a name="Top"></a>
 
26
<p><hr>
27
27
Next:&nbsp;<a rel="next" accesskey="n" href="#General">General</a>,
28
28
Previous:&nbsp;<a rel="previous" accesskey="p" href="#dir">(dir)</a>,
29
29
Up:&nbsp;<a rel="up" accesskey="u" href="#dir">(dir)</a>
32
32
 
33
33
<h2 class="unnumbered">AdaControl Programmer Manual</h2>
34
34
 
35
 
   <p>Last edited: 28 April 2008
 
35
   <p>Last edited: 2 March 2010
36
36
 
37
37
   <p>This is the AdaControl Programmer Manual. It is intended for those who
38
 
want to add new rules to AdaControl. Reading this manual is not
39
 
necessary to use AdaControl. On the other hand, it is assumed that the
40
 
reader knows how to use AdaControl before thinking of adding new rules.
 
38
want to add new rules to AdaControl, or more generally modify (and
 
39
presumably improve!) AdaControl. Reading this manual is not necessary
 
40
to use AdaControl. On the other hand, it is assumed that the reader
 
41
is familiar with how to use AdaControl.
41
42
 
42
43
<ul class="menu">
43
44
<li><a accesskey="1" href="#General">General</a>
81
82
copyright notice is included unmodified in any copy.
82
83
 
83
84
<div class="node">
84
 
<p><hr>
85
85
<a name="General"></a>
 
86
<p><hr>
86
87
Next:&nbsp;<a rel="next" accesskey="n" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>,
87
88
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Top">Top</a>,
88
89
Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
95
96
AdaControl. Since AdaControl is based on ASIS, this manual assumes
96
97
that the reader has some familiarity with ASIS programming.
97
98
 
98
 
   <p>The AdaControl tool includes several main components. Those that are
 
99
<h3 class="section">1.1 vocabulary</h3>
 
100
 
 
101
<p>Some terms have a precise definition in AdaControl, and will be used
 
102
with that signification in the rest of this manual.
 
103
 
 
104
   <p>A <i>rule</i> is an AdaControl package whose purpose is to recognize
 
105
occurrences of certain constructs in Ada programs. All rules are
 
106
children of  the &ldquo;Rules&rdquo; package. By extension, the term rule is
 
107
also used to designate the check that is performed by the package. A
 
108
rule has a name, and may have parameters.
 
109
 
 
110
   <p>A <i>control</i> defines a check to be performed on some Ada text. A
 
111
control is defined by a rule, and the value of the parameters given to
 
112
the rule.
 
113
 
 
114
   <p>A <i>command</i> is a statement in the command language interpreted by
 
115
AdaControl.
 
116
 
 
117
   <p>A <i>control command</i> is a kind of command that describes a check to
 
118
be performed. A control commmand includes a <i>kind</i> (&ldquo;check&rdquo;, &ldquo;search&rdquo;
 
119
or &ldquo;count&rdquo;, see user's guide), and a control (rule name and parameters).
 
120
 
 
121
   <p>A <i>context</i> is a set of values used by a rule to keep the
 
122
characteristics associated with a control. Those values can, but need
 
123
not necessarily, be the parameters of the control.
 
124
 
 
125
<h3 class="section">1.2 General organization</h3>
 
126
 
 
127
<p>The AdaControl tool includes several main components. Those that are
99
128
relevant for writing new rules are:
100
129
     <ul>
101
130
<li>A general <i>framework</i> that provides services that are necessary to
113
142
itself.
114
143
 
115
144
<div class="node">
116
 
<p><hr>
117
145
<a name="The-framework-and-utilities-packages"></a>
 
146
<p><hr>
118
147
Next:&nbsp;<a rel="next" accesskey="n" href="#Writing-a-new-rule">Writing a new rule</a>,
119
148
Previous:&nbsp;<a rel="previous" accesskey="p" href="#General">General</a>,
120
149
Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
159
188
</ul>
160
189
 
161
190
<div class="node">
162
 
<p><hr>
163
191
<a name="The-package-Adactl_Constants"></a>
164
192
<a name="The-package-Adactl_005fConstants"></a>
 
193
<p><hr>
165
194
Next:&nbsp;<a rel="next" accesskey="n" href="#The-package-Framework">The package Framework</a>,
166
195
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>,
167
196
Up:&nbsp;<a rel="up" accesskey="u" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>
180
209
any reasonable program, but should you hit one of these limits, you
181
210
can safely change them here. No other change is required.
182
211
 
 
212
   <p>If a rule needs to set a fixed dimension to some tables for example,
 
213
it should use the constants defined in this package. If no existing
 
214
constant is appropriate, add a new one to the package, don't define
 
215
dimensioning constants in the rule itself.
 
216
 
183
217
<div class="node">
184
 
<p><hr>
185
218
<a name="The-package-Framework"></a>
 
219
<p><hr>
186
220
Next:&nbsp;<a rel="next" accesskey="n" href="#The-package-Framework_002eRules_005fManager">The package Framework.Rules_Manager</a>,
187
221
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-package-Adactl_005fConstants">The package Adactl_Constants</a>,
188
222
Up:&nbsp;<a rel="up" accesskey="u" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>
205
239
rules:
206
240
     <pre class="example">          search Entities (Blah);
207
241
          Strictly_Forbidden: check entities (Ada.Unchecked_Conversion)
208
 
     </pre>
 
242
</pre>
209
243
     <p>the rule Entities must associate that <code>Blah</code> is the target of a
210
244
search, and that <code>Ada.Unchecked_Deallocation</code> is the target of a
211
245
check with label <code>Strictly_Forbidden</code>. 
212
246
</ul>
213
247
 
214
248
<div class="node">
215
 
<p><hr>
216
249
<a name="The-package-Framework.Rules_Manager"></a>
217
250
<a name="The-package-Framework_002eRules_005fManager"></a>
 
251
<p><hr>
218
252
Next:&nbsp;<a rel="next" accesskey="n" href="#The-package-Framework_002eReports">The package Framework.Reports</a>,
219
253
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-package-Framework">The package Framework</a>,
220
254
Up:&nbsp;<a rel="up" accesskey="u" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>
238
272
currently active.
239
273
 
240
274
<div class="node">
241
 
<p><hr>
242
275
<a name="The-package-Framework.Reports"></a>
243
276
<a name="The-package-Framework_002eReports"></a>
 
277
<p><hr>
244
278
Next:&nbsp;<a rel="next" accesskey="n" href="#The-package-Framework_002eLanguage">The package Framework.Language</a>,
245
279
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-package-Framework_002eRules_005fManager">The package Framework.Rules_Manager</a>,
246
280
Up:&nbsp;<a rel="up" accesskey="u" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>
301
335
&ldquo;Uncheckable&rdquo; to work.
302
336
 
303
337
<div class="node">
304
 
<p><hr>
305
338
<a name="The-package-Framework.Language"></a>
306
339
<a name="The-package-Framework_002eLanguage"></a>
 
340
<p><hr>
307
341
Next:&nbsp;<a rel="next" accesskey="n" href="#The-package-Framework_002eScope_005fManager">The package Framework.Scope_Manager</a>,
308
342
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-package-Framework_002eReports">The package Framework.Reports</a>,
309
343
Up:&nbsp;<a rel="up" accesskey="u" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>
348
382
as implicitely provided by GNAT, does <i>not</i> work).
349
383
 
350
384
<div class="node">
351
 
<p><hr>
352
385
<a name="The-package-Framework.Scope_Manager"></a>
353
386
<a name="The-package-Framework_002eScope_005fManager"></a>
 
387
<p><hr>
354
388
Next:&nbsp;<a rel="next" accesskey="n" href="#The-package-Framework_002ePlugs">The package Framework.Plugs</a>,
355
389
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-package-Framework_002eLanguage">The package Framework.Language</a>,
356
390
Up:&nbsp;<a rel="up" accesskey="u" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>
378
412
   <p>See the package specification for more details.
379
413
 
380
414
<div class="node">
381
 
<p><hr>
382
415
<a name="The-package-Framework.Plugs"></a>
383
416
<a name="The-package-Framework_002ePlugs"></a>
 
417
<p><hr>
384
418
Next:&nbsp;<a rel="next" accesskey="n" href="#The-package-Rules">The package Rules</a>,
385
419
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-package-Framework_002eScope_005fManager">The package Framework.Scope_Manager</a>,
386
420
Up:&nbsp;<a rel="up" accesskey="u" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>
397
431
described in details in <a href="#Plugging_002din-a-new-rule-into-the-framework">Plugging-in a new rule into the framework</a>.
398
432
 
399
433
<div class="node">
400
 
<p><hr>
401
434
<a name="The-package-Rules"></a>
 
435
<p><hr>
402
436
Next:&nbsp;<a rel="next" accesskey="n" href="#The-package-Utilities">The package Utilities</a>,
403
437
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-package-Framework_002ePlugs">The package Framework.Plugs</a>,
404
438
Up:&nbsp;<a rel="up" accesskey="u" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>
414
448
be used for instantiating <code>Traverse_Element</code>in simple cases.
415
449
 
416
450
<div class="node">
417
 
<p><hr>
418
451
<a name="The-package-Utilities"></a>
 
452
<p><hr>
419
453
Next:&nbsp;<a rel="next" accesskey="n" href="#The-package-Thick_005fQueries">The package Thick_Queries</a>,
420
454
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-package-Rules">The package Rules</a>,
421
455
Up:&nbsp;<a rel="up" accesskey="u" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>
469
503
   </ul>
470
504
 
471
505
<div class="node">
472
 
<p><hr>
473
506
<a name="The-package-Thick_Queries"></a>
474
507
<a name="The-package-Thick_005fQueries"></a>
 
508
<p><hr>
475
509
Next:&nbsp;<a rel="next" accesskey="n" href="#The-packages-Linear_005fQueue-and-Binary_005fMap">The packages Linear_Queue and Binary_Map</a>,
476
510
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-package-Utilities">The package Utilities</a>,
477
511
Up:&nbsp;<a rel="up" accesskey="u" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>
486
520
package.
487
521
 
488
522
<div class="node">
489
 
<p><hr>
490
523
<a name="The-packages-Linear_Queue-and-Binary_Map"></a>
491
524
<a name="The-packages-Linear_005fQueue-and-Binary_005fMap"></a>
 
525
<p><hr>
492
526
Next:&nbsp;<a rel="next" accesskey="n" href="#The-package-A4G_005fBugs">The package A4G_Bugs</a>,
493
527
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-package-Thick_005fQueries">The package Thick_Queries</a>,
494
528
Up:&nbsp;<a rel="up" accesskey="u" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>
517
551
   <p>See existing rules for examples of using this package.
518
552
 
519
553
<div class="node">
520
 
<p><hr>
521
554
<a name="The-package-A4G_Bugs"></a>
522
555
<a name="The-package-A4G_005fBugs"></a>
 
556
<p><hr>
523
557
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-packages-Linear_005fQueue-and-Binary_005fMap">The packages Linear_Queue and Binary_Map</a>,
524
558
Up:&nbsp;<a rel="up" accesskey="u" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>
525
559
 
546
580
replacement in <code>A4G_Bugs</code>.
547
581
 
548
582
<div class="node">
549
 
<p><hr>
550
583
<a name="Writing-a-new-rule"></a>
 
584
<p><hr>
551
585
Next:&nbsp;<a rel="next" accesskey="n" href="#Plugging_002din-a-new-rule-into-the-framework">Plugging-in a new rule into the framework</a>,
552
586
Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-framework-and-utilities-packages">The framework and utilities packages</a>,
553
587
Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
907
941
</dl>
908
942
 
909
943
<div class="node">
910
 
<p><hr>
911
944
<a name="Plugging-in-a-new-rule-into-the-framework"></a>
912
945
<a name="Plugging_002din-a-new-rule-into-the-framework"></a>
 
946
<p><hr>
913
947
Next:&nbsp;<a rel="next" accesskey="n" href="#Testing-and-debugging-a-rule">Testing and debugging a rule</a>,
914
948
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Writing-a-new-rule">Writing a new rule</a>,
915
949
Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
925
959
</ul>
926
960
 
927
961
<div class="node">
928
 
<p><hr>
929
962
<a name="Normal-case"></a>
 
963
<p><hr>
930
964
Next:&nbsp;<a rel="next" accesskey="n" href="#Specific-rules">Specific rules</a>,
931
965
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Plugging_002din-a-new-rule-into-the-framework">Plugging-in a new rule into the framework</a>,
932
966
Up:&nbsp;<a rel="up" accesskey="u" href="#Plugging_002din-a-new-rule-into-the-framework">Plugging-in a new rule into the framework</a>
974
1008
 
975
1009
     <p>Ex:
976
1010
     <pre class="example">          <b>with</b> Rules.Pragmas;
977
 
     </pre>
 
1011
</pre>
978
1012
     <li>Add calls to the rule's <code>Process</code> procedure(s) at the appropriate
979
1013
place(s) in the body of the provided procedures. For textual rules,
980
1014
<code>Text_Analysis</code> is the only appropriate place.
989
1023
                   Rules.Pragmas.Process_Pragma (Element);
990
1024
                 ...
991
1025
          <b>end</b> Pre_Procedure;
992
 
     </pre>
 
1026
</pre>
993
1027
     </ol>
994
1028
 
995
1029
   <p>Many alternatives of the big case statement cover a number of
1011
1045
alternatives of the big case statement.
1012
1046
 
1013
1047
<div class="node">
1014
 
<p><hr>
1015
1048
<a name="Specific-rules"></a>
 
1049
<p><hr>
1016
1050
Next:&nbsp;<a rel="next" accesskey="n" href="#User-documentation">User documentation</a>,
1017
1051
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Normal-case">Normal case</a>,
1018
1052
Up:&nbsp;<a rel="up" accesskey="u" href="#Plugging_002din-a-new-rule-into-the-framework">Plugging-in a new rule into the framework</a>
1047
1081
show that it is a specific version.
1048
1082
 
1049
1083
<div class="node">
1050
 
<p><hr>
1051
1084
<a name="User-documentation"></a>
 
1085
<p><hr>
1052
1086
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Specific-rules">Specific rules</a>,
1053
1087
Up:&nbsp;<a rel="up" accesskey="u" href="#Plugging_002din-a-new-rule-into-the-framework">Plugging-in a new rule into the framework</a>
1054
1088
 
1064
1098
you need will be quite straightforward to understand.
1065
1099
 
1066
1100
<div class="node">
1067
 
<p><hr>
1068
1101
<a name="Testing-and-debugging-a-rule"></a>
 
1102
<p><hr>
1069
1103
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Plugging_002din-a-new-rule-into-the-framework">Plugging-in a new rule into the framework</a>,
1070
1104
Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1071
1105
 
1080
1114
</ul>
1081
1115
 
1082
1116
<div class="node">
1083
 
<p><hr>
1084
1117
<a name="Testing"></a>
 
1118
<p><hr>
1085
1119
Next:&nbsp;<a rel="next" accesskey="n" href="#Debugging-aids">Debugging aids</a>,
1086
1120
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Testing-and-debugging-a-rule">Testing and debugging a rule</a>,
1087
1121
Up:&nbsp;<a rel="up" accesskey="u" href="#Testing-and-debugging-a-rule">Testing and debugging a rule</a>
1108
1142
is done currently, and do the same.
1109
1143
 
1110
1144
<div class="node">
1111
 
<p><hr>
1112
1145
<a name="Debugging-aids"></a>
 
1146
<p><hr>
1113
1147
Next:&nbsp;<a rel="next" accesskey="n" href="#Integrating-the-test-in-the-test-suite">Integrating the test in the test suite</a>,
1114
1148
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Testing">Testing</a>,
1115
1149
Up:&nbsp;<a rel="up" accesskey="u" href="#Testing-and-debugging-a-rule">Testing and debugging a rule</a>
1166
1200
instead. See <a href="#The-package-A4G_005fBugs">The package A4G_Bugs</a>.
1167
1201
 
1168
1202
<div class="node">
1169
 
<p><hr>
1170
1203
<a name="Integrating-the-test-in-the-test-suite"></a>
 
1204
<p><hr>
1171
1205
Previous:&nbsp;<a rel="previous" accesskey="p" href="#Debugging-aids">Debugging aids</a>,
1172
1206
Up:&nbsp;<a rel="up" accesskey="u" href="#Testing-and-debugging-a-rule">Testing and debugging a rule</a>
1173
1207