1This is adacontrol_ug.info, produced by makeinfo version 6.0 from 2adacontrol_ug.texi. 3 4 5File: adacontrol_ug.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) 6 7AdaControl User Guide 8********************* 9 10Last edited: September 17, 2016 11 12 This is the AdaControl User Guide. It describes how to install and 13use AdaControl. Please refer to the AdaControl Programmer Manual to 14learn how to add new kinds of rules to AdaControl. 15 16* Menu: 17 18* Introduction:: 19* Installation:: 20* Program Usage:: 21* Command language reference:: 22* Rules reference:: 23* Examples of using AdaControl for common programming rules:: 24* Specifying an Ada entity name:: 25* Syntax of regular expressions:: 26* Non upward-compatible changes:: 27 28 AdaControl is Copyright (C) 2005-2015 Eurocontrol/Adalog, except for 29some specific modules that are (C) 2006 Belgocontrol/Adalog, (C) 2006 30CSEE/Adalog, (C) 2006 SAGEM/Adalog, or (C) 2015 Alstom/Adalog. 31AdaControl is free software; you can redistribute it and/or modify it 32under terms of the GNU General Public License as published by the Free 33Software Foundation; either version 2, or (at your option) any later 34version. This unit is distributed in the hope that it will be useful, 35but WITHOUT ANY WARRANTY; without even the implied warranty of 36MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General 37Public License for more details. You should have received a copy of the 38GNU General Public License distributed with this program; see file 39COPYING. If not, write to the Free Software Foundation, 59 Temple Place 40- Suite 330, Boston, MA 02111-1307, USA. 41 42 As a special exception, if other files instantiate generics from this 43program, or if you link units from this program with other files to 44produce an executable, this does not by itself cause the resulting 45executable to be covered by the GNU General Public License. This 46exception does not however invalidate any other reasons why the 47executable file might be covered by the GNU Public License. 48 49 This document is Copyright (C) 2005-2015 Eurocontrol/Adalog. This 50document may be copied, in whole or in part, in any form or by any 51means, as is or with alterations, provided that (1) alterations are 52clearly marked as alterations and (2) this copyright notice is included 53unmodified in any copy. 54 55 56File: adacontrol_ug.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top 57 581 Introduction 59************** 60 61AdaControl is an Ada rules controller. It is used to control that Ada 62software meets the requirements of a number of parameterizable rules. 63It is not intended to supplement checks made by the compiler, but rather 64to search for particular violations of good-practice rules, or to check 65that some rules are obeyed project-wide. AdaControl can also be handy 66to make statistics about certain usages of language features, or simply 67to search for the occurrences of particular constructs; its scope is 68therefore not limited to enforcing programming rules, although it is of 69course one of its main goals. 70 71 AdaControl is a commercial product of Adalog 72(http://www.adalog.fr/adalog2.htm) with professional grade support 73available. Getting support is highly recommended for industrial 74projects. Adacontrol can also be customized or extended to match your 75special needs, please refer to *note Support:: or contact Adalog at 76<info@adalog.fr>. 77 78* Menu: 79 80* Features:: 81* Support:: 82* History:: 83* References:: 84 85 86File: adacontrol_ug.info, Node: Features, Next: Support, Prev: Introduction, Up: Introduction 87 881.1 Features 89============ 90 91AdaControl analyzes a set of Ada units, according to parameterizable 92controls. Controls can be given from the command line, from a file, or 93interactively. There is a wide range of controls available. Some are 94quite simple (although very useful): 95 * Control physical layout of the program (Maximum line length, no use 96 of tabulations...) 97 * Control occurences of special strings in comments (like TBD for "To 98 Be Defined"), with full wildcarding. 99 * Use of features (goto statement, tasking, pointers, variables in 100 package specifications...) 101 * Use of any declared entity, with full overloading resolution 102 Other rules are quite sophisticated: 103 * Control series of "if"..."elsif" that could be replaced by "case" 104 statements 105 * Verify usage of declarations (variables that should be constant, 106 variables read but not written...) 107 * Control declarations that could be moved to a more reduced, 108 internal scope 109 * Limit the call depth of a program (and diagnose recursive 110 subprograms) 111 * Enforce a pattern that guarantees that exceptions are not handled 112 silently 113 * Enforce a pattern for paired calls (like semaphore's "P" and "V") 114 that guarantees that the closing call is always executed, even in 115 presence of exceptions. 116 * Check that there is no aliasing between out parameters 117 * Ensure that no protected operation calls a potentially blocking 118 operation 119 and much, much more... See *note Rules reference:: for the complete 120reference for all possible controls. 121 122 AdaControl is very simple to use. It takes, as parameters, a list of 123units to process and a list of commands that define the controls to 124apply. The complete syntax of the commands is described in chapter 125*note Command language reference::. 126 127 AdaControl produces messages to the standard output, unless 128redirected. Several levels of messages are defined (i.e. error or 129found), depending on the kind of the control (i.e. check or search). 130 131 Rules can be locally disabled for a part of the source code, and 132various options can be passed to the program. 133 134 Ex: 135 136 Given the following package: 137 package Pack is 138 pragma Pure (Pack); 139 ... 140 end Pack; 141 The following command: 142 adactl -l "search pragmas (pure)" pack 143 produces the following result (displayed to standard output): 144 pack.ads:2:4: Found: PRAGMAS: use of pragma Pure 145 146 AdaControl integrates nicely in environments such as GPS (*note 147Running AdaControl from GPS::), AdaGide (*note Running AdaControl from 148AdaGide::), or emacs (*note Control kinds and report messages::). In 149those environments, you can run AdaControl from menus or by just 150clicking on a button! 151 152 153File: adacontrol_ug.info, Node: Support, Next: History, Prev: Features, Up: Introduction 154 1551.2 Support 156=========== 157 1581.2.1 Commercial support 159------------------------ 160 161Adalog provides commercial support for AdaControl. Support includes the 162following benefits: 163 * Help with installation procedures. 164 * Explanations regarding the use of the tool, and help for 165 translating coding standards into AdaControl rules. 166 * Dedicated account into our BT system for priority handling of 167 problem reports. 168 * Correction of problems encountered in the use of AdaControl. 169 Pre-releases versions of AdaControl are provided for each corrected 170 problem. 171 * Access to beta-versions before they are released 172 * Keeping in sync customer's own custom rules with the latest version 173 of AdaControl. 174 * Reduced rate for on-demand development of custom rules. 175 * Priority consideration of enhancement requests. Satisfying 176 enhancement requests is not part of the support contract; however, 177 Adalog is constantly improving AdaControl, and suggestions 178 originating from supported customers are given a high priority in 179 our todo list. 180 181 Adalog cannot correct problems whose origin is due to compiler bugs 182or defects in the implementation of ASIS (contact your compiler provider 183for support on these problems). However, Adalog will do its best effort 184to find workarounds for such problems. 185 186 In addition, Adalog can provide various services: 187 * Custom improvements to AdaControl, including application-specific 188 rules; 189 * consulting services for defining coding standards; 190 * consulting services in all areas related to Ada, real-time, 191 compilation, etc. See Adalog's site 192 (http://www.adalog.fr/adalog2.htm) for details. 193 194 For pricing information about support contract and other services, 195please contact <info@adalog.fr>. 196 1971.2.2 Other support 198------------------- 199 200There is a Wiki for questions about AdaControl at 201<https://sourceforge.net/p/adacontrol/wiki/Home/>. This is the place to 202ask for information, make suggestions, or get help from the community. 203 204 For problem reports, please create a ticket into our BT system at 205<https://sourceforge.net/p/adacontrol/tickets/>. 206 2071.2.3 Your support to us, too! 208------------------------------ 209 210If you enjoy AdaControl, there are several things you can do to help us 211continue and improve this nice project. 212 * Rate it, or even better post a review, on the SourceForge review 213 page (http://sourceforge.net/projects/adacontrol/reviews/) 214 * Click "I use it" from AdaControl's home page 215 (http://www.adalog.fr/adacontrol2.htm). 216 * Rate it on AdaControl's Ohloh page 217 (http://www.ohloh.net/p/11353?ref=sample) 218 * Get a support contract, or encourage your company, your friends, or 219 anybody else to get a support contract! 220 * Provide good ideas, new rules, suggestions for improvements... 221 And remember: developing AdaControl is an expensive effort (according 222to Ohlo's COCOMO model, it is worth 15 man.year of development). We 223need support from our users to keep it running! 224 225 226File: adacontrol_ug.info, Node: History, Next: References, Prev: Support, Up: Introduction 227 2281.3 History 229=========== 230 231The development of AdaControl was initially funded by Eurocontrol 232(<http://www.eurocontrol.int>), which needed a tool to help in verifying 233the million+ lines of code that does Air Traffic Flow Management over 234Europe. Because it was felt that such a tool would benefit the 235community at-large, and that further improvements made by the community 236would benefit Eurocontrol, it was decided to release AdaControl as free 237software. Later, Eurocontrol, Belgocontrol, Alstom, Ansaldo (formerly 238CSEE-Transport), and SAGEM-DS sponsored the development of more rules. 239 240 The requirements for AdaControl were written by Philippe Waroquiers 241(Eurocontrol-Brussels), who also conducted extensive testing of 242AdaControl over the Eurocontrol software. The software was developped 243by Arnaud Lecanu and Jean-Pierre Rosen (Adalog). Rules, improvements, 244etc. were contributed by Pierre-Louis Escouflaire (Adalog), Alain 245Fontaine (ABF consulting), Richard Toy (Eurocontrol-Maastricht), and 246Isidro Ilasa Veloso (GMV). AdaGide support and improvement of icons were 247contributed by Gautier de Montmollin. Emmanuel Masker (Alstom) and 248Yannick Duchene contributed to GPS integration. 249 250 See file 'HISTORY' for a description of the various versions of 251AdaControl, including enhancements of the current version over the 252previous ones. Users of a previous version are warned that the rules 253are not 100% upward-compatible: this is necessary to make the rules more 254consistent and easier to use. However, the incompatibilities are 255straightforward to fix and should affect only a very limited number of 256files. See *note Non upward-compatible changes:: for details. 257 258 259File: adacontrol_ug.info, Node: References, Prev: History, Up: Introduction 260 2611.4 References 262============== 263 264 1. "On the benefits for industrials of sponsoring free software 265 development", Ada User Journal, Volume 26, number 4, december 2005 266 267 <http://www.adalog.fr/publicat/Free-software.pdf> 268 2. "A Comparison of Industrial Coding Rules", Ada User Journal, Volume 269 29, number 4, december 2008 270 271 <http://www.adalog.fr/publicat/coding-rules.pdf> 272 3. "A Methodology for Avoiding Known Compiler Problems Using Static 273 Analysis", proceedings of the ACM SIGAda Annual International 274 Conference (SIGAda 2010) 275 276 <http://dl.acm.org/authorize?316395> 277 278 279File: adacontrol_ug.info, Node: Installation, Next: Program Usage, Prev: Introduction, Up: Top 280 2812 Installation 282************** 283 284Like any ASIS application, AdaControl can be run only if the compiler 285available on the system has exactly the same version as the one used to 286compile AdaControl itself. The executable distribution of AdaControl 287will work only with GNAT version GPL 2015, as distributed by AdaCore. 288If you are using any other version, please use the source distribution 289of AdaControl and compile it as indicated below. 290 291 Another reason for using the source distribution of AdaControl is 292that the user may not be interested in all provided rules. It is very 293easy to remove some rules from AdaControl to increase its speed. *Note 294Customizing AdaControl::. 295 296* Menu: 297 298* Building and installing AdaControl from source:: 299* Installing an executable distribution:: 300* Installing support for AdaGide:: 301 302 303File: adacontrol_ug.info, Node: Building and installing AdaControl from source, Next: Installing an executable distribution, Prev: Installation, Up: Installation 304 3052.1 Building and installing AdaControl from source 306================================================== 307 308This section is only for the source distribution of AdaControl. If you 309downloaded an executable distribution (and are using the latest version 310of GNAT GPL), you may skip to the next section. 311 3122.1.1 Getting the correct version of the sources for your Gnat version 313---------------------------------------------------------------------- 314 315ASIS is continuously evolving to support Ada-2005/2012 features, and so 316is AdaControl. As a consequence, the full set of features of AdaControl 317is supported only with recent versions of Gnat, namely with GnatPRO 3187.2.0 and GnatGPL-2013 (and higher). We refer to these versions as the 319"new Gnat", and we encourage all users to use the latest versions. 320 321 Some user may however need to use an older version of Gnat. We 322provide also a version of AdaControl that is compatible with versions 323GnatPRO 7.0.x and GnatGPL-2011 and older (before some incompatible -but 324necessary- changes in ASIS happened). We refer to these versions as the 325"old Gnat". 326 327 The release whose distribution files start with "adactl" is for the 328new Gnat, and the one whose distribution files start with "adactl-old" 329is for the old-gnat. Both versions provide the same features, except 330that controls related to Ada-2012 (or that depend on new features of 331ASIS) are not available in the old-gnat version. Moreover, the old-gnat 332version is now frozen, and will not receive any new features or 333improvements in the future, unless requested by a supported customer 334(such requests will be honoured as part of the support contract). See 335*note Support:: for information on becoming a supported user. 336 337 Note that intermediate releases of Gnat (GnatPRO-7.1.x, GnatGPL-2012) 338are not fully compatible with either of these distribution. Depending 339on exact version, problems may range from compilation errors to 340incorrect results in some rare (Ada 2012) cases. Compatible sources can 341be obtained from the Git repository of AdaControl on SourceForge 342(<http://adacontrol.sourceforge.net>). We will be happy to help our 343supported customers who must use one of these versions. 344 3452.1.2 Prerequisites 346------------------- 347 348The following software must be installed in order to compile AdaControl 349from source: 350 * A GNAT compiler, any version (but please consider *note Getting the 351 correct version of the sources for your Gnat version:: above). 352 Note that the compiler must also be available on the machine in 353 order to run AdaControl (all ASIS application need the compiler). 354 * ASIS for GNAT 355 * The GNATColl component 356 357 Make sure to have the same version of GNAT and ASIS. The version used 358for running AdaControl must be the same as the one used to compile 359AdaControl itself. 360 3612.1.3 Build and install with installer (Windows) 362------------------------------------------------ 363 364Run the installer ('adactl_src-setup.exe'). This will automatically 365build and install AdaControl, no other installation is necessary. 366 3672.1.4 Build and install with project file 368----------------------------------------- 369 370Simply go to the root directory of the distribution and type: 371 gprbuild build.gpr 372 gprinstall build.gpr 373 You're done! 374 375 Caveat (old gnat only): Due to a bug in some versions, if you are 376using GNATPro 6.1.2 and above, you must set the variable GNAT_FIX to 1; 377i.e. invoke the command as: 378 gprbuild -Pbuild.gpr -XGNAT_FIX=1 379 or if gprbuild is not available for your distribution: 380 gnatmake -Pbuild.gpr -XGNAT_FIX=1 381 3822.1.5 Build and install with Makefile 383------------------------------------- 384 385It is also possible to build and install AdaControl with a regular 386Makefile, although it does little more than run the previous commands. 387This is mainly useful if you want to embed AdaControl into some 388distribution that uses Makefiles, or if you want to change the default 389compilation options (see comments in Makefile for details). 390 391 Go to the root directory of the distribution and type: 392 make build 393 make install 394 395 It is also possible to delete object files and do other actions with 396this "Makefile", run the following command to get more information: 397 make help 398 399 NOTE: Building AdaControl needs the "make" command provide with GNAT; 400it works both with WIN32 shell and UNIX shell. 401 4022.1.6 Manual installation 403------------------------- 404 405Automatic install will place AdaControl's files in standard locations, 406in your Gnat installation tree. You can skip this section unless you 407want different locations (for example, if GPS is not installed in the 408Gnat tree). 409 410 All you need to run AdaControl is the executable named 'adactl' under 411Linux or 'adactl.exe' under Windows. In addition, 'pfni' (or 'pfni.exe' 412under Windows) is a convenient utility, required by the GPS support. 413*Note pfni::. Copy these executables (found in the root directory of 414the distribution) to any convenient directory on your path. 415 416 To also add AdaControl support to GPS, copy the file 417'GPS/adacontrol.xml' into the '<GNAT_dir>/share/gprconfig' directory; 418copy all other files from the 'GPS' directory into the 419'<GPS_dir>/share/gps/plug-ins' directory. Copy also HTML files from the 420'doc' directory into the '<GPS_dir>/share/doc/gps/html' to access 421AdaControl's guides from the "Help" menu of GPS. 422 4232.1.7 Build with a compiler other than GNAT 424------------------------------------------- 425 426It should be possible to compile AdaControl with other compilers than 427GNAT, although we didn't have an opportunity to try it. If you have 428another compiler that supports ASIS, note that it may require some easy 429changes in the package 'Implementation_Options' to give proper 430parameters to the 'Associate' procedure of ASIS. Rules that need string 431pattern matchings need the package 'Gnat.Regpat'. If you compile 432AdaControl with another compiler, you can either port 'Gnat.Regpat' to 433your system, or use a (limited) portable implementation of a simple 434pattern matching (package 'String_Matching_Portable'). Edit the file 435'string_matching.ads' and change it as indicated in the comments. No 436other change should be necessary. 437 438 Alternatively, if you are using another compiler, you can try and 439compile your program with GNAT just to be able to run AdaControl. 440However, compilers often differ in their support of representation 441clauses, which can cause your program to be rejected by GNAT. In that 442case, we provide a sed script to comment-out all representation clauses; 443this can be sufficient to allow you to use AdaControl. *Note 444unrepr.sed::. 445 4462.1.8 Testing AdaControl 447------------------------ 448 449Testing AdaControl needs a UNIX shell, so it works only with UNIX 450systems. However, it is possible to run the tests on a WIN32 system by 451using an UNIX-like shell for WIN32, such as those provided by CYGWIN or 452MSYS. To run the tests, enter the following commands: 453 cd test 454 ./run.sh 455 456 All tests must report PASSED. If they don't, it may be due to one of 457the following issues: 458 * You are using an old version of GNAT. AdaControl runs without any 459 known problem (and it has been checked against the whole ACATS) 460 only with the latest GNATPro and GNATGPL versions; earlier versions 461 are known to have bugs and unimplemented features that will not 462 allow AdaControl to run correctly in some cases. We strongly 463 recommend to always use the most recent version of GNAT. 464 * You run an old-gnat version of AdaControl with GNATPro (6.1.2 and 465 above) and you forgot to specify the "-XGNAT_FIX=1" option. *Note 466 Build and install with project file::. 467 * It may happen that the test 'tfw_help' reports "FAILED" because it 468 includes a check on the version of AdaControl, and the version 469 string refers to a different version of Gnat. The only difference 470 (you can see it by typing "d" when prompted for checking the 471 differences) should be the name of the compiler. 472 4732.1.9 Customizing AdaControl 474---------------------------- 475 476If there are some rules that you are not interested in, it is very easy 477to remove them from AdaControl: 478 1. In the 'src' directory, edit the file 'framework-plugs.adb'. There 479 is a 'with' clause for each rule (children of package 'Rules'). 480 Comment out the ones you don't want. 481 2. Recompile 'framework-plugs.adb'. There will be error messages 482 about unknown procedure calls. Comment out the corresponding 483 lines. 484 3. Compile AdaControl normally. That's all! 485 486 It is also possible to add new rules to AdaControl. If your favorite 487rules are not currently supported, you have several options: 488 1. If you have some funding available, please contact info@adalog.fr. 489 We'll be happy to make an offer to customize AdaControl to your 490 needs. 491 2. If you don't have funding, but have some knowledge of ASIS 492 programming, you can add the rule yourself. We have made every 493 effort to make this as simple as possible. Please refer to the 494 AdaControl programmer's manual for details. If you do so, please 495 send your rules to rosen@adalog.fr, and we'll be happy to integrate 496 them in the general release of AdaControl to make them available to 497 everybody. 498 3. If you have good ideas, but don't feel like implementing them 499 yourself (nor financing them), please send a note to 500 rosen@adalog.fr. We will eventually incorporate all good 501 suggestions, but we can't of course commit to any dead-line in that 502 case. 503 504 505File: adacontrol_ug.info, Node: Installing an executable distribution, Next: Installing support for AdaGide, Prev: Building and installing AdaControl from source, Up: Installation 506 5072.2 Installing an executable distribution 508========================================= 509 510If you downloaded the Windows installer executable version of 511AdaControl, simply run 'adactl_exe-setup.exe'. This will install all 512the files in the recommended locations (as has been done with the 513Windows installer source version), including GPS support if you have GPS 514installed and/or AdaGide support if you have AdaGide installed. 515 516 Otherwise, go to the root directory of the installation and type: 517 gprinstall build.gpr 518 519 This will install the executables and the GPS support in the standard 520locations (the Gnat directory). However, if you are using AdaGide, the 521support will have to be installed manually as explained below. 522 523 524File: adacontrol_ug.info, Node: Installing support for AdaGide, Prev: Installing an executable distribution, Up: Installation 525 5262.3 Installing support for AdaGide 527================================== 528 529To add AdaControl support to AdaGide, copy the file 'AdaControl.tdf' 530from the 'AdaGide' directory of the distribution into AdaGide's root 531directory. Note that AdaControl support requires AdaGide version 7.42 532or above. 533 534 535File: adacontrol_ug.info, Node: Program Usage, Next: Command language reference, Prev: Installation, Up: Top 536 5373 Program Usage 538*************** 539 540AdaControl is a command-line program, i.e. it is normally called 541directly from the system shell. Options are introduced by a "-" 542followed by a letter and can be grouped as usual. Some options take the 543following word on the command line as a value; such options must appear 544last in a group of options. Parameters are words on the command line 545that stand by themselves. Options and parameters can be given in any 546order. 547 548 The syntax for invoking AdaControl in regular mode is: 549 adactl [-deEirsTuvwx] 550 [-p <project file>] [-f <rules file>] [-l <rules list>] 551 [-o <output file>] [-t <trace file>] [-F <format>] 552 [-S <statistics level>] [-m <warning limit>] [-M <message limit>] 553 {<unit>[+|-<unit>]|[@]<file>} [-- <ASIS options>] 554 555 AdaControl can process Ada-2012 as well as Ada-95 programs, even if 556there are currently few Ada-2012 related controls - but we hope to 557improve that situation in the near future. 558 559 If you are using Ada-2005 (or Ada-2012) features, make sure that GNAT 560is set up for Ada-2005/2012 (this is the default for GNAT-GPL). Due to 561technical reasons, the -gnat05 option cannot be passed to the compiler 562in "compile on the fly" mode, but you can do any of the following: 563 * have a "gnat.adc" file in the current directory that contains a 564 'pragma Ada_05;' (or 'pragma Ada_12;') 565 * put a 'pragma Ada_05' (or 'pragma Ada_12;') on top of every 566 compilation unit that uses Ada-2005/2012 features; 567 * generate the tree files manually (*note Generating tree files 568 manually::) with the "-gnat05" (or "-gnat12)") option. Note that 569 this allows you to pass any other GNAT option as well. 570 571 Note that if your program is pure Ada-95 and you are using a version 572of GNAT where Ada-2005 is the default (especially GNAT-GPL), and in the 573rare cases where your program would not compile in Ada-2005 mode 574(notably if you have a function that returns a task type), you can force 575Ada-95 the same way by using 'pragma Ada_95' instead. 576 577* Menu: 578 579* Command line parameters and options:: 580* Return codes:: 581* Environment variable and default settings:: 582* Interactive mode:: 583* Other execution modes:: 584* Running AdaControl from GPS:: 585* Running AdaControl from AdaGide:: 586* Helpful utilities:: 587* Optimizing Adacontrol:: 588* In case of trouble:: 589 590 591File: adacontrol_ug.info, Node: Command line parameters and options, Next: Return codes, Prev: Program Usage, Up: Program Usage 592 5933.1 Command line parameters and options 594======================================= 595 596* Menu: 597 598* Input units:: 599* Commands:: 600* Output file:: 601* Output format:: 602* Output limits:: 603* Project files:: 604* Local disabling control:: 605* Verbose and debug mode:: 606* Treatment of warnings:: 607* Exit on error:: 608* ASIS options:: 609 610 611File: adacontrol_ug.info, Node: Input units, Next: Commands, Prev: Command line parameters and options, Up: Command line parameters and options 612 6133.1.1 Input units 614----------------- 615 616Units to be processed are given as parameters on the command line. Note 617that they are Ada _compilation unit_ names, not _file names_: case is 618not significant, and there should be no extension! Child units are 619allowed following normal Ada naming rules: 'Parent.Child', but be aware 620that specifying a child unit will automatically include its parent unit 621in the analysis. Subunits are processed during the analysis of the 622including unit; there is therefore no need to specify subunits 623explicitely. If you do specify a subunit explicitly, it will result in 624the whole enclosing unit being analyzed. 625 626 However, as a convenience to the user, units can be specified as file 627names, provided they follow the default GNAT naming convention. More 628precisely, if a parameter ends in ".ads" or ".adb", the unit name is 629extracted from it (and all "-" in the name are substituted with "."). 630File names can include a path; in this case, the path is automatically 631added to the list of directories searched ("-I" ASIS option). The file 632notation is convenient to process all units in a directory, as in the 633following example: 634 adactl -f my_rules.aru *.adb 635 636 In the unlikely case where you have a child unit called 'Ads' or 637'Adb', use the "-u" option to force interpretation of all parameters as 638unit names. 639 640 By default, both the specification and body of the unit are 641processed; however, it is possible to specify processing of the 642specification only by providing the "-s" option. If only file names are 643given, the "-s" option is assumed if all files are specifications 644(".ads" files). It is not possible to specify processing of bodies 645only, since rules dealing with visibility would not work. 646 647 The "-r" option tells AdaControl to process (recursively) all user 648units that the specified units depend on (including parent units if the 649unit is a child unit or a subunit). Predefined Ada units and units 650belonging to the compiler's run-time library are never processed. 651 652 Ex: 653 adactl -r -f my_rules.aru my_main 654 will process 'my_main' and all units that 'my_main' depends on. If 655'my_main' is the main procedure, this means that the whole program will 656be processed. 657 658 If both options "-r" and "-s" are given, then AdaControl will process 659all units given on the command line, plus (recursively) the 660specifications (but not the bodies) of all units that the given units 661depend on. In short, it will process the minimal transitive closure of 662all compilation units that are necessary to compile the units given on 663the command line. 664 665 It is possible to specify more than one unit (not file) to process in 666a parameter by separating the names with "+". Conversely, it is 667possible to specify units that are not to be processed, separated by 668"-". When a unit is subtracted from the unit list, it is never 669processed even if it is included via the recursive option, and all its 670child and separate units are also excluded. This is convenient to avoid 671processing reusable components, that are not part of a project. For 672example, if you want to run AdaControl on itself, you should use the 673following command: 674 adactl -f my_rules_file.aru -r adactl-asis-a4g 675 This applies the rules from the file 'my_rules_files.aru' to 676AdaControl itself, but not to units that are part of ASIS (units 'Asis', 677'A4G', and their children) that would be found by the "-r" (recursive) 678option otherwise. 679 680 Alternatively, it is possible to provide units indirectly with a 681parameter consisting of an "@" followed by the name of a file. This 682file must contain a list of unit names (not files), one on each line. 683Only the first "word" of the line is considered, i.e. everything after 684the first blank is ignored. This can be useful to annotate unit names. 685All units whose names are given in the file will be processed. If a 686name in the file starts with "@", it will also be treated as an indirect 687file (i.e. the same process will be invoked recursively). If a line in 688the file starts with "#" or "--", it is ignored. This can be useful to 689temporarily disable the processing of some files or to add comments. 690 691 Ex: 692 adactl -f my_rules.aru @unit_file.txt 693 694 695File: adacontrol_ug.info, Node: Commands, Next: Output file, Prev: Input units, Up: Command line parameters and options 696 6973.1.2 Commands 698-------------- 699 700Commands specify which processing AdaControl should apply to units. See 701*note Command language reference:: for a detailed description of all 702commands. 703 704 Commands can be given directly on the command line with the "-l" 705option. A commands list must be quoted with """. 706 707 Ex: 708 adactl pack.ads proc.adb -l "check instantiations (My_Generic);" 709 It is possible to pass several commands separated by ";", but as a 710convenience to the user, the last ";" may be omitted. 711 712 Commands can also be read from a file, whose name is given after the 713"-f" option (the "'.aru'" extension is taken by default). As a special 714case, if the file name is "-", commands are read from the standard 715input. This is intended to allow AdaControl to be pipelined behind 716something that generates commands; if you want to type commands directly 717to AdaControl, the interactive mode is more appropriate. *Note 718Interactive mode::. 719 720 Ex: 721 adactl -f my_rules.aru proc.adb 722 723 Note that the "-l" and "-f" options are not exclusive: if both are 724specified, the commands to be performed include those in the file 725(first) and then those given on the command line. 726 727 728File: adacontrol_ug.info, Node: Output file, Next: Output format, Prev: Commands, Up: Command line parameters and options 729 7303.1.3 Output file 731----------------- 732 733Messages produced by controls are output to the output file; by default, 734it is the standard output, but it can be changed by specifying the "-o" 735option. 736 737 Ex: 738 adactl -f my_rules.aru -o my_output.txt proc.adb 739 If the output file exists, new messages are appended to it. This 740allows running AdaControl under several directories that make up the 741project, and gathering the results in a single file. However, if the 742"-w" option is given, AdaControl overwrites the output file if it 743exists. 744 745 All other messages, including syntax error messages, units processed 746(in verbose mode), and possible internal error mesages from AdaControl 747itself are output to the standard error file. 748 749 750File: adacontrol_ug.info, Node: Output format, Next: Output limits, Prev: Output file, Up: Command line parameters and options 751 7523.1.4 Output format 753------------------- 754 755The "-F" option selects the output format. It must be followed by 756"Gnat", "Gnat_Short", "CSV", "CSV_Short", "Source", "Source_Short", or 757"None" (case insensitive). By default, the output is in "Gnat" format. 758See *note Control kinds and report messages:: for details. 759 760 The "-S" option selects which statistics are output after each run. 761It must be followed by a value in the range 0..3. See *note Control 762kinds and report messages:: for details on the various statistics 763levels. 764 765 The "-T" option prints a summary of timing at the end of each run. 766This indicates how long (in real-time seconds) was spent in processing 767each rule. 768 769 Ex: 770 adactl -F CSV -S 2 -f my_rules.aru -o my_output.csv proc.adb 771 772 773File: adacontrol_ug.info, Node: Output limits, Next: Project files, Prev: Output format, Up: Command line parameters and options 774 7753.1.5 Output limits 776------------------- 777 778The "-m" and "-M" options are used to limit the output of AdaControl. 779These options are followed by an integer value that specifies the 780maximum number of error messages ("-m") or warning and error messages 781("-M"). If the value is omitted, a previous limitation (comming for 782example from a command file) is cancelled. 783 784 If the indicated number of messages is exceeded during a run, 785AdaControl stops immediately. 786 787 788File: adacontrol_ug.info, Node: Project files, Next: Local disabling control, Prev: Output limits, Up: Command line parameters and options 789 7903.1.6 Project files 791------------------- 792 793Starting with version 1.18, AdaControl supports GNAT project files 794(".gpr"). The "-p" option is used to provide the name of a project 795file; Ada units to analyze will be searched in all "source_dirs" 796specified in the project file or one of the projects it depends on 797(directly or indirectly). 798 799 Ex: 800 adactl -f my_rules.aru -p proj.gpr proc.adb 801 802 Alternatively, an old emacs project file (the file with a ".adp" 803extension used by the Ada mode of Emacs and older versions of 804AdaControl) can also be specified with the " -p" option. AdaControl 805will consider all the directories mentioned in "src_dir" lines from the 806project file. 807 808 809File: adacontrol_ug.info, Node: Local disabling control, Next: Verbose and debug mode, Prev: Project files, Up: Command line parameters and options 810 8113.1.7 Local disabling control 812----------------------------- 813 814The "-i" option tells AdaControl to ignore disabling markers in Ada 815source code (*note Disabling controls::); i.e. all controls will be 816performed, regardless of the presence of disabling markers. This is 817equivalent to the command "'set ignore ON;'". Note that if you have 818many messages, setting this option can speed-up AdaControl considerably. 819It is therefore advisable to always set this option when you know that 820there is no disabling marker in your source code. 821 822 The "-j" option tells AdaControl to invert the meaning of disabling 823markers, i.e. only messages marked as disabled will be printed. This 824is useful to check which messages have been disabled. This is 825equivalent to the command "'set ignore INVERTED;'". 826 827 828File: adacontrol_ug.info, Node: Verbose and debug mode, Next: Treatment of warnings, Prev: Local disabling control, Up: Command line parameters and options 829 8303.1.8 Verbose and debug mode 831---------------------------- 832 833In the default mode, AdaControl displays only messages from triggered 834controls. It is possible to get more information with the verbose 835option ("-v"). In this mode, AdaControl displays a a progress indicator 836and unit names as they are processed, and its global execution time when 837it finishes. Note that the progress indicator includes an indication of 838the run number if there are more than one "go" command. 839 840 The "-d" option enables debug mode. This mode provides more 841information in case of an internal program error, and is of little 842interest for the casual user. Note that if you hit Ctrl-C in debug 843mode, AdaControl aborts with a message telling the currently active rule 844and module. This can be useful if you suspect AdaControl to be stuck in 845an infinite loop. 846 847 In debug mode, AdaControl may also, in rare occasions (and only with 848some versions of GNAT), display ASIS "bug boxes"; this does not mean 849that something went wrong with the program, but simply that an ASIS 850failure was properly recovered by AdaControl. 851 852 Output of the messages printed by the "-d" option can be directed to 853a "trace" file (instead of being printed to the standard error file). 854This is done by the "-t" option, which must be followed by the file 855name. If the trace file exists, new messages are appended to it. 856 857 858File: adacontrol_ug.info, Node: Treatment of warnings, Next: Exit on error, Prev: Verbose and debug mode, Up: Command line parameters and options 859 8603.1.9 Treatment of warnings 861--------------------------- 862 863The "-e" option tells AdaControl to treat warnings as errors, i.e. to 864report a return code of 1 even if only "search" controls were triggered. 865*Note Return codes::. It does not change the messages however. 866 867 Conversely, the "-E" option tells AdaControl to not report warnings 868at all, i.e. only errors are reported. However, if you ask for 869statistics, the number of warning messages is still counted. *Note 870Control kinds and report messages::. 871 872 873File: adacontrol_ug.info, Node: Exit on error, Next: ASIS options, Prev: Treatment of warnings, Up: Command line parameters and options 874 8753.1.10 Exit on error 876-------------------- 877 878If an internal error is encountered during the processing of a unit, 879AdaControl will do its best effort to recover and to continue to process 880other units. However, if the "-x" option is given, AdaControl will stop 881on the first error encountered. This option is mainly useful if you 882want to debug AdaControl itself (or your own rules). *Note In case of 883trouble::. 884 885 Ex: 886 adactl -x -f my_rules.aru proc.adb 887 888 889File: adacontrol_ug.info, Node: ASIS options, Prev: Exit on error, Up: Command line parameters and options 890 8913.1.11 ASIS options 892------------------- 893 894Everything that appears on the command line after "--" will be treated 895as an ASIS option, as described in the ASIS user manual. 896 897 Casual users don't need to care about ASIS options, except in one 898case: if you are running AdaControl from the command line (not from 899GPS), and if the units that you are processing reference other units 900whose source is not in the same directory, AdaControl needs to know how 901to access these units (as GNAT would). This can be done either by using 902a project file with the "-p" option (see *note Project files::), by 903putting the appropriate directories into the ADA_INCLUDE_PATH 904environment variable, or by passing "-I" options to ASIS. 905 906 It is possible to pass one or several "-I" options to ASIS, to 907provide other directories where sources can be found. The syntax is the 908same as the "-I" option for GNAT. 909 910 Other ASIS options, like the "-Cx" and/or "-Fx" options, can be 911specified. Most users can ignore this feature; however, specifying 912these options can improve the processing time of big projects. *Note 913Optimizing Adacontrol::. 914 915 916File: adacontrol_ug.info, Node: Return codes, Next: Environment variable and default settings, Prev: Command line parameters and options, Up: Program Usage 917 9183.2 Return codes 919================ 920 921In order to ease the automation of controlling programs with shell 922scripts, AdaControl returns various error codes depending on how 923successful it was. Values returned are: 924 * 0: At most "search" controls (i.e. warnings) were triggered (no 925 control at all with "-e" option) 926 * 1: At least one "check" control (i.e. error) was triggered (or at 927 least one "search" or "check" control with "-e" option) 928 * 2: AdaControl was not run due to a syntax error in the rules or in 929 the specification of units. 930 * 10: There was an internal failure of AdaControl. 931 932 933File: adacontrol_ug.info, Node: Environment variable and default settings, Next: Interactive mode, Prev: Return codes, Up: Program Usage 934 9353.3 Environment variable and default settings 936============================================= 937 938If the environment variable "ADACTLINI" is set, its content is taken as 939a set of commands (separated by semi-colons) that are executed before 940any other command. Although any command can be specified, this is 941intended to allow changing default settings with "set" commands. *Note 942Set command::. 943 944 For example, you can set ADACTLINI to "set format Gnat_Short" if you 945prefer having you messages in short format rather than the (default) 946long format. 947 948 949File: adacontrol_ug.info, Node: Interactive mode, Next: Other execution modes, Prev: Environment variable and default settings, Up: Program Usage 950 9513.4 Interactive mode 952==================== 953 954The "-I" option tells AdaControl to operate interactively. In this 955mode, commands specified with "-l" or "-f" options are first processed, 956then AdaControl prompts for commands on the terminal. Note that the 957"quit" command (*note Quit command::) is used to terminate AdaControl. 958 959 The syntax of commands run interactively is exactly the same as the 960one used for files; especially, each command must be terminated with a 961";". Note that the prompt ("Command:") becomes ".......:" when 962AdaControl requires more input because a command is not completely 963given, and especially if you forget the final ";". 964 965 As with files, it is possible to give several commands on a single 966line in interactive mode. If a command contains syntax errors, all "go" 967commands (*note Go command::) on the same line are temporarily disabled. 968Other commands that do not have errors are normally processed however. 969 970 The interactive mode is useful when you want to do some analysis of 971your code, but don't know beforehand what you want to control. Since 972the ASIS context is open only once when the program is loaded, queries 973will be much faster than running AdaControl entirely with a new query 974given in a "-l" option each time. It is also useful to experiment with 975AdaControl, and to check interactively commands before putting them into 976a file. 977 978 979File: adacontrol_ug.info, Node: Other execution modes, Next: Running AdaControl from GPS, Prev: Interactive mode, Up: Program Usage 980 9813.5 Other execution modes 982========================= 983 984In addition to normal usage, AdaControl features special options to ease 985its use; no Ada unit is analyzed when using these options. 986 987* Menu: 988 989* Getting help:: 990* Checking commands syntax:: 991* Generating a units list:: 992 993 994File: adacontrol_ug.info, Node: Getting help, Next: Checking commands syntax, Prev: Other execution modes, Up: Other execution modes 995 9963.5.1 Getting help 997------------------ 998 999The "-h" option provides help about Adacontrol usage. If the "-h" 1000option is given, no other option is analyzed and no further processing 1001happens. 1002 1003 Syntax: 1004 adactl -h [<keyword> | <rule name> | variables ["<pattern>"] ...] 1005 <keyword> ::= all | commands | license | list | options | rules | version 1006 1007 The "-h" option without parameter displays a help message about usage 1008of the AdaControl program, the various options, and the rule names. 1009 1010 Otherwise, the "-h" must be followed by one or several keywords or 1011rule names (case irrelevant); its effect is: 1012 * <rule name>: if <rule name> is exactly the name of rule, display 1013 the help message for the indicated rule. Otherwise, <rule name> is 1014 interpreted as a pattern, and help messages for all rules that 1015 match the pattern is displayed. Patterns are given using the full 1016 Regexp syntax. *note Syntax of regular expressions:: for details. 1017 * "variables" lists the values of all variables whose name matches 1018 <pattern>, or all variables if there is no <pattern>. Patterns are 1019 given using the full Regexp syntax. *note Syntax of regular 1020 expressions:: for details. 1021 * "all": display the help message for all rules. 1022 * "commands": display a summary of all commands 1023 * "license": display the license information 1024 * "list": display the names of all rules (note that "rules" also 1025 displays the list of rules, in a prettier format; the "list" option 1026 is mainly useful for the integration of AdaControl into GPS). 1027 * "options": display help about the command-line options 1028 * "rules": display the names of all rules. 1029 * "version": display AdaControl and ASIS implementation version 1030 numbers. 1031 1032 Ex: 1033 adactl -h pragmas Unnecessary_Use_Clause 1034 adactl -h all 1035 adactl -h version license 1036 adactl -h stat 1037 Note in the last example that "stat" is not the name of a rule; it is 1038therefore interpreted as a pattern, and help will be displayed for all 1039rules that include the string "stat" in their name. This can be very 1040convenient to retrieve the name of a rule if you don't remember exactly 1041how it is spelled. 1042 1043 1044File: adacontrol_ug.info, Node: Checking commands syntax, Next: Generating a units list, Prev: Getting help, Up: Other execution modes 1045 10463.5.2 Checking commands syntax 1047------------------------------ 1048 1049The "-C" option is used to check syntax of commands without executing 1050any control. 1051 1052 Syntax: 1053 adactl -C [-dv] [-f <rules file>] [-l <rules list>] 1054 1055 In this mode, AdaControl simply checks the syntax of the commands 1056provided with the "-l" option, or of the commands provided in the file 1057named by the "-f" option (at least one of these options must be 1058provided). No other processing will happen. 1059 1060 AdaControl will exit with a return code of 0 if the syntax is 1061correct, and 2 if any errors are found. A confirming message that no 1062errors were found is output if the "-v" option is given. 1063 1064 This option is especially useful when you have modified a rules file, 1065before trying it on many units. The way AdaControl works, it must open 1066the ASIS context (a lengthy operation) before analyzing the rules. This 1067option can therefore save a lot of time if the rules file contains 1068errors. 1069 1070 1071File: adacontrol_ug.info, Node: Generating a units list, Prev: Checking commands syntax, Up: Other execution modes 1072 10733.5.3 Generating a units list 1074----------------------------- 1075 1076The "-D" options produces a list of units that can be reused as an 1077indirect file in later runs. 1078 1079 Syntax: 1080 adactl -D [-rsvw] [-o <output file>] [-p <project file>] 1081 {<unit>[+|-<unit>]|[@]<file>} [-- <ASIS options>] 1082 In this mode, AdaControl outputs the list of units that would be 1083processed. It is especially useful when used with the "-r" option and 1084given the main unit name, since it will then generate the whole 1085dependencies list (hence the name "D"), i.e. the list of units that are 1086part of the program. However, if -D is used with -s, the list includes 1087only transitive dependencies from the specifications of required units 1088(but not from their bodies). This is the list of all units required to 1089compile the given units. 1090 1091 The list can be directed to a file with the "-o" option (if the file 1092exists, it won't be overwritten unless the "-w" option is specified). 1093This file can then be used in an indirect list of units. *Note Input 1094units::. Note that it is more efficient to create the list of units 1095once and then use the indirect file than to specify all applicable units 1096or use the "-r" option each time AdaControl is run. 1097 10983.5.3.1 Limitation 1099.................. 1100 1101If you use the "-Drs" option to generate the minimum set of required 1102units to compile the given unit, note that some units may still be 1103missing when the compiler requires the presence of a body due to 1104inlining of subprograms or generic instantiations. These units depend 1105on the compiler and cannot be computed from the text of the program 1106alone. 1107 1108 1109File: adacontrol_ug.info, Node: Running AdaControl from GPS, Next: Running AdaControl from AdaGide, Prev: Other execution modes, Up: Program Usage 1110 11113.6 Running AdaControl from GPS 1112=============================== 1113 1114AdaControl integrates nicely into GPS, making it even easier to use. It 1115can be launched from menu commands, and parameters can be set like any 1116other GPS project parameters. When run from within GPS, AdaControl will 1117automatically retrieve all needed directories from the current GPS 1118project. 1119 1120 After running AdaControl, the "locations" panel will open, and you 1121can retrieve the locations of errors from there, just like with a 1122regular compilation. Errors will be marked in red in the source, 1123warning will be marked orange, and you will have corresponding marks 1124showing the places of errors and warnings in the speedbar. Note that 1125AdaControl errors appear under the "AdaControl" category, but if there 1126were compilation errors, they will appear under the "Compilation" 1127category. Final counts from "count" control kinds will appear under the 1128"Counts summary" category, and statistics under the "Statistics" 1129category. 1130 1131* Menu: 1132 1133* The AdaControl menu and buttons:: 1134* Contextual menu:: 1135* AdaControl switches:: 1136* AdaControl preferences:: 1137* AdaControl language:: 1138* AdaControl help:: 1139* Caveat:: 1140 1141 1142File: adacontrol_ug.info, Node: The AdaControl menu and buttons, Next: Contextual menu, Prev: Running AdaControl from GPS, Up: Running AdaControl from GPS 1143 11443.6.1 The AdaControl menu and buttons 1145------------------------------------- 1146 1147GPS now features an "AdaControl" menu, with several submenus: 1148 * "Control Current File (rules file)" runs AdaControl on the 1149 currently edited file, with rules taken from the current rules 1150 file; this menu is greyed-out if no rules file is defined, if no 1151 file window is currently active, or if the associated language is 1152 not "Ada". The name of the rules file can be set from the 1153 "Library" tab from the "Project/Edit Project Properties" menu. 1154 * "Control Root Project (rules file)" runs AdaControl on all units 1155 that are part of the root project, with rules taken from the 1156 current rules file; this menu is greyed-out if no rules file is 1157 defined. The name of the rules file can be set from the "Library" 1158 tab from the "Project/Edit Project Properties" menu. 1159 * "Control Units from List (rules file)" runs AdaControls on units 1160 given in a indirect file, with rules taken from the current rules 1161 file. This menu is greyed-out if no rules file is defined or if no 1162 indirect file is defined. The name of the rules file and of the 1163 indirect file can be set from the "Library" tab from the 1164 "Project/Edit Project Properties" menu. 1165 * "Control Current File (interactive)" runs AdaControl on the 1166 currently edited file, with a rule asked interactively from a 1167 pop-up; this menu is greyed-out if no file window is currently 1168 active, or if the associated language is not "Ada". 1169 * "Control Root Project (interactive)" runs AdaControl on all units 1170 that are part of the root project, with a rule asked interactively 1171 from a pop-up. 1172 * "Control Units from List (interactive)" runs AdaControls on units 1173 given in a indirect file, with a rule asked interactively from a 1174 pop-up. This menu is greyed-out if no indirect file is defined. 1175 The name of the indirect file can be set from the "Library" tab 1176 from the "Project/Edit Project Properties" menu. 1177 * "Check Rules File" checks the syntax of the current rules file. 1178 This menu is deactivated if the current window does not contain an 1179 AdaControl rules file. 1180 * "Open Rules File" opens the rules file. This menu is deactivated 1181 if there is no current rules file defined. 1182 * "Open Units File" opens the units file. This menu is deactivated 1183 if there is no current units file defined. 1184 * "Create units file" creates a text file containing all units (not 1185 files) names from the current root project. This file is 1186 appropriate as an indirect file for the "... from list" commands. 1187 * "Create .adp project" creates an Emacs-style project file from the 1188 current GPS project. This is of little interest now that 1189 AdaControl accepts GPS project files directly, and is still 1190 provided for compatibility with older versions of AdaControl. 1191 *Note Project files::. 1192 * "Delete Tree Files" removes existing tree files from the current 1193 directory. This is convenient when AdaControl complains that the 1194 tree files are not up-to-date. Note that you can set the 1195 preferences for automatic deletion of tree files after each run 1196 (see below). Note that the name of this menu is changed to "Delete 1197 Tree and .ali Files" if you have chosen to delete .ali files in the 1198 preferences (see below). 1199 * "Load results file" loads in the location window the result file 1200 obtained from a previous run of AdaControl. The file must have 1201 been produced with the "Gnat" or "Gnat_Short" format. *Note 1202 Control kinds and report messages::. 1203 1204 There are also two buttons representing Lady Ada in a magnifier glass 1205in the toolbar, one with a red question mark in the background. These 1206buttons launch AdaControl, by default on the file currently being 1207edited; however, you can change this behaviour from the preferences to 1208control either files from a list, or all files from the project. The 1209button without the question mark uses rules from the current rules file, 1210while the one with the question mark asks for the control to apply 1211interactively. 1212 1213 Here are some tips about using the "interactive" menus (or the button 1214with the question mark): 1215 * When you use the "interactive" menus several times, the previously 1216 entered command(s) is used as a default. 1217 * You can enter any command from AdaControl's language in the dialog; 1218 you can even enter several commands separated by ";". 1219 * Especially, if you want to run AdaControl with a rules file that is 1220 not the one defined by the switches, you can use one of the 1221 "interactive" commands, and give "source <file name>" as the 1222 command. 1223 1224 1225File: adacontrol_ug.info, Node: Contextual menu, Next: AdaControl switches, Prev: The AdaControl menu and buttons, Up: Running AdaControl from GPS 1226 12273.6.2 Contextual menu 1228--------------------- 1229 1230AdaControl adds two entries to the contextual menus (right click) of Ada 1231files. They call the 'pfni' utility on the current entity. *Note 1232pfni::. The entry "Print full name" displays the full name of the 1233entity in simple form, while the entry "Print full name (with 1234overloading)" ) prints it with overloading information. If the name 1235refers to an entity which is initialized (or to a parameter with a 1236default value), the initial value is printed. If the entity is a 1237discrete type, its range is printed. If the entity is an array type, 1238the ranges of its indices are printed. 1239 1240 This is convenient to find how to name entities in rule files. *Note 1241Specifying an Ada entity name::. It is also convenient to find where an 1242entity is declared, and which of several overloaded entities is being 1243referred to. 1244 1245 This is also convenient to find the actual value of a constant from 1246anywhere in the program text, since the printed value is completely 1247evaluated if it is a (static) expression. 1248 1249 1250File: adacontrol_ug.info, Node: AdaControl switches, Next: AdaControl preferences, Prev: Contextual menu, Up: Running AdaControl from GPS 1251 12523.6.3 AdaControl switches 1253------------------------- 1254 1255The tab "switches" from the "Project/Edit Project Properties" menu 1256includes a page for AdaControl, which allows you to set various 1257parameters. Since the GPS interface analyzes the output of AdaControl, 1258you should not set options directly in the bottom window of this page 1259(the one that displays the actual options passed to AdaControl). 1260 12613.6.3.1 Files 1262............. 1263 1264This section controls the definition of various files used by 1265AdaControl. 1266 * "Rules file". This is the name of a file that contains the 1267 definition of the controls to be applied to your project. This 1268 file is required for all "control (rules file)" commands. 1269 * "Units file". This is the name of a file that contains the list of 1270 units to be controlled. This file is required for all "control 1271 from list" commands. 1272 12733.6.3.2 Processing 1274.................. 1275 1276This section offers options that control how units are processed. 1277 * "Recursive mode". This sets the "-r" option. *Note Input units::. 1278 * "Ignore local deactivation". This sets the "-i" option. *Note 1279 Local disabling control::. 1280 * "Process specs only". This sets the "-s" option. *Note Input 1281 units::. 1282 * "Compilation unit mode". This sets the "-u" option. *Note Input 1283 units::. 1284 12853.6.3.3 Debug 1286............. 1287 1288This section controls the debugging options of AdaControl. 1289 * "Debug messages". This sets the "-d" option. *Note Verbose and 1290 debug mode::. 1291 * "Halt on error". This sets the "-x" option. *Note Exit on 1292 error::. 1293 12943.6.3.4 Output 1295.............. 1296 1297This section offers options that control where and how the output of 1298AdaControl is displayed. 1299 * "Display only errors". This sets the "-E" option. *Note Treatment 1300 of warnings::. 1301 * "Warnings as errors". This sets the "-e" option. *Note Treatment 1302 of warnings::. 1303 * "Statistics". This sets the "-S" option from a pull-down menu. 1304 *Note Control kinds and report messages::. 1305 * "Send results to GPS". When checked (default), the output of 1306 AdaControl is sent to the "locations" window of GPS. 1307 * "Send results to File". When checked, the output of AdaControl is 1308 sent to the file indicated in the box below. 1309 * "Send results to File and GPS". When checked, the output of 1310 AdaControl is sent to the file indicated in the box below, and the 1311 content of the file is then automatically reloaded in the 1312 "locations" window of GPS. If this option is set, the file format 1313 is always "Gnat" (the file format option is ignored). 1314 * "File name". This is the name of the file that will contain the 1315 results when sent to "File" or "File and GPS". If the results are 1316 sent to "File" and the file exists, AdaControl will ask for the 1317 permission to overwrite it. If the results are sent to "File and 1318 GPS", the result file is always overriden without asking. 1319 * "File format". This is a pull-down menu that allows you to select 1320 the desired format when output is directed to a file ("-F" option). 1321 *Note Control kinds and report messages::. 1322 13233.6.3.5 ASIS 1324............ 1325 1326This section controls the ASIS parameters passed to AdaControl. The 1327content of the input field "ASIS options" is used in place of the 1328standard ("-CA -FM") one. 1329 1330 Casual users don't need to change the default ASIS options. For more 1331details, *note ASIS options::. 1332 1333 1334File: adacontrol_ug.info, Node: AdaControl preferences, Next: AdaControl language, Prev: AdaControl switches, Up: Running AdaControl from GPS 1335 13363.6.4 AdaControl preferences 1337---------------------------- 1338 1339There is an entry for AdaControl in the "edit/preferences" menu: 1340 * "delete trees". If this box is checked, tree files are 1341 automatically deleted after each run of AdaControl. This avoids 1342 having problems with out-of-date tree files, at the expanse of 1343 slightly slowing down AdaControl if you run it several times in a 1344 row without changing the source files. 1345 * "Delete .ali files with tree files". If this box is checked, the 1346 ".ali" files in the current directory will also be deleted together 1347 with the tree files (either automatically if the previous box is 1348 checked, or when the "AdaControl/Delete Tree Files" menu is 1349 selected). This is normally what you want, unless the current 1350 directory is also used as the object directory for compilations; in 1351 the latter case, deleting ".ali" files would cause a full 1352 recompilation for the next build of the project. 1353 * "Help on rule". This allows you to select how rule specific help 1354 (from the "Help/AdaControl/Help on rule" menu) is displayed. If 1355 you select "Pop-up", a summary of the rule's purpose and syntax is 1356 displayed in a pop-up. If you select "User Guide", the user guide 1357 opens in a browser at the page that explains the rule. (Caveat: 1358 due to a problem in GPS under Windows, the "User Guide" option may 1359 not work at all, or the browser will not find the right anchor; 1360 hopefully, this will be fixed in an upcomming release of GPS. No 1361 such problem under Linux). 1362 * "Use separate categories". If this box is checked, there will be 1363 one category (i.e. tree in the locations window) for each rule 1364 type or label, otherwise all messages will be grouped under the 1365 single category "AdaControl". In practice, this means that with 1366 the box checked, messages will be sorted by rules first, then by 1367 files, while otherwise, the messages will be sorted by files first, 1368 then by rules. In any case, compilation errors appear under the 1369 "Compilation" category, final counts under the "Counts summary" 1370 category, and statistics under the "Statistics" category. 1371 * "Auto save files". If this box is checked, all modified files are 1372 automatically saved without asking before running AdaControl. 1373 Otherwise, a dialog appears allowing the user to choose which files 1374 to save. 1375 * "Buttons operate on". This defines the behaviour of the buttons. 1376 If "Current File" is selected, the buttons operate on the file 1377 being currently edited. If "Root Project" is selected, the buttons 1378 operate on all files that are part of the current project. If 1379 "Units from List" is selected, the buttons operate on all units 1380 from the units file. 1381 * "Display AdaControl run". If this box is checked, the command line 1382 used to launch AdaControl and the output messages are displayed in 1383 the "Messages" window. 1384 * "Max allowed error messages". If non zero, run will stop if the 1385 number of error messages exceeds this limit. *Note Output 1386 limits::. 1387 * "Max allowed messages (all kinds)". If non zero, run will stop if 1388 the number of error and warning messages exceeds this limit. *Note 1389 Output limits::. 1390 1391 1392File: adacontrol_ug.info, Node: AdaControl language, Next: AdaControl help, Prev: AdaControl preferences, Up: Running AdaControl from GPS 1393 13943.6.5 AdaControl language 1395------------------------- 1396 1397If you check "AdaControl" in the "Languages" tab of the project 1398properties, GPS will recognize files with extension '.aru' as AdaControl 1399rules files, and provide appropriate colorization. Remember to check 1400also the corresponding "no compiler" checkbox to avoid spurious messages 1401from GPS. 1402 1403 1404File: adacontrol_ug.info, Node: AdaControl help, Next: Caveat, Prev: AdaControl language, Up: Running AdaControl from GPS 1405 14063.6.6 AdaControl help 1407--------------------- 1408 1409The AdaControl User Manual (this manual) and the AdaControl Programmer 1410Manual are available from the "Help/AdaControl" menu of GPS. 1411 1412 The "Help on rule" entry displays the list of all rules; if you click 1413on one of them, you get help for the particular rule. Depending on the 1414setting of the "Help on rule" preference (see above), it opens a pop-up 1415that displays the rule(s) purpose and the syntax of its parameters, or 1416opens the user guide at the appropriate location. 1417 1418 The "About" entry displays a popup with AdaControl's version number 1419and license condition. 1420 1421 1422File: adacontrol_ug.info, Node: Caveat, Prev: AdaControl help, Up: Running AdaControl from GPS 1423 14243.6.7 Caveat 1425------------ 1426 1427GPS may crash when the output of a command is too big (i.e. hundreds of 1428messages with AdaControl). If this happens, use the "preferences" menu 1429to limit the number of messages. 1430 1431 1432File: adacontrol_ug.info, Node: Running AdaControl from AdaGide, Next: Helpful utilities, Prev: Running AdaControl from GPS, Up: Program Usage 1433 14343.7 Running AdaControl from AdaGide 1435=================================== 1436 1437If you want to use AdaControl from AdaGide, make sure you have copied 1438the necessary file into the required place. *Note Installing support 1439for AdaGide::. Note that AdaGide does not have all the parameterization 1440facilities of sophisticated environments like GPS, but all AdaControl 1441options, like the name of the rules file or the output format, can 1442easily be changed by editing the tool description file 'AdaControl.tdf'. 1443 1444 AdaGide now features several AdaControl commands from the "tool" 1445menu: 1446 * "AdaControl" runs AdaControl on the currently edited file, with 1447 rules taken from the file named 'verif.aru'. 1448 * "AdaControl recursive" works like the previous command, with the 1449 addition of the "-r" (recursive) option. When used on the main 1450 program, it will analyze the whole set of compilation units in the 1451 program. 1452 * "AdaControl interactive" runs AdaControl on the currently edited 1453 file, with a rule asked interactively from a pop-up. 1454 * "AdaControl: delete .adt" removes existing tree files from the 1455 current directory. This is convenient when AdaControl complains 1456 that the tree files are not up-to-date. 1457 1458 1459File: adacontrol_ug.info, Node: Helpful utilities, Next: Optimizing Adacontrol, Prev: Running AdaControl from AdaGide, Up: Program Usage 1460 14613.8 Helpful utilities 1462===================== 1463 1464This section describe utilities that are handy to use in conjunction 1465with AdaControl. 1466 1467* Menu: 1468 1469* pfni:: 1470* makepat.sed:: 1471* unrepr.sed:: 1472 1473 1474File: adacontrol_ug.info, Node: pfni, Next: makepat.sed, Prev: Helpful utilities, Up: Helpful utilities 1475 14763.8.1 pfni 1477---------- 1478 1479The convention used to refer to entities (as described in *note 1480Specifying an Ada entity name::) is very powerful, but it may be 1481difficult to spell out correctly the name of some entities, especially 1482when using the overloaded syntax. 1483 1484 'pfni' (which stands for Print Full Name Image) can be used to get 1485the correct spelling for any Ada entity. The syntax of 'pfni' is: 1486 pfni [-sofdq] [-p <project-file>] <unit>[:<span>] 1487 [-- <ASIS options>] 1488 <span> ::= <line_number> 1489 | [<first_line>]-[<last_line>] 1490 | <line_number>:<column_number> 1491 or 1492 pfni -h 1493 If called with the "-h" option, 'pfni' prints a help message and 1494exits. 1495 1496 Otherwise, 'pfni' prints the full name image of all identifiers 1497declared in the indicated unit, unless there is a "-f" (full) option, in 1498which case it prints the full name image of all identifiers (i.e. 1499including those that are used, but not declared, in the unit). The 1500image is printed without overloading information, unless the "-o" option 1501is given. 1502 1503 In addition, 'pfni' prints the initial value of variables if there is 1504one, the range of discrete types, and the range of the indices of array 1505types. 1506 1507 The <unit> is given either as an Ada unit, or as a file name, 1508provided the extension is ".ads" or ".adb" (as in AdaControl). If a 1509span is given, only identifiers within the span are printed. In the 1510first form, the span includes only the indicated line; in the second 1511form, the span includes all lines from <first_line> to <last_line> (if 1512omitted, they are taken as the first and last line of the file, 1513respectively). In the third form, the span includes only the place at 1514the specified <line_number> and <column_number>. 1515 1516 Normally, the source line corresponding to the names is printed above 1517the names. The "-q" (quiet) option suppresses this. 1518 1519 If the "-s" option is given (or the unit is a file name with a ".ads" 1520extension), the specification of the unit is processed, otherwise the 1521body is processed. The "-p" option specifies the name of a project file 1522(".gpr" or ".adp"), and the "-d" option is the debug mode, as for 1523AdaControl itself. ASIS options can be passed, like for AdaControl, 1524after a "--" (but -FS is the default). *Note ASIS options::. 1525 1526 As a side usage of 'pfni', if you are calling a subprogram that has 1527several overloadings and you are not sure which one is called, use 1528'pfni' with the "-o" option on that line: the program will tell you the 1529full name and profile of the called subprogram. 1530 1531 1532File: adacontrol_ug.info, Node: makepat.sed, Next: unrepr.sed, Prev: pfni, Up: Helpful utilities 1533 15343.8.2 makepat.sed 1535----------------- 1536 1537This file (provided in the "src" directory) is a sed script that 1538transforms a text file into a set of correponding regular expressions. 1539It is useful to generate model header files. *Note Header_Comments::. 1540 1541 1542File: adacontrol_ug.info, Node: unrepr.sed, Prev: makepat.sed, Up: Helpful utilities 1543 15443.8.3 unrepr.sed 1545---------------- 1546 1547This file (provided in the "src" directory) is a sed script that 1548comments out all representation clauses. It is typically useful if you 1549use a different compiler that accepts representation clauses not 1550supported by GNAT. 1551 1552 Typically, you would copy all your sources in a different directory, 1553copy "unrepr.sed" in that directory, then run: 1554 sed -i -f unrepr.sed *.ads *.adb 1555 You can now run AdaControl on the patched files. Of course, you 1556won't be able to check rules related to representation clauses any 1557more... 1558 1559 Note that the script adds "--UNREPR " to all representation clauses. 1560Its effect can thus easily be undone with the following commad: 1561 sed -i -e "s/--UNREPR //" *.ads *.adb 1562 1563 1564File: adacontrol_ug.info, Node: Optimizing Adacontrol, Next: In case of trouble, Prev: Helpful utilities, Up: Program Usage 1565 15663.9 Optimizing Adacontrol 1567========================= 1568 1569There are many factors that may influence dramatically the speed of 1570AdaControl when processing many units. For example, on our canonical 1571test (same controls, same units), the extreme points for execution time 1572were 111s. vs 13s.! Unfortunately, this seems to depend on a number of 1573parameters that are beyond AdaControl's control, like the relative speed 1574of the CPU to the speed of the hard-disk, or the caching strategy of the 1575file system. 1576 1577 This section will give some hints that may help you increase the 1578speed of AdaControl, but it will not change the output of the program; 1579you don't really need to read it if you just use AdaControl 1580occasionnally. This section is concerned only with the GNAT 1581implementation of ASIS; other implementations work differently. 1582 1583 Bear in mind that the best strategy depends heavily on how your 1584program is organized, and on the particular OS and hardware you are 1585using. Therefore, no general rule can be given, you'll have to 1586experiment yourself. Hint: if you specify the "-v" option to 1587AdaControl, it will print in the end the elapsed time for running the 1588tests; this is very helpful to make timing comparisons. 1589 1590 Note: all options described in this section are ASIS options, i.e. 1591they must appear last on the command line, after a "--". 1592 1593* Menu: 1594 1595* Tree files and the ASIS context:: 1596* Generating tree files manually:: 1597* Choosing an appropriate combination of options:: 1598 1599 1600File: adacontrol_ug.info, Node: Tree files and the ASIS context, Next: Generating tree files manually, Prev: Optimizing Adacontrol, Up: Optimizing Adacontrol 1601 16023.9.1 Tree files and the ASIS context 1603------------------------------------- 1604 1605Since AdaControl is an ASIS application, it is useful to explain here 1606how ASIS works. ASIS (and therefore AdaControl) works on a set of units 1607constituting a "context". Any reference to an Ada entity which is not 1608in the context (nor automatically added, see below) will be ignored; 1609especially, if you specify to AdaControl the name of a unit which is not 1610included in the current context, the unit will simply not be processed. 1611 1612 ASIS works by exploring tree files (same name as the corresponding 1613Ada unit, with a ".adt" extension), which are "predigested" views of the 1614corresponding Ada units. By default, the tree files are generated 1615automatically when needed, and kept after each run, so that subsequent 1616runs do not have to recreate them. 1617 1618 A context in ASIS-for-Gnat is a set of tree files. Which trees are 1619part of the context is defined by the "-C" option: 1620 * -C1 Only one tree makes up the context. The name of the tree file 1621 must follow the option. 1622 * -CN Several explicit trees make up the context. The name of the 1623 tree files must follow the option. 1624 * -CA All available trees make up the context. These are the tree 1625 files found in the current directory, and in any directory given 1626 with a "-T" option (which works like the "-I" option, but for tree 1627 files instead of source files). 1628 1629 The "-F" option specifies what to do if the program tries to access 1630an Ada unit which is not part of the context: 1631 * -FT Only consider tree files, do not attempt to compile units 1632 on-the-fly 1633 * -FS Always compile units on-the-fly, ignore existing tree files 1634 * -FM Compile on-the-fly units for which there is no already existing 1635 tree file 1636 Note that "-FT" is the only allowed mode, and must be specified, with 1637the "-C1" and "-CN" options. 1638 1639 The default combination used by AdaControl is "-CA -FM". A 1640consequence of this is that the context is established by first loading 1641all available tree files before starting the analysis, even those that 1642are not necessary. Since tree files are often big and long to load, if 1643you want to check a single unit and have remaining trees from a previous 1644run, it is often more efficient to delete all ".adt" files first. 1645 1646 More generally, given the current speed of CPUs and the not-so-fast 1647access time of disks, it may happen that recomputing the trees instead 1648of loading them from disk might be faster. Only experiencing will tell 1649you the best procedure to follow. 1650 1651 1652File: adacontrol_ug.info, Node: Generating tree files manually, Next: Choosing an appropriate combination of options, Prev: Tree files and the ASIS context, Up: Optimizing Adacontrol 1653 16543.9.2 Generating tree files manually 1655------------------------------------ 1656 1657It is also possible to generate the tree files manually before running 1658AdaControl. Although this mode of operation is less practical, it is 1659recommended by AdaCore for any ASIS tool that deals with many 1660compilation units. Some reasons why you might want to generate the tree 1661files manually are: 1662 * Your project has several source directories (ASIS had problems with 1663 ADA_INCLUDE_PATH, until releases dated later than Sept. 1st, 1664 2006). Note that an alternative solution is to provide a project 1665 file with the -p option, or to specify source directories with the 1666 -I option; 1667 * Your project uses some compilation options that cannot be set 1668 otherwise (AdaControl just uses the "source_dirs" from GPR 1669 projects, not other options) 1670 * It is faster to generate tree files once than to use "compile on 1671 the fly" mode. 1672 1673 To generate tree files manually, simply recompile your project with 1674the "-gnatct" option. This option can be passed to 'gnatmake' or 1675'gprbuild' normally. Of course, you will need all other options needed 1676by your project (like the "-P" option if you are using GNAT project 1677files). 1678 1679 Tree files may be copied into a different directory if you don't want 1680your current directory to be cluttered by them. In this case, use the 1681"-T" ASIS option to indicate the directory where the tree files are 1682located. 1683 1684 If you chose to generate the tree files manually, you may want to 1685specify the "-FT" ASIS option (see above) to prevent from accidental 1686automatic recompilation. 1687 1688 1689File: adacontrol_ug.info, Node: Choosing an appropriate combination of options, Prev: Generating tree files manually, Up: Optimizing Adacontrol 1690 16913.9.3 Choosing an appropriate combination of options 1692---------------------------------------------------- 1693 1694In order to optimize the use of AdaControl, it is important to remember 1695that reading tree files is a time-consuming operation. On the other 1696hand, a single tree file contains not only information for the 1697corresponding unit, but also for the specifications of all units that 1698the given unit depends on. Moreover, our measures showed that reading 1699an existing tree file may be slower than compiling the corresponding 1700unit on-the-fly (but once again, YMMV). 1701 1702 Here are some hints to help you find the most efficient combination 1703of options. 1704 * If you want to run AdaControl on all units of your program, use the 1705 "-D" option to create a file containing the list of all required 1706 units, then use this file as an indirect file. Using the the "-r" 1707 option (recursive mode) of AdaControl implies an extra pass over 1708 the whole program tree to determine the necessary units. 1709 * If you have not disabled any rule (and have many messages), 1710 specifying the "-i" option (ignore disabling) saves AdaControl the 1711 burden of checking whether rules are disabled, which can result in 1712 a sensible speed-up. 1713 * Avoid having unnecessary tree files. All tree files in the context 1714 are read by ASIS, even if they are not later used. If you don't 1715 want to run AdaControl on the whole project, deleting tree files 1716 from a previous run can save a lot of time. 1717 * When using an indirect file, the order in which units are given may 1718 influence the speed of the program. As a rule of thumb, units that 1719 are closely related should appear close to each other in the file. 1720 A good starting point is to sort the file in alphabetical order: 1721 this way, child units will appear immediately after their parent. 1722 You can then reorder units, and measure if it has a significant 1723 effect on speed. 1724 * If you want to check a unit individually, try using the "-C1" 1725 option (especially if the current directory contains many tree 1726 files from previous runs). Remember that you must specify the unit 1727 to check to AdaControl, and the tree file to ASIS. I.e., if you 1728 want to check the unit "Example", the command line should look 1729 like: 1730 adactl -f rules_file.aru example -- -FT -C1 example.adt 1731 provided the tree file already exists. 1732 * For each strategy, first run AdaControl with the default options 1733 (which will create all necessary tree files). Compare execution 1734 time with the one you get with "-FT" and "-FS". This will tell you 1735 if compiling on-the-fly is more efficient than loading tree files, 1736 or not. 1737 1738 1739File: adacontrol_ug.info, Node: In case of trouble, Prev: Optimizing Adacontrol, Up: Program Usage 1740 17413.10 In case of trouble 1742======================= 1743 17443.10.1 Known issues 1745------------------- 1746 1747If you are using an old version of GNAT and your project includes source 1748files located in several directories, the ADA_INCLUDE_PATH environment 1749variable may not be considered by ASIS, resulting in error messages that 1750tell you that the bodies of some units have not been found (and hence 1751have not been processed). This problem has been fixed in GNAT dated 1752later than Sept. 1st, 2006. If this happens, either provide your 1753source directories as "-I" options (*note ASIS options::), or generate 1754the tree files manually (*note Generating tree files manually::). Note 1755that this problem does not happen if you are using a project file (*note 1756Project files::), nor if you are running AdaControl from GPS. 1757 17583.10.2 AdaControl or ASIS failure 1759--------------------------------- 1760 1761Like any sophisticated piece of software, AdaControl may fail when 1762encountering some special case of construct. ASIS may also fail 1763occasionnally; actually, we discovered several ASIS bugs during the 1764development of AdaControl. These were reported to ACT, and have been 1765corrected in the wavefront version of GNAT - but you may be using an 1766earlier version. In this case, try to upgrade to a newer version of 1767ASIS. If an AdaControl or ASIS problem is not yet solved, AdaControl is 1768designed in such a way that an occasionnal bug won't prevent you from 1769using it. 1770 1771 If AdaControl detects an unexpected exception during the processing 1772of a unit (an ASIS error or an internal error), it will abandon the 1773unit, clean up everything, and go on processing the remaining units. 1774This way, an error due to a special case in a unit will not affect the 1775processing of other units. AdaControl will return a Status of 10 in 1776this case. 1777 1778 However, if it is run with the "-x" option (eXit on error), it will 1779stop immediately, and no further processing will happen. 1780 1781 If you don't want the garbage from a failing rule to pollute your 1782report, you may chose to disable the rule for the unit that has a 1783problem. *Note Inhibit command::. 1784 1785 If you encounter a problem while using AdaControl, you are very 1786welcome to report it through our bug tracking system 1787(https://sourceforge.net/p/adacontrol/tickets/) (under Windows, you can 1788click on "Report problem" in the AdaControl Start menu). Please include 1789the exact control and the unit that caused the problem, as well as the 1790captured output of the program (with "-dx" option). 1791 1792 1793File: adacontrol_ug.info, Node: Command language reference, Next: Rules reference, Prev: Program Usage, Up: Top 1794 17954 Command language reference 1796**************************** 1797 1798AdaControl is about controlling rules. Rules are built in AdaControl; 1799each rule has a name, and may require parameters. For the complete 1800description of each rule, *note Rules reference::. 1801 1802 To run AdaControl, you need to define which rules you want to apply 1803to your Ada units, what are the parameters, etc. In addition, you may 1804want to define various things, like the file where the results should 1805go, the output format, etc. 1806 1807 AdaControl defines a small command language which is used to describe 1808how you want to process your units. Commands can be specified either on 1809the command line or in a file, that we call here a rules file. Commands 1810can also be given interactively; *Note Interactive mode::. 1811 1812* Menu: 1813 1814* General:: 1815* Controls:: 1816* Other commands:: 1817* Example of commands:: 1818 1819 1820File: adacontrol_ug.info, Node: General, Next: Controls, Prev: Command language reference, Up: Command language reference 1821 18224.1 General 1823=========== 1824 1825The command language is not case-sensitive, i.e. the case of the 1826keywords, rule names, and parameters is not significant. The layout of 1827commands is free (i.e. a command can extend over several lines, and 1828spaces are freely allowed between syntactic elements). 1829 1830 Comments are allowed in and between commands. Comments begin with a 1831"#" or a "--", and extend to the end of the line. 1832 1833 Since wide characters are allowed in Ada programs, AdaControl accepts 1834wide characters in commands as well. With GNAT, the encoding scheme is 1835Hex ESC encoding (see the GNAT User-Guide/Reference-Manual). This is 1836the prefered method, since few people require wide characters in 1837programs anyway, and that keeping the default bracket encoding would not 1838conveniently allow brackets for regular expressions, like those used by 1839some rules. *Note Syntax of regular expressions::. 1840 1841 If a syntax error is encountered in a command, an appropriate error 1842message is output, and analysis of the rules file continues in order to 1843output all errors, but no analysis of user code will be performed. 1844 1845 1846File: adacontrol_ug.info, Node: Controls, Next: Other commands, Prev: General, Up: Command language reference 1847 18484.2 Controls 1849============ 1850 1851A control command is a command that declares one (or several) controls. 1852A control defines how a rule is applied to Ada units. The syntax of a 1853control command is as follows: 1854 <control_command> ::= [<label> ":"] <control> {"," <control>} ";" 1855 <control> ::= <ctrl_kind> <Rule_Name> [<parameters>] 1856 <parameters ::= "(" [<modifiers>] <value> {"," [<modifiers>] <value>} ")" 1857 <ctrl_kind> ::= "check"|"search"|"count" 1858 1859 If present, the label gives a name to the control(s); it will be 1860printed whenever each control is activated, and can be used to disable 1861the control(s). *Note Disabling controls::. If no label is present, 1862the rule name is printed instead. The label must have the syntax of an 1863Ada identifier, or else the label must be included within double quotes 1864('"'), in which case it can contain any character. 1865 1866 Each control consists of a <ctrl_kind> followed by a rule name, and 1867(optionally) parameters. Some parameters may be preceded by modifiers 1868(such as "not" or "case_sensitive"). The meaning of the rule parameters 1869and modifiers depends on the rule. 1870 1871 Here are some examples of commands: 1872 check unnecessary_use_clause; 1873 All_Imports: search pragmas (Import); 1874 "Why do you need that?": check entities (Unchecked_Conversion, 1875 all 'Address); 1876 1877 Specifying several controls with the same label is a shorthand which 1878is equivalent to specifying the same label for several controls. It is 1879handy when the label is long, and/or to stress that several controls are 1880part of the same programming rule. For example: 1881 "Check why this obsolete stuff is still used": 1882 check entities (obsolete_unit_1), -- Note comma here! 1883 check instantiations (some_obsolete_generic); 1884 1885* Menu: 1886 1887* Control kinds and report messages:: 1888* Parameters:: 1889* Multiple controls:: 1890* Disabling controls:: 1891 1892 1893File: adacontrol_ug.info, Node: Control kinds and report messages, Next: Parameters, Prev: Controls, Up: Controls 1894 18954.2.1 Control kinds and report messages 1896--------------------------------------- 1897 1898There are three control kinds: "check", "search", and "count". 1899 1900 "Check" is intended to search for rules that must be obeyed in your 1901programs. Normally, if a "Check" control fails, you should fix the 1902program. "Search" is intended to report some situations, but you should 1903consider what to do on a case-by-case basis. Roughly, use "check" when 1904you consider that the failure of the control is an error, and "search" 1905when you consider it as a warning. AdaControl will exit with a status 1906of 1 if any "Check" control is triggered, and a status of 0 if only 1907"Search" controls were triggered (or no control was triggered at all). 1908 1909 "Count" works like "Search", but instead of printing a message for 1910each control which is triggered, it simply counts occurrences and prints 1911a summary at the end of the run. There is a separate count for each 1912control label (or if no label is given, the rule name is taken instead); 1913if you give the same label to different controls, this allows you to 1914accumulate the counts. 1915 1916 A report message (except for the final report of "count") comprises 1917the following elements: 1918 * the file name (where the control matches) 1919 * the line number (where the control matches) 1920 * the column number (where the control matches) 1921 * the label (if there is one) and/or the rule name (the rule that 1922 matches). 1923 * a message (why the control matches). A control whose kind is 1924 "check" will produce an error report message (i.e. containing the 1925 keyword "Error") and a control whose kind is "search" will produce 1926 a found report message (i.e. containing the keyword "Found"). 1927 1928 The formatting of the report message depends on the format option, 1929which can be selected with the "-F" command-line option or the "set 1930format" command. 1931 1932 If the format is "Gnat" (the default) or "Gnat_Short", items are 1933separated by ':'; this is the same format as the one used by GNAT error 1934messages. Editors (like Emacs or GPS) that recognize this format allow 1935you to go directly to the place of the message by clicking on it. In 1936order to avoid too long messages, only the label appears, unless there 1937is none, in which case it is replaced with the rule name. 1938 1939 If the format is "CSV" or "CSV_Short", items are separated by ',' and 1940surrounded by double quotes. This is the "Comma Separated Values" 1941format, which can be read by any known spreadsheet program, except 1942Excel(tm) by default, which uses the semicolon and not the comma to 1943separate fields. Therefore, the formats "CSVX" and "CSVX_Short" do the 1944same thing, but using semi-colons (';') instead of commas. Both the 1945label (replaced by an empty column if there is none) and the rule name 1946appear. Note that when an output file is created in one of the "CSV" 1947formats, a title line is issued as the first line, following normal CSV 1948convention. 1949 1950 If the format is "Source" or "Source_Short", the offending source 1951line is output, and the message is output behind it, with a "!" 1952pointing to the exact location of the problem. 1953 1954 If the format is "None", no error message is output at all. This is 1955useful when only the return code of running AdaControl is desired (just 1956to check if a program is OK or not). Note that this does not prevent 1957the output of statistics, since these are under control of the "-S" 1958option or the "set statistics" command. In this case, statistics are 1959output in CSVX format, since asking for statistics with a "none" format 1960is mainly useful for analysing the statistics with a spreadsheet 1961program. 1962 1963 With recent versions of GNAT, the file name includes the full path of 1964the source file. If the "_Short" form of the format option is used, the 1965file name is stripped from any path. This can make it easier to compare 1966the results of controlling units from various directories. Note that 1967with older versions of GNAT, the file name never includes the full path, 1968and the "_Short" form of the format option has no effect. 1969 1970 After each run (*note Go command::), statistics may be output, 1971depending on the statistics level which is set with the "-S" option or 1972the "set statistics" command. The meaning of the various levels is as 1973follows: 1974 * 0: No statistics are output (default) 1975 * 1: A count of error and warning messages is output 1976 * 2: The rule name and label (if any) of any control not triggered 1977 are output 1978 * 3: The rule name and label (if any) of every control is output, 1979 together with a count of each triggering kind ("check", "search", 1980 "count"), or "not triggered" if the control was not triggered. 1981 1982 1983File: adacontrol_ug.info, Node: Parameters, Next: Multiple controls, Prev: Control kinds and report messages, Up: Controls 1984 19854.2.2 Parameters 1986---------------- 1987 1988Most rules accept parameters. Parameters can be: 1989 * a keyword for the rule 1990 * a numerical value 1991 * a character string (often a regular expression) 1992 * an Ada entity name 1993 1994 A numerical value is given with the syntax of an Ada integer or real 1995literal (underscores and exponents are allowed as in Ada). Based 1996literals are supported for integer values; if somebody can justify a 1997need for supporting them for reals, we'll be happy to add this feature 1998later... 1999 2000 A character string is given within double quotes """. As usual, 2001quotes appearing within the string are doubled. The tilde character 2002("~") can be used as a replacement delimiter, but the same character 2003must be used at both ends of the string. The latter has been chosen as 2004a character not used by the various shells, and can be useful to pass 2005quoted strings from parameters on the command line (unfortunately, we 2006could not use the percent ("%") sign, because it plays a special role in 2007DOS/Windows). 2008 2009 An Ada entity name is the full name (prefixed with the names of all 2010units that include it) of something declared in a program. It can be 2011followed by overloading information, in order to uniquely identify the 2012Ada entity. If an Ada entity is overloaded and no overloading 2013information is provided, the rule is applied to all (overloaded) Ada 2014entities that match the name. Alternatively, it can be "all" followed 2015by a simple name, in wich case it applies to all entities with that 2016name. See *note Specifying an Ada entity name:: for the full 2017description of the syntax. Here are some examples of entity names: 2018 Ada.Text_IO.Put -- All Put defined in Ada.Text_IO 2019 Ada.Text_IO.Put{Standard.Character} -- The Put on Character 2020 all Put -- All Put 2021 Standard.Integer'Image -- The 'Image function on Integer 2022 all 'Image -- All 'Image functions 2023 2024 2025File: adacontrol_ug.info, Node: Multiple controls, Next: Disabling controls, Prev: Parameters, Up: Controls 2026 20274.2.3 Multiple controls 2028----------------------- 2029 2030Most rules can be used in more than one control (with different 2031parameters). There is no difference between a single or a multiple 2032configuration rule use: outputs, efficiency, etc. are the same. 2033 2034 The following rules files produce an identical configuration: 2035 Search Pragmas (Pure, Elaborate_All); 2036 and 2037 Search Pragmas (Pure); 2038 Search Pragmas (Elaborate_All); 2039 2040 However, the second form can be used to give different labels. 2041Consider: 2042 Search Pragmas (Pure); 2043 No_Elaborate: Search Pragmas (Elaborate_All); 2044 2045 The messages for pragma 'Pure' will contain "PRAGMAS", while those 2046for 'Elaborate_All' will contain "No_Elaborate". If a disabling comment 2047mentions 'pragmas', it will disable both controls, but a disabling 2048comment that mentions 'No_Elaborate' will disable only the second one. 2049 2050 2051File: adacontrol_ug.info, Node: Disabling controls, Prev: Multiple controls, Up: Controls 2052 20534.2.4 Disabling controls 2054------------------------ 2055 2056It is possible to disable controls on parts of the source code by 2057placing markers in the source code. A marker is an Ada comment, where 2058the comment mark ('--') is immediately followed by the special tag 2059"'##'" (by default). 2060 2061 There are two kinds of markers: block markers and line markers. Both 2062kinds specify a list of controls to disable/re-enable. A list of 2063controls is a list of rule names (to disable/re-enable all controls on 2064the indicated rule(s)) or control labels (to disable/re-enable all 2065controls with that label), separated by spaces. Alternatively, the list 2066of controls can be the word "all" to disable/re-enable all controls. 2067 2068 In a "'--##'" line, everything appearing after another "##" tag (by 2069default) is ignored. This allows the insertion of a comment explaining 2070why the control is disabled at that point. 2071 2072 Both tags can be changed with the "set" command. *Note Set 2073command::. 2074 20754.2.4.1 Block disabling 2076....................... 2077 2078A control is disabled from a "rule off" marker that applies to it until 2079a "rule on" marker that applies to it. If there is no appropriate "rule 2080on" marker, the control is disabled up to the end of file. 2081 2082 Syntax: 2083 --## rule off <control_list> 2084 Ada code block 2085 --## rule on <control_list> 2086 2087 Ex: 2088 --## rule off rule1 rule2 ## Authorized by QA ref 1234 2089 I := I + 1; 2090 Proc (I); 2091 --## rule on rule2 2092 20934.2.4.2 Line disabling 2094...................... 2095 2096A control is disabled only for the line where a marker that applies to 2097it appears. 2098 2099 Syntax: 2100 Ada code line --## rule line off <rule_list> 2101 Ex: 2102 I := I + 1; --## rule line off rule3 rule_label_1 2103 Conversely, it is possible to re-enable a control for just the 2104current line in a block where it is disabled: 2105 2106 Syntax: 2107 Ada code line --## rule line on <rule_list> 2108 Ex: 2109 --## rule off rule1 rule2 2110 ... 2111 I := I + 1; --## rule line on rule2 2112 21134.2.5 Limitation 2114---------------- 2115 2116Since the disabling is based on special comments, there is a conflict 2117with the rule "header_comments" which is based on the content of 2118comments. Line disabling is not possible with this rule, and block 2119disabling needs special care. *Note Header_Comments::. 2120 2121 2122File: adacontrol_ug.info, Node: Other commands, Next: Example of commands, Prev: Controls, Up: Command language reference 2123 21244.3 Other commands 2125================== 2126 2127In addition to controls, AdaControl recognizes a number of commands. 2128Although these commands are especially useful when using the interactive 2129mode (*note Interactive mode::), they can be used in command files as 2130well. 2131 2132* Menu: 2133 2134* Go command:: 2135* Quit command:: 2136* Message command:: 2137* Help command:: 2138* Clear command:: 2139* Set command:: 2140* Source command:: 2141* Inhibit command:: 2142 2143 2144File: adacontrol_ug.info, Node: Go command, Next: Quit command, Prev: Other commands, Up: Other commands 2145 21464.3.1 Go command 2147---------------- 2148 2149This command starts processing of the controls that have been specified. 2150 2151 Syntax: 2152 go; 2153 Controls are not reset after a "go" command; for example, the 2154following program: 2155 search entities (pack1); 2156 go; 2157 search entities (pack2); 2158 go; 2159 will first output all usages of 'Pack1', then all usages of both 2160'Pack1' and 'Pack2'. See *note Clear command:: to reset controls. 2161 2162 If not in interactive mode, a "go" command is automatically added at 2163the end, therefore it is not required in rules files. 2164 2165 2166File: adacontrol_ug.info, Node: Quit command, Next: Message command, Prev: Go command, Up: Other commands 2167 21684.3.2 Quit command 2169------------------ 2170 2171This command terminates AdaControl. 2172 2173 Syntax: 2174 quit; 2175 If given in a file, all subsequent commands will be ignored. This 2176command is really useful only in interactive mode. *Note Interactive 2177mode::. 2178 2179 2180File: adacontrol_ug.info, Node: Message command, Next: Help command, Prev: Quit command, Up: Other commands 2181 21824.3.3 Message command 2183--------------------- 2184 2185This command prints a message on the output file. 2186 2187 Syntax: 2188 message "<any string>" [pause]; 2189 The length of the message is limited to 250 characters. If the word 2190"pause" (case irrelevant) is specified after the message, AdaControl 2191will wait for the user to press the Return key before proceeding. 2192 2193 Note that the message is syntactically a string, and must therefore 2194be quoted (double quotes). 2195 2196 2197File: adacontrol_ug.info, Node: Help command, Next: Clear command, Prev: Message command, Up: Other commands 2198 21994.3.4 Help command 2200------------------ 2201 2202This command prints various informations about the rules and AdaControl 2203itself. 2204 2205 Syntax: 2206 Help [<help_item> {,<help_item>}] 2207 <Help_Item> ::=<keyword> | <rule name> | variables ["<pattern>"] 2208 <keyword> ::= all | commands | license | list | options | rules | version 2209 Without any argument, this command prints a summary of all commands 2210and rule names. If given one or more keywords or rule names, it prints 2211the corresponding help message. See *note Getting help:: for the 2212details. 2213 2214 2215File: adacontrol_ug.info, Node: Clear command, Next: Set command, Prev: Help command, Up: Other commands 2216 22174.3.5 Clear command 2218------------------- 2219 2220This command command clears (i.e. removes) controls that have been 2221previously given. 2222 2223 Syntax: 2224 Clear all | <rule name>{,<rule name>} ; 2225 The command clears all controls given for the indicated rules, or for 2226all rules if the 'all' keyword is given. Rule variables (*note Set 2227command::) associated to cleared rules are returned to their default 2228values. For example, the following program: 2229 search entities (pack1); 2230 go; 2231 clear all; 2232 search entities (pack2); 2233 go; 2234 will first output all usages of 'Pack1', then all usages of 'Pack2'. 2235Without the "clear all" command, the second "go" would output all usages 2236of 'Pack1' together with all usages of 'Pack2'. 2237 2238 2239File: adacontrol_ug.info, Node: Set command, Next: Source command, Prev: Clear command, Up: Other commands 2240 22414.3.6 Set command 2242----------------- 2243 2244This command sets various parameters of AdaControl. 2245 2246 Syntax: 2247 set Format Gnat|Gnat_Short|CSV|CSV_Short|Source|Source_short|None; 2248 set Check_Key|Search_Key "<value>" 2249 set Max_Errors [<value>]; 2250 set Max_Messages [<value>]; 2251 set Output|New_Output <output file>; 2252 set Statistics <level>; 2253 set Tag1|Tag2 "<value>"; 2254 set Trace <trace file>; 2255 set Debug|Exit_On_Error|Verbose|Warning|Warning_As_Error 2256 On|Off; 2257 set Timing On|Off|Global 2258 set Ignore On|Off|Inverted; 2259 set <Rule_Name>.<Variable> <Value> 2260 The "set format" command selects the output format for the messages, 2261like the "-F" option; see *note Control kinds and report messages:: for 2262details. 2263 2264 The "set check_key" command defines a string which is used in place 2265of "Error" in messages issued by a "check" control. Similarly, the "set 2266search_key" command defines a string which is used in place of "Found" 2267in messages issued by a "search" control. This can be useful when 2268AdaControl is used, for example, to detect places where manual 2269inspection is required; having the word "Error" in the message could be 2270misleading to the persons in charge of the review. Note however that if 2271you set these keys, the GPS interface will not be able to recognize 2272properly the messages. 2273 2274 The "set max_errors" and "set max_messages" limit the output of 2275AdaControl, like the "-m" and "-M" options; see *note Output limits:: 2276for details. If no <value> is given after the command name, the 2277corresponding limitation is removed. 2278 2279 The "set output" and "set new_output" commands redirect the output of 2280subsequent controls to the indicated file. If the string 'console' 2281(case irrelevant) is given as the <output file>, output is redirected to 2282the console. 2283 2284 The "set new_output" always create a new file (or overwrites an 2285existing file with the same name). 2286 2287 The "set output" command appends if the file exists, unless the "-w" 2288option is given, in which case it is overwritten. However, the file is 2289overwritten only the first time it is mentionned in an "output" command. 2290This means that you can switch forth and back between two output files, 2291all results from the same run will be kept. Note however that for this 2292to work, you need to specify the output file exactly the same way: if 2293you specify it once as "result.txt", and then as "./result.txt", the 2294second one will overwrite the first one. 2295 2296 The "set statistics" command sets the statistics level, like the "-S" 2297option; see *note Control kinds and report messages:: for details. 2298 2299 The "set Tag1|Tag2" command changes the tags used to disable (or 2300enable) rules. "Tag1" is the string that appears immediately after the 2301comment indicator ('--'), and "tag2" is the tag that terminates the 2302special comment. Note that these tags must be given as strings (in 2303quotes) and that case is relevant. See *note Disabling controls:: for 2304details. 2305 2306 The "set trace" command redirects the trace messages of the "-d" 2307option to the indicated file. If the string 'console' (case irrelevant) 2308is given as the <trace file>, trace messages are redirected to the 2309console. As with the "-t" option, if the file exists, output is 2310appended to it. 2311 2312 The "set Debug|Exit_On_Error|Verbose|Warning|Warning_As_Error" 2313command activates ("on") or deactivates ("off") options. "Debug" 2314corresponds to the "-d" option, "Exit_On_Error" to the "-x" option, 2315"Ignore" to the "-i" option, "Timing" to the "-T" option, "Verbose" to 2316the "-v" option, "Warning" to the "-E" option, and "Warning_As_Error" to 2317the "-e" option. See *note Verbose and debug mode::, *note Exit on 2318error::, *note Treatment of warnings::, *note Output format::, and *note 2319Local disabling control:: for details. 2320 2321 The "set Timing" command activates ("on") or deactivates ("off") the 2322printing of the time spent in each rule after each "go" command. If set 2323to "global" instead of "on", the timings are accumulated over all "go" 2324commands, and output when the program terminates. 2325 2326 The "set Ignore" command governs handling of disabled messages (*note 2327Disabling controls::). In default mode ("set Ignore Off"), disabled 2328messages are not printed. When set to "on" ("set Ignore On"), all 2329messages are printed, including those that are disabled. Setting this 2330option can result in considerable speed-up of the printing of messages. 2331When set to "Inverted" ("set Ignore Inverted"), only disabled messages 2332are printed. This is useful to check which messages have been disabled. 2333 2334 Some rules may also have user-settable global variables that affect 2335their behaviour; the last form of the "set" command allows changing 2336their value. The variable name is of the form of a qualified name (i.e. 2337"rule.var"), and the value depends on the variable. The description of 2338the variables (if any) and appropriate values is given for each rule. 2339 2340 2341File: adacontrol_ug.info, Node: Source command, Next: Inhibit command, Prev: Set command, Up: Other commands 2342 23434.3.7 Source command 2344-------------------- 2345 2346This command inputs commands from another file. 2347 2348 Syntax: 2349 Source <input file>; 2350 Commands are read and executed from the indicated file, then control 2351is returned to the place after the "source" command. There is no 2352restriction on the content of the sourced file; especially, it may 2353itself include other "source" commands. 2354 2355 If <input file> is a relative file path, it is taken relatively to 2356the file where the "source" command is given. Especially, if no path is 2357specified, the sourced file will be taken from the same directory as the 2358sourcing file (irrespectively of where the command is being run from). 2359If the file is not found there, it is searched on the path given by the 2360environment variable 'ADACTL_PATH'. 2361 2362 The default extension is '.aru', i.e. if <input file> is not found 2363as given, AdaControl will retry the same name with '.aru' appended. It 2364is a syntax error if the file is not found either. 2365 2366 If the string 'console' (case irrelevant) is given as the <input 2367file>, commands are read from the console until a "quit" command is 2368given. This command is of course useful only from files, and allows to 2369pass temporarily control to the user in interactive mode. 2370 2371 2372File: adacontrol_ug.info, Node: Inhibit command, Prev: Source command, Up: Other commands 2373 23744.3.8 Inhibit command 2375--------------------- 2376 2377This command prevents execution of certain controls on particular units. 2378 2379 Syntax: 2380 Inhibit <rule name>|all ([all] <unit> {,[all] <unit>}); 2381 Controls refering to the given rule (or all rules if "all" is 2382specified in place of a rule name) for the indicated unit(s) are not 2383performed. In addition, if "all" is specified in front of the unit 2384name, the unit will not be accessed at all, even from rules that follow 2385call graphs, and could thus access this unit while analyzing other 2386units. 2387 2388 There are several reasons why you might want to inhibit a control of 2389a rule for certain units: 2390 * The unit is known not to obey the rule in many places, and you 2391 don't want the output to be cluttered with too many messages (of 2392 course, you'll fix the unit in the near future!); 2393 * The unit is known to obey the rule, execution of the rule is 2394 time-consuming, and you want to save some processing time; 2395 * The unit is known to raise an ASIS bug, and until you upgrade to 2396 the appropriate version of GNAT, you don't want to be bothered by 2397 the error messages. 2398 2399 The "all" option for a unit is intended for the last case, to prevent 2400ASIS bugs from spoiling any unit that calls something from an offending 2401unit. 2402 2403 2404File: adacontrol_ug.info, Node: Example of commands, Prev: Other commands, Up: Command language reference 2405 24064.4 Example of commands 2407======================= 2408 2409Below is an example of a file with multiple commands: 2410 message "Searching Unchecked_Conversion"; 2411 search entitities (ada.unchecked_conversion); 2412 set output uc_usage.txt; 2413 go; 2414 clear all; 2415 message "Searching 'Address"; 2416 search entities (all 'Address); 2417 set output address_usage.txt; 2418 go; 2419 This file will output all usages of 'Ada.Unchecked_Conversion' into 2420the file 'uc_usage.txt', then output all usages of the ''Address' 2421attribute into the file 'address_usage.txt'. Messages are output to 2422tell the user about what's happenning. 2423 2424 2425File: adacontrol_ug.info, Node: Rules reference, Next: Examples of using AdaControl for common programming rules, Prev: Command language reference, Up: Top 2426 24275 Rules reference 2428***************** 2429 2430This chapter describes each rule currently provided by AdaControl. Note 2431that the 'rules' directory of the distribution contains a file named 2432'verif.aru' that contains an example of a set of rules appropriate to 2433check on almost any software. 2434 2435 A general limitation applies to all rules. AdaControl is a static 2436checking tool, and therefore cannot check usages that depend on run-time 2437values. For example, it is not possible to check rules applying to an 2438entity when this entity is aliased and accessed through an access value, 2439or rules applying to subprogram calls when the call is a dispatching 2440call. 2441 2442* Menu: 2443 2444* Abnormal_Function_Return:: 2445* Allocators:: 2446* Array_Declarations:: 2447* Aspects:: 2448* Assignments:: 2449* Barrier_Expressions:: 2450* Case_Statement:: 2451* Characters:: 2452* Comments:: 2453* Declarations:: 2454* Default_Parameter:: 2455* Dependencies:: 2456* Derivations:: 2457* Directly_Accessed_Globals:: 2458* Duplicate_Initialization_Calls:: 2459* Entities:: 2460* Entity_Inside_Exception:: 2461* Exception_Propagation:: 2462* Expressions:: 2463* Generic_Aliasing:: 2464* Global_References:: 2465* Header_Comments:: 2466* Improper_Initialization:: 2467* Instantiations:: 2468* Insufficient_Parameters:: 2469* Local_Access:: 2470* Local_Hiding:: 2471* Max_Blank_Lines:: 2472* Max_Call_Depth:: 2473* Max_Line_Length:: 2474* Max_Nesting:: 2475* Max_Size:: 2476* Max_Statement_Nesting:: 2477* Movable_Accept_Statements:: 2478* Naming_Convention:: 2479* No_Operator_Usage:: 2480* Non_Static:: 2481* Not_Elaboration_Calls:: 2482* Not_Selected_Name:: 2483* Object_Declarations:: 2484* Parameter_Aliasing:: 2485* Parameter_Declarations:: 2486* Positional_Associations:: 2487* Potentially_Blocking_Operations:: 2488* Pragmas:: 2489* Record_Declarations:: 2490* Reduceable_Scope:: 2491* Representation_Clauses:: 2492* Return_Type:: 2493* Side_Effect_Parameters:: 2494* Silent_Exceptions:: 2495* Simplifiable_Expressions:: 2496* Simplifiable_Statements:: 2497* Statements:: 2498* Style:: 2499* Terminating_Tasks:: 2500* Type_Initial_Values:: 2501* Type_Usage:: 2502* Uncheckable:: 2503* Unit_Pattern:: 2504* Units:: 2505* Unnecessary_Use_Clause:: 2506* Unsafe_Elaboration:: 2507* Unsafe_Paired_Calls:: 2508* Unsafe_Unchecked_Conversion:: 2509* Usage:: 2510* Use_Clauses:: 2511* With_Clauses:: 2512 2513 2514File: adacontrol_ug.info, Node: Abnormal_Function_Return, Next: Allocators, Prev: Rules reference, Up: Rules reference 2515 25165.1 Abnormal_Function_Return 2517============================ 2518 2519This rule controls functions that may not terminate normally, i.e. 2520where 'Program_Error' could be raised due to reaching the end of the 2521function without encountering a 'return' statement. 2522 25235.1.1 Syntax 2524------------ 2525 2526 <control_kind> abnormal_function_return; 2527 25285.1.2 Action 2529------------ 2530 2531The rule controls that the sequence of statements of each function body, 2532as well as each of its exception handlers, ends with: 2533 * a 'return' statement (including extended return statements) 2534 * a 'raise' statement (or equivalently, a call to 2535 'Ada.Exceptions.Raise_Exception' or 2536 'Ada.Exceptions.Reraise_Occurrence'); 2537 * a call to a procedure which is the target of a 'pragma No_Return'; 2538 * a block statement, whose last statement of its sequence and any 2539 exception handler is one of these; 2540 * an 'if' statement that includes an 'else' path, and where the last 2541 statement of every path is one of these; 2542 * a 'case' statement where the last statement of every path is one of 2543 these. 2544 * a plain 'loop' statement (not 'for' or 'while') without any 'exit' 2545 or 'goto' statement transfering control outside of the loop. 2546 2547 This is a sufficient (but of course not necessary) condition to 2548ensure that no function raises 'Program_Error' due to reaching the end 2549of its statements without encountering a 'return'. 2550 2551 This rule can be specified only once. 2552 2553 Ex: 2554 check abnormal_function_return; 2555 25565.1.3 Tips 2557---------- 2558 2559This rule checks that a function always returns correctly, but does not 2560prevent multiple 'return' statements in functions. If you want to 2561ensure that there is exactly one 'return' statement in functions, and 2562that this statement is always the last one, use this rule together with 2563the rule 'statements(function_return)'. *Note Statements::. 2564 2565 It is possible to exit from an extended return statement with an 2566'exit' or 'goto' statement. If this happens, the return statement is 2567not considered a proper return statement, and an appropriate message is 2568issued. 2569 2570 2571File: adacontrol_ug.info, Node: Allocators, Next: Array_Declarations, Prev: Abnormal_Function_Return, Up: Rules reference 2572 25735.2 Allocators 2574============== 2575 2576This rule controls the use of allocators (i.e. dynamic memory 2577allocation). 2578 25795.2.1 Syntax 2580------------ 2581 2582 <control_kind> allocators [(<target> {, <target>})]; 2583 <target> ::= [anonymous | inconsistent | not] [<category>|<entity>] 2584 <category> ::= () | access | array | delta | digits | 2585 mod | protected | range | record | tagged | task 2586 25875.2.2 Action 2588------------ 2589 2590If one or several <entity> or <category> are given, only allocators 2591whose allocated type matches the <entity>, or whose type belongs to the 2592indicated <category>, are controlled; otherwise all allocators are 2593controlled. As usual, the whole syntax for entities is allowed for 2594<entity>. *Note Specifying an Ada entity name::. The meaning of 2595<category> is: 2596 * "()": The allocated value is of an enumerated type. 2597 * "access": The allocated value is of an access type. 2598 * "array": The allocated value is of an array type. 2599 * "delta": The allocated value is of a fixed point type (it is not 2600 currently possible to distinguish ordinary fixed point types from 2601 decimal fixed point types). 2602 * "digits": The allocated value is of a floating point type. 2603 * "mod": The allocated value is of a modular type. 2604 * "protected": The allocated value is of a protected type. 2605 * "range": The allocated value is of a signed integer type. 2606 * "record": The allocated value is of an (untagged) record type. 2607 * "tagged": The allocated value is of a tagged type (including type 2608 extensions). 2609 * "task": The allocated value is of a task type. 2610 2611 This rule is especially useful for finding memory leaks, since it 2612tells all the places where dynamic allocation occurs. 2613 2614 If a parameter is preceded by the word "not", allocators for the 2615corresponding type or category are not controlled (i.e. they are always 2616allowed). If a control includes only "not" parameters, an implicit 2617check for all allocators is assumed. 2618 2619 If a parameter is preceded by the word "anonymous", only allocators 2620whose expected type is an anonymous access type are controlled. 2621 2622 If a parameter is preceded by the word "inconsistent", only 2623allocators whose allocator subtype (the name after "'new'") is not the 2624same as the designated subtype (from the access type declaration) are 2625controlled. However an allocator is not considered inconsistent when 2626the designated subtype imposes no special constraint: 2627 * when it is a class-wide type, since the allocator subtype will 2628 generally be of some descendant specific type; 2629 * when it is an unconstrained array type, since the allocated subtype 2630 is necessarily constrained; 2631 * when it is a base type (of the form 'T'Base'). 2632 2633 Note that if the access type includes a constraint like in the 2634following example: 2635 type Acc is access integer range 1..10; 2636 all allocators will necessarilly be inconsistent, since there is no 2637way to repeat the constraint at the place of the allocator. 2638 2639 "Inconsistent" can be given alone, in which case all inconsistent 2640allocators are controlled. 2641 2642 Ex: 2643 search allocators (standard.string); 2644 check allocators (T'Class); 2645 check allocators (array); 2646 check allocators (Inconsistent standard.Integer); 2647 check allocators (Inconsistent); 2648 2649 -- all task allocators, except when the type is called "special": 2650 check allocators (task, not all Special); 2651 26525.2.3 Tips 2653---------- 2654 2655The type given as an <entity> in the rule must be a first named subtype, 2656and the rule will also find allocators that use a subtype of this type. 2657If the type is declared within a generic package, the rule will control 2658all corresponding types from instantiations. 2659 2660 The type mentionned in the rule is the one following the 'new' 2661keyword, which is not necessarily the same as the expected type in 2662presence of implicit conversions like this: 2663 2664 type T is tagged ...; 2665 type Class_Access is access T'Class; 2666 X : Class_Access; 2667 begin 2668 X := new T; 2669 2670 This allocator will be found for type 'T', not for type 'T'Class'. 2671 2672 For <categories>, note that the rule "sees through" derived and 2673private types (i.e. it will trigger if the ultimate type belongs to the 2674indicated category). 2675 2676 The reason for the "inconsistent" modifier is that inconsistent 2677allocators may cost a double check. Given: 2678 type Acc is access Positive; 2679 V : Acc; 2680 begin 2681 V := new Natural'(...); 2682 The compiler will first check the constraint for Natural, then the 2683constraint for Positive. To avoid confusion, it is better to always use 2684the same subtype for the allocator as used in the access type 2685declaration. 2686 2687 The reason for the "anonymous" modifier is that allocators of an 2688anonymous type (especially access parameters) create a terrible mess in 2689accessibility rules, and are better avoided. 2690 26915.2.4 Limitations 2692----------------- 2693 2694In some (rare) cases involving anonymous access types as array or record 2695components, ASIS provides no way to determine the target type of the 2696(anonymous) acccess type. Inconsistent allocators will thus not be 2697controlled. Such cases are detected by the rule "uncheckable". *Note 2698Uncheckable::. 2699 2700 2701File: adacontrol_ug.info, Node: Array_Declarations, Next: Aspects, Prev: Allocators, Up: Rules reference 2702 27035.3 Array_Declarations 2704====================== 2705 2706This rule controls properties of arrays, by enforcing a consistent value 2707or range of values for the lower or upper bound, or by limiting the 2708possible size. It can also control various aspects of the component 2709type of the array. 2710 27115.3.1 Syntax 2712------------ 2713 2714 <control_kind> array_declarations (first, <value> | <bounds>); 2715 <control_kind> array_declarations (last, <value> | <bounds>); 2716 <control_kind> array_declarations (dimensions, <value> | <bounds>); 2717 <control_kind> array_declarations ([all] length, <bounds>); 2718 <control_kind> array_declarations (component, <type> {,<repr_cond>}); 2719 <control_kind> array_declarations (index, <type> | <> {,<type> | <>}); 2720 <bounds> ::= min|max <value> [, min|max <value> ] 2721 <type> ::= <entity>|<category> 2722 <category > ::= () | access | array | delta | digits | mod | private 2723 | protected | range | record | tagged | task 2724 <repr_cond> ::= [not] pack | size | component_size 2725 27265.3.2 Action 2727------------ 2728 2729This rule controls properties of the index or component of an array 2730type. The checks are therefore performed on array definitions, i.e. on 2731array (sub)type declarations and single array declarations. However, 2732the "length" subrule can be checked on any array variable, see below. 2733 2734 The first parameter is a subrule keyword: 2735 * "First" and "Last" control the lower (respectively upper) bound of 2736 each dimension of arrays (even unconstrained array types). If a 2737 single value is specified without the "min" or "max" modifiers, the 2738 subrule controls the bounds that are not exactly this value; 2739 otherwise, it controls the bounds that are smaller than the given 2740 "min" value or greater than the given "max" value. It is possible, 2741 but not required to specify both "min" and "max". If this subrule 2742 is given both for "search" and for "check", the value(s) for 2743 "search" is interpreted as the prefered one, and the value(s) for 2744 "check" is interpreted as an alternative acceptable one; i.e., it 2745 is a warning if the value is the one given for "check", and an 2746 error if it is neither. In short: 2747 search array_declarations (first, 1); 2748 check array_declarations (first, min -1, max 1); 2749 will be silent if the lower bound of an array is 1, it will issue a 2750 warning if it is in the range -1 .. 1, and an error otherwise. 2751 * "Dimensions"controls the number of dimensions of arrays. If a 2752 single value is specified without the "min" or "max" modifiers, the 2753 subrule controls arrays whose number of dimensions is not exactly 2754 this value; otherwise, it controls arrays whose number of 2755 dimensions are smaller than the given "min" value or greater than 2756 the given "max" value. It is possible, but not required to specify 2757 both "min" and "max". If this subrule is given both for "search" 2758 and for "check", the value(s) for "search" is interpreted as the 2759 prefered one, and the value(s) for "check" is interpreted as an 2760 alternative acceptable one; i.e., it is a warning if the value is 2761 the one given for "check", and an error if it is neither. In 2762 short: 2763 search array_declarations (Dimensions, 1); 2764 check array_declarations (Dimensions, min 2, max 3); 2765 will be silent for one-dimensional arrays, it will issue a warning 2766 for 2- and 3-dimensional arrays, and an error otherwise. 2767 * "Length" controls arrays that have a dimension whose number of 2768 elements is smaller than the given "min" value or greater than the 2769 given "max" value (except for unconstrained array types). At least 2770 one of "min" or "max" must be specified, but it is not required to 2771 specify both. 2772 2773 If the "all" modifier is specified, all object declarations of an 2774 array type are controlled, even if they do not contain any special 2775 constraint. This is useful if you want to assess all variables 2776 that contain more than a certain number of elements. For example: 2777 type Tab is array (Min .. Max) of Compo; -- Always checked 2778 subtype Str is String (Min .. Max); -- Always checked 2779 V1 : String (Min .. Max); -- Always checked 2780 V2 : Str; -- Checked only with "all" 2781 2782 * "Component" controls arrays whose component type is the indicated 2783 <entity>, or whose component type belongs to the indicated 2784 <category>. If the <entity> is a subtype, only arrays whose 2785 components are of that subtype are controlled. If the indicated 2786 <entity> is a type, all arrays whose components are of that type 2787 (including subtypes) are controlled. The meaning of <category> is: 2788 * "()": The component is of an enumerated type. 2789 * "access": The component is of an access type. 2790 * "array": The component is of an array type. 2791 * "delta": The component is of a fixed point type (it is not 2792 currently possible to distinguish ordinary fixed point types 2793 from decimal fixed point types). 2794 * "digits": The component is of a floating point type. 2795 * "mod": The component is of a modular type. 2796 * "private": The component is of a private type (including 2797 private extensions). 2798 * "protected": The component is of a protected type. 2799 * "range": The component is of a signed integer type. 2800 * "record": The component is of an (untagged) record type. 2801 * "tagged": The component is of a tagged type (including type 2802 extensions). 2803 * "task": The component is of a task type. 2804 If <repr_cond> are specified, the rule controls only arrays to 2805 which all the corresponding representation items apply: 2806 * "pack": A pragma Pack applies to the array. 2807 * "not pack": No pragma Pack applies to the array. 2808 * "size": A size representation clause applies to the array. 2809 * "not size": No size representation clause applies to the 2810 array. 2811 * "component_size": A component_size representation clause 2812 applies to the array. 2813 * "not component_size": No component_size representation clause 2814 applies to the array. 2815 2816 * "index" controls arrays whose index types are the indicated 2817 <entity>, or whose index types belong to the indicated <category>. 2818 If the <entity> is a subtype, only arrays whose indexes are of that 2819 subtype are controlled. If the indicated <entity> is a type, all 2820 arrays whose indexes are of that type (including subtypes) are 2821 controlled. The meaning of <category> is the same as for 2822 "component", but obviously only "()", "range", and "mod" are 2823 allowed. 2824 2825 The number of <entity> given determines the dimensionality of the 2826 controlled arrays. If a "<>" is given in place of an entity, it 2827 means that any type matches at that position. 2828 2829 This rule can be specified several times for the "component" and 2830"index" subrules. For other subrules, it can be specified at most once 2831for each subrule and for each of "check", "search" and "count". It is 2832thus possible for each subrule to have a value considered a warning, and 2833a value considered an error. 2834 2835 Ex: 2836 -- All arrays should start at 1: 2837 check array_declarations (first, 1); 2838 2839 -- No arrray of more than 100 elements: 2840 check array_declarations (length, max 100); 2841 2842 -- No empty array: 2843 check array_declarations (length, min 1); 2844 2845 -- Arrays whose component type is private: 2846 check array_declarations (component, private); 2847 2848 -- Packed arrays of Character 2849 check array_declarations (component, Standard.Character, pack); 2850 2851 -- Packed arrays of record without size clause 2852 check array_declarations (component, record, packed, not size); 2853 2854 -- One-dimensional arrays indexed by Integer 2855 check array_declarations (index, standard.integer); 2856 2857 -- Three dimensional arrays whose second index is an enumeration 2858 check array_declarations (index, <>, (), <>); 2859 28605.3.3 Tips 2861---------- 2862 2863The subrule 'Max_Length' ignores index constraints that are not static. 2864Non static index constraints can be controlled with the rule 'Non_Static 2865(Index_Constraint)'. *Note Non_Static::. 2866 2867 Requiring the same upper bound for all arrays is not very useful, 2868but: 2869 check array_declarations (last, min 1); 2870 can be used to check that no array has a negative or zero upper 2871bound. 2872 2873 The subrule "index" controls a precise pattern of types used as 2874indices. To control the use of a type as an index at any position and 2875irrespectively of the number of indices of the array, use the rule 2876"type_usage". *Note Type_Usage::. 2877 2878 2879File: adacontrol_ug.info, Node: Aspects, Next: Assignments, Prev: Array_Declarations, Up: Rules reference 2880 28815.4 Aspects 2882=========== 2883 2884This rule controls aspect specifications (new feature in Ada 2012), 2885either all of them or specific ones. 2886 28875.4.1 Syntax 2888------------ 2889 2890 <control_kind> aspects [(all | <aspect mark> {, <aspect mark>})]; 2891 28925.4.2 Action 2893------------ 2894 2895Without parameters (or if "all" is given), controls all aspect 2896specifications. Otherwise, controls only the aspect specifications 2897corresponding to the given aspect marks. 2898 2899 Ex: 2900 search aspects; 2901 DBC: check aspects (Pre, Post, Pre'Class, Post'Class); 2902 2903 2904File: adacontrol_ug.info, Node: Assignments, Next: Barrier_Expressions, Prev: Aspects, Up: Rules reference 2905 29065.5 Assignments 2907=============== 2908 2909This rule controls various issues related to the assignment statement: 2910assignments that involve array sliding, redundant assignments to the 2911same variable, or groups of assignments that are replaceable by 2912aggregate assignment. 2913 29145.5.1 Syntax 2915------------ 2916 2917 <control_kind> assignments (sliding); 2918 <control_kind> assignments (repeated); 2919 <control_kind> assignments (groupable, <filter> {,<filter>}); 2920 <filter> ::= given <min_val> | missing <max_val> | ratio <min_val> | 2921 total <max_val> 2922 29235.5.2 Action 2924------------ 2925 2926The first form (keyword "sliding") controls array assignments where the 2927target variable has a different lower bound than the assigned 2928expression; this is allowed by the language only in so-called "sliding" 2929contexts. 2930 2931 Other subrules control properties of groups of assignment statements. 2932A group is made of consecutive assignments, without any other 2933intervening kind of statements (except null statements). 2934 2935 The second form (keyword "repeated") controls when a same variable 2936(or a same subcomponent of a structured variable) is assigned several 2937times in the same group of assignments. This form of the rule can be 2938given only once. 2939 2940 The third form (keyword "groupable") controls assignments to 2941different subcomponents of a same structured variable; such assignments 2942are often replaceable by a global assignment of an aggregate to the 2943variable. One or several <filter> parameters indicate under which 2944conditions a group is reported: 2945 * "given": <min_val> (an integer value) indicates the minimum number 2946 of assigned subcomponents that will trigger the rule (i.e. the 2947 rule is triggered if the number of assignments to subcomponents of 2948 a same variable is greater or equal to the indicated value). 2949 * "missing": <max_val> (an integer value) indicates the maximum 2950 number of subcomponents not assigned that will trigger the rule 2951 (i.e. the rule is triggered if the number of subcomponents not 2952 assigned to is lesser or equal to the indicated value). 2953 * "ratio": <min_val> (an integer value) indicates the minimum 2954 percentage of assigned subcomponents that will trigger the rule 2955 (i.e. the rule is triggered if the percentage of assigned 2956 subcomponents is greater or equal to the indicated value). 2957 * "total": <max_val> (an integer value) indicates the maximum number 2958 of subcomponents of the type that will trigger the rule (i.e. the 2959 rule is triggered if the number of subcomponents of the record type 2960 is lesser or equal to the indicated value). 2961 2962 If several filters are given, the rule is triggered if all conditions 2963are met ("and" logic). Note however that this rule can be given several 2964times, thus achieving "or" logic. 2965 2966 The rule is not triggered on an object if a subcomponent of that 2967object is of a limited type, since global assignment would not be 2968allowed in that case. 2969 2970 For other structured objects, a subcomponent is counted as assigned 2971if it has been assigned in full, or if it should have been assigned in 2972full (in other words: if the rule is triggered on those subcomponents as 2973well) - recursively, of course. 2974 2975 Ex: 2976 search Assignments (sliding); 2977 check Assignments (repeated); 2978 2979 -- Warn if a at least 3 fields are given and at most 2980 -- two fields are missing, or if 80% of the fields are given: 2981 search assignments (groupable, given 3, missing 2); 2982 search assignments (groupable, ratio 80); 2983 29845.5.3 Tip 2985--------- 2986 2987The "sliding" subrule is not intended to prevent all cases of slidings 2988(the dynamic ones are uncheckable), it is rather an indication of 2989"obvious" cases that could be avoided. 2990 2991 Note that for the "groupable" subrule, it is possible to give 1 for 2992the "given" criterion; in this case, any assignment to parts of a 2993structured variable will be reported, only global assignment is allowed. 2994 29955.5.4 Limitations 2996----------------- 2997 2998As usual, AdaControl can control only static aspects of assignments. 2999Therefore, it cannot control assignments whose target is not statically 3000known (like dynamic indexing of arrays). Slices are always considered 3001dynamic (the cases where it would be useful did not seem worth the 3002additional complexity). 3003 3004 For the "sliding" subrule, if the assigned expression is a 3005multidimensional aggregate, only the first dimension is checked for 3006sliding, other dimensions are ignored. This is not considered an 3007important issue, since in any case the rule can detect only static 3008cases, and the handling of sliding in multi-dimensional array aggregates 3009is extremely touchy (see RM 4.3.3 for details). 3010 3011 For the "groupable" subrule, if the number of subcomponents is not 3012statically determinable (dynamic arrays, discriminated records), only 3013the "given" criterion can be met. 3014 3015 3016File: adacontrol_ug.info, Node: Barrier_Expressions, Next: Case_Statement, Prev: Assignments, Up: Rules reference 3017 30185.6 Barrier_Expressions 3019======================= 3020 3021Although the language allows any expression as the barrier of a 3022protected entry, it is generally better to use only "simple" 3023expressions. This rule controls the kind of constructs allowed in 3024barrier expressions. 3025 30265.6.1 Syntax 3027------------ 3028 3029 <control_kind> Barrier_Expressions ([<allowable> {, <allowable>}]); 3030 <allowable> ::= <entity> | <keyword> 3031 <keyword> ::= allocation | any_component | any_variable | 3032 arithmetic_operator | array_aggregate | comparison_operator | 3033 conversion | dereference | indexing | 3034 function_attribute | local_function | logical_operator | 3035 record_aggregate | value_attribute 3036 30375.6.2 Action 3038------------ 3039 3040Without parameters, the only elements allowed in barriers are references 3041to boolean components of the protected element and litterals (this 3042corresponds to what is allowed for the Ravenscar profile). Parameters 3043specify other constructs that are allowed: 3044 * Any <entity> (like a global variable, a function...) can be 3045 specified and is thus allowed. As usual, the whole syntax for 3046 entities is allowed for <entity>. *Note Specifying an Ada entity 3047 name::. 3048 * "allocation" allows use of allocators. 3049 * "any_component" allows use of protected components that are not of 3050 type 'Standard.Boolean'. 3051 * "any_variable" allows use of any variable (i.e. variables external 3052 to the protected element). 3053 * "arithmetic_operator" allows use of predefined arithmetic operators 3054 ('"+"', '"**"', etc.). 3055 * "array_aggregate" allows use of array aggregates. 3056 * "comparison_operator" allows use of predefined comparison and 3057 membership operators ('"="', '">"', 'in', etc.). 3058 * "conversion" allows use of type conversions and type 3059 qualifications. 3060 * "dereference" allows use of dereferencing of access types (both 3061 implicit and explicit dereferences). 3062 * "indexing" allows use of array indexing and slices. 3063 * "function_attribute" allows use of attributes that are functions 3064 (like ''Pred', ''Image', etc.). 3065 * "local_function" allows use of (protected) functions declared in 3066 the same protected object. 3067 * "logical_operator" allows use of predefined logical operators and 3068 short-circuit forms ('and', 'or else', etc.). 3069 * "record_aggregate" allows use of record aggregates and extension 3070 aggregates. 3071 * "value_attribute" allows use of attributes that are simple values 3072 (like ''First', ''Terminated', etc.). 3073 3074 This rule can be given only once for each of "check", "search" and 3075"count". 3076 3077 Ex: 3078 search barrier_expressions; 3079 check barrier_expressions (logical_operator, comparison_operator, 3080 any_component, 3081 Pack.Global_State); 3082 30835.6.3 Tips 3084---------- 3085 3086The goal of the "Simple_Barrier" restriction from the Ravenscar profile 3087is to ensure that evaluation of barriers never raise exceptions. Even 3088simple things like a qualified expression can raise exceptions, but in 3089practice more than the restriction of the Ravenscar profile can be 3090"reasonably" allowed. 3091 3092 Note that the various "operator" keywords allow only the use of 3093predefined operators. If a user defined operator should be allowed, 3094provide it explicitely as an <entity>. There is no way to allow any 3095function call, since this would boil down to allowing pretty much 3096anything, but you can of course specify explicitely functions that can 3097be called. 3098 3099 You can provide this rule both for "check" and "search", but of 3100course it makes sense only if the set of allowed features for "search" 3101is a superset of those allowed for "check". This way, the use of 3102certain features can be interpreted only as a warning. 3103 3104 3105File: adacontrol_ug.info, Node: Case_Statement, Next: Characters, Prev: Barrier_Expressions, Up: Rules reference 3106 31075.7 Case_Statement 3108================== 3109 3110This rule controls various metrics related to the 'case' statement. It 3111is intended for cases where it is desired to limit the complexity of 3112'case' statements. 3113 31145.7.1 Syntax 3115------------ 3116 3117 <control_kind> Case_Statement (<subrule>, <bound> [, <bound>]); 3118 <subrule> ::= others_span | paths | range_span | values | values_if_others 3119 <bound> ::= min | max <value> 3120 31215.7.2 Action 3122------------ 3123 3124The first parameter is a subrule keyword. The second (and optionnally 3125third) parameter give the minimum and/or maximum allowed values (i.e. 3126the rule will control values outside the indicated interval). If not 3127specified, the minimum value is defaulted to 0 and the maximum value to 3128infinity. The parameters controlled by each subrule are: 3129 * "others_span" controls the number of values covered by 'when' 3130 'others' case alternatives. 3131 * "paths" controls the number of paths (i.e. 'when' branches). 3132 * "range_span" controls the number of values covered by ranges used 3133 as choices. 3134 * "values" controls the number of values covered by the subtype of 3135 the 'case' selector. 3136 * "values_if_others" is like "values", but is activated only for 3137 'case' statements with a 'when' 'others' alternative. 3138 3139 This rule can be specified at most once for each subrule and for each 3140of "check", "search" and "count". It is thus possible for each subrule 3141to have a value considered a warning, and a value considered an error. 3142 3143 Ex: 3144 check Case_Statement (others_span, min 1); 3145 search Case_Statement (others_span, min 5); 3146 3147 check Case_Statement (values, max 10); 3148 check Case_Statement (paths, min 3, max 30); 3149 31505.7.3 Tips 3151---------- 3152 3153To control that no range is used as a choice in a 'case' statement: 3154 check case_statement (range_span, max 0); 3155 3156 To control "'when' 'others'" that cover no value at all: 3157 check case_statement (others_span, min 1); 3158 31595.7.4 Limitations 3160----------------- 3161 3162If some characteristic of the 'case' statement depend on a generic 3163formal type, it is not possible to control some of the features 3164statically. Such cases are detected by the rule "uncheckable". *Note 3165Uncheckable::. 3166 3167 If the subtype of the selecting expression of the 'case' statement, 3168or a subtype in one of its a choice lists, has applicable static 3169predicates, AdaControl is not able to control the features that depend 3170on the number of values of the subtype. Such cases are detected by the 3171rule "uncheckable". *Note Uncheckable::. We hope to be able to remove 3172this limitation in the future, but the problem is quite difficult... 3173 3174 3175File: adacontrol_ug.info, Node: Characters, Next: Comments, Prev: Case_Statement, Up: Rules reference 3176 31775.8 Characters 3178============== 3179 3180This rule makes sure that the program text does not use "undesirable" 3181characters. 3182 31835.8.1 Syntax 3184------------ 3185 3186 <control_kind> characters [(<subrule> {, <subrule>})]; 3187 <subrule> ::= control | not_iso_646 | trailing_space | wide 3188 31895.8.2 Action 3190------------ 3191 3192The rule controls the occurrence in the source file of characters 3193belonging to the classe(s) defined by the subrules. Without parameters, 3194all classes are controlled. The classes are defined as follows: 3195 * "control": control characters that are allowed by the language 3196 (ASCII HT, ASCII VT and ASCII FF). 3197 * "not_iso_646": characters outside the ISO-646 set (aka ASCII). 3198 * "trailing_space": space characters appearing at the end of the 3199 source line. 3200 * "wide": wide characters that are not in 'Standard.Character'. 3201 3202 This rule can be given only once for each class of characters. 3203 3204 Ex: 3205 check characters (control, trailing_space); 3206 search characters (not_iso_646); 3207 32085.8.3 Limitations 3209----------------- 3210 3211With the "wide" subrule, the error message may seem to not always appear 3212at the right place; this depends on the encoding scheme used. For 3213example, if your source contains (using bracket encoding): 3214 S : Wide_String := "["1041"]["1042"]"; 3215 it will appear to AdaControl as a string containing two characters, 3216and therefore the error message for the second wide character will point 3217at two characters after the opening quote of the string. 3218 3219 This rule controls only the characters in the source file; other 3220means of having characters in the corresponding classes (like using the 3221''Val' attribute) are not controlled. 3222 3223 3224File: adacontrol_ug.info, Node: Comments, Next: Declarations, Prev: Characters, Up: Rules reference 3225 32265.9 Comments 3227============ 3228 3229This rule controls comments that must, or must not, appear in certain 3230cases. 3231 32325.9.1 Syntax 3233------------ 3234 3235 <control_kind> comments (pattern, "<pattern>" {, "<pattern>"}); 3236 <control_kind> comments (position, <value> | <bounds>); 3237 <control_kind> comments (terminating {, "<pattern>" | begin | end}); 3238 <control_kind> comments (unnamed_begin, <kind> {, <kind>}); 3239 <bounds> ::= min|max <value> [, min|max <value> ] 3240 <kind> ::= [<condition>] <unit_kind> 3241 <condition> ::= always | declaration | program_unit 3242 <unit_kind> ::= all | procedure | function | entry | package | task 3243 32445.9.2 Action 3245------------ 3246 3247The first parameter is a subrule name which detemines what is being 3248controlled. 3249 * "pattern" controls comments that match one of the given patterns 3250 (given as strings). Only the "useful" part of the comment is 3251 matched against the patterns, i.e. the part after the "'--'" and 3252 spaces following it. Patterns are given using the full Regexp 3253 syntax. *note Syntax of regular expressions:: for details. 3254 Pattern matching is always case insensitive. 3255 3256 This subrule is especially useful to find lines with comments like 3257 "TBSL" (To Be Supplied Later) or "fixme", which are often used to 3258 mark places where something should be done before releasing the 3259 program. 3260 * "position" controls the starting position of comments. If a single 3261 value is specified without the "min" or "max" modifiers, the 3262 subrule controls comments that do not start exactly at the 3263 indicated column position; otherwise, it controls comments whose 3264 starting column is smaller than the given "min" value or greater 3265 than the given "max" value. It is possible, but not required to 3266 specify both "min" and "max". If this subrule is given both for 3267 "search" and for "check", the value(s) for "search" is interpreted 3268 as the prefered one, and the value(s) for "check" is interpreted as 3269 an alternative acceptable one; i.e., it is a warning if the value 3270 is the one given for "check", and an error if it is neither. In 3271 short: 3272 search comments (position, 1); 3273 check comments (position, min 1, max 6); 3274 will be silent for comments that start in column 1, it will issue a 3275 warning for comments that start at columns 2 to 6, and an error 3276 otherwise. 3277 3278 * "terminating" controls comments that are at the end of an otherwise 3279 non empty line (i.e. that appear on the same line as a declaration 3280 or statement). If "begin" is specified, comments appearing on a 3281 line that contains only a 'begin' are allowed (not reported); 3282 similarly, if "end" is specified, comments appearing on a line that 3283 contains only an 'end' are allowed. Otherwise, the other 3284 parameters are patterns that specify forms of comments that are 3285 allowed. Patterns are given using the full Regexp syntax. *note 3286 Syntax of regular expressions:: for details. Pattern matching is 3287 always case insensitive. 3288 * "unnamed_begin" controls 'begin' of various constructs that do not 3289 have a comment that repeats the name of the program unit associated 3290 to the 'begin'. Except for spaces, the comment must not contain 3291 anything else than the unit name. 3292 3293 The <condition> keyword determines circumstances where the comment 3294 is required: 3295 * "always" (default): the comment is always required. 3296 * "declaration": the comment is required only if the preceding 3297 declaration part is non-empty (not counting pragmas). 3298 * "program_unit": the comment is required only if the preceding 3299 declaration part contains the declarations of other program 3300 units (subprograms, packages, protected objects, or tasks). 3301 3302 The <unit_kind> keyword detemines the kind of program unit to which 3303 the rule applies ("all" stands for all kinds). The subrule can be 3304 given only once of each kind of program unit. 3305 3306 Ex: 3307 check comments (pattern, "TBSL"); 3308 3309 -- Report places where rules are disabled: 3310 search comments (pattern, "##.* off"); 3311 3312 -- End of line comments are not allowed, except for the 3313 -- comment that repeats the name of a procedure on the "begin" 3314 -- line, and special AdaControl comments 3315 check comments (terminating, begin, "^ *##"); 3316 3317 -- Named begin required for packages unless they have no 3318 -- declaration, and subprograms if they have nested units 3319 check comments (unnamed_begin, declaration package); 3320 check comments (unnamed_begin, program_unit procedure); 3321 check comments (unnamed_begin, program_unit function); 3322 33235.9.3 Tips 3324---------- 3325 3326Remember that a Regexp matches if the pattern matches any part of the 3327identifier. Use "^" and "$" to match the beginning (resp. end) of the 3328comment, or both. 3329 33305.9.4 Limitations 3331----------------- 3332 3333This rule does not support wide characters outside the basic Latin-1 3334set. 3335 3336 3337File: adacontrol_ug.info, Node: Declarations, Next: Default_Parameter, Prev: Comments, Up: Rules reference 3338 33395.10 Declarations 3340================= 3341 3342This rule controls usage of various kinds of declarations, possibly only 3343those occurring at specified locations. 3344 33455.10.1 Syntax 3346------------- 3347 3348 <control_kind> declarations (<subrule> {, <subrule>}); 3349 <subrule> ::= {[not] <location_kw>} <declaration_kw> 3350 <location_kw> ::= all | block | library | local | nested | 3351 own | private | public | in_generic | task_body 3352 <declaration_kw> ::= 3353 any_declaration | abstract_function | 3354 abstract_operator | abstract_procedure | 3355 abstract_type | access_all_type | 3356 access_constant_type | access_constrained_array_type | 3357 access_def_discriminated_type | access_formal_Type | 3358 access_language_type | access_nondef_discriminated_type | 3359 access_protected_type | access_subprogram_type | 3360 access_task_type | access_unconstrained_array_type | 3361 access_unknown_discriminated_type | access_type | 3362 aliased_array_component | aliased_constant | 3363 aliased_protected_component | aliased_record_component | 3364 aliased_variable | anonymous_access_component | 3365 anonymous_access_constant | anonymous_access_discriminant | 3366 anonymous_access_parameter | anonymous_access_variable | 3367 anonymous_subtype_allocator | anonymous_subtype_case | 3368 anonymous_subtype_declaration | anonymous_subtype_for | 3369 anonymous_subtype_indexing | array | 3370 array_type | binary_modular_type | 3371 box_defaulted_formal_function | box_defaulted_formal_procedure | 3372 character_literal | child_unit | 3373 class_wide_constant | class_wide_variable | 3374 constant | constrained_array_constant | 3375 constrained_array_type | constrained_array_variable | 3376 controlled_type | decimal_fixed_type | 3377 defaulted_discriminant | defaulted_generic_parameter | 3378 defaulted_parameter | deferred_constant | 3379 derived_type | discriminant | 3380 empty_private_part | empty_visible_part | 3381 enumeration_type | entry | 3382 equality_operator | exception | 3383 expression_function | extension | 3384 fixed_type | float_type | 3385 formal_function | formal_package | 3386 formal_procedure | formal_type | 3387 function | function_call_renaming | 3388 function_instantiation | generic | 3389 generic_function | generic_package | 3390 generic_procedure | handlers | 3391 incomplete_type | in_out_generic_parameter | 3392 in_out_parameter | initialized_protected_component | 3393 initialized_record_component | initialized_variable | 3394 instantiation | integer_type | 3395 interface_type | library_unit_renaming | 3396 limited_private_type | modular_type | 3397 multiple_names | multiple_protected_entries | 3398 name_defaulted_formal_function | name_defaulted_formal_procedure | 3399 named_number | non_binary_modular_type | 3400 non_identical_operator_renaming | non_identical_renaming | 3401 non_joint_ce_ne_handler | non_limited_private_type | 3402 non_ravenscar_task | not_operator_renaming | 3403 null_defaulted_formal_procedure | null_extension | 3404 null_ordinary_record_type | null_procedure | 3405 null_procedure_body | null_procedure_declaration | 3406 null_tagged_type | operator | 3407 operator_renaming | ordinary_fixed_type | 3408 ordinary_fixed_type_no_small | ordinary_fixed_type_with_small | 3409 ordinary_record_type | ordinary_record_variable | 3410 out_parameter | package | 3411 package_instantiation | package_statements | 3412 predefined_operator | private_extension | 3413 procedure | procedure_instantiation | 3414 protected | protected_discriminant | 3415 protected_entry | protected_type | 3416 protected_variable | record_type | 3417 relay_function | relay_package | 3418 relay_procedure | renaming | 3419 renaming_as_body | renaming_as_declaration | 3420 scalar_variable | self_calling_function | 3421 self_calling_procedure | separate | 3422 signed_type | single_array | 3423 single_protected | single_task | 3424 subtype | synonym_renaming | 3425 tagged_incomplete_type | tagged_private_type | 3426 tagged_type | tagged_variable | 3427 task | task_discriminant | 3428 task_entry | task_type | 3429 task_variable | type | 3430 unconstrained_array_constant | unconstrained_array_type | 3431 unconstrained_array_variable | unconstrained_subtype | 3432 uninitialized_protected_component | uninitialized_record_component | 3433 uninitialized_variable | unknown_discriminant | 3434 variable | variant_part 3435 34365.10.2 Action 3437------------- 3438 3439The <location_kw> restricts the places where the occurrence of the 3440declaration is controlled. If it is preceded by "not", the declaration 3441is controlled except at this location. Several <location_kw> can be 3442given, in which case the declaration is controlled at places where all 3443the keywords apply. If there is no <location_kw>, it is assumed to be 3444"all". 3445 * 'all': puts no special restriction to the location. This keyword 3446 can be specified for readability purposes, and if specified must 3447 appear alone (not with other <location_kw>), and "not" is not 3448 allowed. 3449 * 'block': only declarations appearing in block statements are 3450 controlled. 3451 * 'library': only library level declarations are controlled. 3452 * 'local': only local declarations are controlled (i.e. only 3453 declarations appearing in (generic) packages, possibly nested, are 3454 allowed). 3455 * 'own': only declarations that are local to a (generic) package body 3456 are controlled. 3457 * 'public': only declarations appearing in the visible part of 3458 (generic) packages are controlled. 3459 * 'private': only declarations appearing directly in a private part 3460 are controlled. 3461 * 'in_generic': only declarations appearing directly or indirectly in 3462 a generic specification or body are controlled. 3463 * 'task_body': only declarations appearing directly in a task body 3464 are controlled. Note that it would not make sense to have a 3465 <location_kw> for task specifications, since only entries can 3466 appear there, and they cannot appear anywhere else. 3467 3468 The <declaration_kw> specifies what kind of declaration to control: 3469 * Declaration keywords that are Ada keywords match the corresponding 3470 Ada declarations. 3471 * 'any_declaration' controls all declarations. This is of course not 3472 intended to forbid all declarations in a program (!), but 3473 _counting_ all declarations can be quite useful. 3474 * 'abstract_function', 'abstract_operator', and 'abstract_procedure' 3475 control the declarations of abstract functions, abstract operators, 3476 and abstract procedures, respectively. 3477 * 'abstract_type' controls the declaration of non-formal abstract 3478 types. 3479 * 'access_type' controls all access type declarations, while 3480 'access_subprogram_type', 'access_protected_type', and 3481 'access_task_type' control only access to procedures or functions, 3482 access to protected types, or access to task types, respectively. 3483 Similarly, 'access_constrained_array_type' and 3484 'access_unconstrained_array_type' control access to constrained or 3485 unconstrained array types, 'access_def_discriminated_type', 3486 'access_nondef_discriminated_type', and 3487 'access_unknown_discriminated_type' control access to types with 3488 discriminants with default values, without default values, and 3489 unknown discriminants, respectively. 'access_formal_type' controls 3490 access to (generic) formal types, 'access_all_type' control 3491 generalized access to variables types (aka "'access all T'", and 3492 'access_constant_type' control generalized access to constants 3493 types (aka "'access constant T'"). 'access_language_type' controls 3494 access to language defined private types. 3495 * 'aliased_variable' and 'aliased_constant' control the declarations 3496 of aliased variables or constants, respectively. 3497 * 'aliased_array_component' controls the declaration of arrays (array 3498 types or single arrays) whose components are declared aliased. 3499 * 'aliased_record_component' and 'aliased_protected_component' 3500 control the declarations of aliased record (respectively protected) 3501 components. 3502 * 'anonymous_access_component' controls array and record components 3503 that are of an anonymous access type (but not discriminants, which 3504 are controlled by 'anonymous_access_discriminant'). Similarly, 3505 'anonymous_access_constant' and 'anonymous_access_variable' control 3506 constants and variables that are of an anonymous access type 3507 (including generic formal 'in' and 'in out' parameters, 3508 respectively). 'anonymous_access_parameter' controls subprogram 3509 parameters that are of an anonymous access type, the only ones that 3510 existed in Ada 95. Note that to avoid unnecessary messages, if a 3511 subprogram has an explicit specification, the message for 3512 'anonymous_access_parameter' is given on the specification and not 3513 repeated on the body. 3514 * 'anonymous_subtype_declaration' controls the declarations of 3515 anonymous subtypes and ranges that are part of some other 3516 declaration. Similarly, 'anonymous_subtype_allocator', 3517 'anonymous_subtype_case', 'anonymous_subtype_for', and 3518 'anonymous_subtype_indexing' control anonymous subtype declarations 3519 and ranges that are part of allocators, 'case' statements (ranges 3520 in the 'when' path), 'for' loop statements, and indexing of slices 3521 or array aggregates, respectively. 3522 * 'array' controls all array definitions (array types and single 3523 arrays), while 'array_type' controls only array types and 3524 'single_array' controls only single arrays (objects of an anonymous 3525 array type). 'constrained_array_type' controls only constrained 3526 array types, while 'unconstrained_array_type' controls only 3527 unconstrained array types. 'constrained_array_variable' controls 3528 variable declarations where the given (or anonymous) array type is 3529 constrained, while 'unconstrained_array variable' controls variable 3530 declarations where the given (or anonymous) array type is 3531 unconstrained (and the constraint is provided by the initial 3532 value). 'constrained_array_constant' and 3533 'unconstrained_array_constant' do the same with constants instead 3534 of variables. 3535 * 'character_literal' controls the declaration of new character 3536 literals, i.e. character literals defined as part of the values of 3537 an enumeration type. 3538 * 'child_unit' controls the declaration of all child units. 3539 * 'constant' controls all constants, while 'class_wide_constant' 3540 control the declaration of constants of a class-wide type, and 3541 'deferred_constant' controls the declaration of deferred constants. 3542 * 'controlled_type' controls the declaration of controlled types, 3543 i.e. descendants of 'Ada.Finalization.Controlled' or 3544 'Ada.Finalization.Limited_Controlled'. Note that this includes 3545 also private types that are not visibly controlled. 3546 * 'defaulted_parameter' controls subprogram or entry (in) parameters 3547 that provide a default value, while 'defaulted_generic_parameter' 3548 controls generic formal objects that provide a default value. 3549 * 'derived_type' controls regular derived types, but not type 3550 extensions (derivations of tagged types). These are controlled by 3551 'extension' and 'private_extension'. 3552 * 'discriminant' controls all declarations of types with 3553 discriminants, while 'protected_discriminant' and 3554 'task_discriminant' control only discriminants of protected types 3555 and task types, respectively. 'defaulted_discriminants' controls 3556 only discriminants where default values are provided. 3557 'unknown_discriminants' controls only unknown discriminants (AKA 3558 "'(<>)'" discriminants). 3559 * 'empty_private_part' controls package specification with an empty 3560 private part, i.e. where the word 'private' appears, but the 3561 private part contains no declaration (even if it contains pragmas). 3562 * 'empty_visible_part' controls package specifications that contain 3563 no declaration in the visible part (before the word 'private' if 3564 any), even if it contains pragmas. 3565 * 'enumeration_type' controls the declaration of enumeration types. 3566 * 'exception' controls exception declarations. 3567 * 'expression_function' controls declaration of expression functions 3568 * 'extension' controls type extensions, i.e. derivations from a 3569 tagged type with a 'with record' extension part. 3570 * 'fixed_type' controls all declarations of fixed point types while 3571 'ordinary_fixed_type' controls only ordinary (binary) fixed point 3572 types, 'ordinary_fixed_type_no_small' controls ordinary fixed point 3573 type without a representation clause for ''SMALL', 3574 'ordinary_fixed_type_with_small' controls ordinary fixed point type 3575 with an explicit representation clause for ''SMALL', and 3576 'decimal_fixed_type' controls only decimal fixed point types (those 3577 can never have a representation clause for ''SMALL'). 3578 * 'float_type' controls declarations of floating point types. 3579 * 'formal_function', 'formal_package', 'formal_procedure', and 3580 'formal_type' control all generic formal functions, packages, 3581 procedures, and types, respectively. 3582 'box_defaulted_formal_function', 'box_defaulted_formal_procedure', 3583 'name_defaulted_formal_function', 3584 'name_defaulted_formal_procedure', and 3585 'null_defaulted_formal_procedure' control generic formal functions 3586 and procedures with a box default, a name default, and a null 3587 default, respectively. 3588 * 'generic_function', 'generic_package', 'generic_procedure' control 3589 generic function (respectively package, procedure) declarations. 3590 * 'handlers' controls the presence of exception handlers in any 3591 handled sequence of statements. 3592 * 'in_out_parameter' and 'out_parameter' control subprogram and entry 3593 parameters of modes 'in' 'out' and 'out' (respectively), while 3594 'in_out_generic_parameter' and 'out_generic_parameter' do the same 3595 for generic formal parameters. Note that to avoid unnecessary 3596 messages, if a subprogram has an explicit specification, the 3597 message is given on the specification and not repeated on the body. 3598 * 'incomplete_type' controls (regular) incomplete type declarations, 3599 while 'tagged_incomplete_type' controls tagged incomplete type 3600 declarations (Ada 2005). 3601 * 'initialized_variable' controls variable declarations that include 3602 an initialization expression, unless they are of a class-wide type 3603 since initialization is required in that case. 3604 * 'instantiation' controls all instantiations, while 3605 'function_instantiation', 'package_instantiation', 3606 'procedure_instantiation' control function (respectively package, 3607 procedure) instantiations. 3608 * 'integer_type' controls all declarations of integer types, while 3609 'signed_type' controls only signed integer types, and 3610 'modular_type' controls only modular types (both kinds); 3611 'binary_modular_type' controls only modular types whose modulus is 3612 a power of 2, and 'non_binary_modular_type' controls only modular 3613 types whose modulus is not a power of 2. 3614 * 'initialized_record_component' and 3615 'initialized_protected_component' control the declaration of record 3616 (respectively protected) component that include a default 3617 initialization, while 'uninitialized_record_component' and 3618 'uninitialized_protected_component' control the declaration of 3619 record (respectively protected) component that do not include a 3620 default initialization, unless they are of a limited type since 3621 initialization would not be allowed in that case. 3622 * 'limited_private_type' controls limited private type declarations, 3623 while 'non_limited_private_type' controls regular (non limited) 3624 private type declarations. 'tagged_private_type' controls tagged 3625 private type declarations. 3626 * 'multiple_names' controls declarations where more than one defining 3627 identifier is given in the same declaration. 3628 * 'multiple_protected_entries' controls protected definitions (from 3629 protected types or single protected objects) that have more than 3630 one entry declaration. Note that a protected definition with a 3631 single entry family declaration is counted as a single entry 3632 declaration. 3633 * 'named_number' controls declarations of named numbers, i.e. 3634 untyped constants. 3635 * 'non_joint_CE_NE_handler' controls exception handlers whose choices 3636 include 'Constraint_Error' or 'Numeric_Error', but not both. This 3637 is intended for legacy Ada 83 code that required to always handle 3638 these exceptions together; it makes little sense for Ada95 or 3639 Ada2005 code (and to be honnest, this subrule is provided because 3640 Gnatcheck has it). 3641 * 'null_extension' controls record extensions (derived tagged types) 3642 that contain no new elements. Similarly, 3643 'null_ordinary_record_type' and 'null_tagged_type' control ordinary 3644 records and tagged types that contain no elements. Note that the 3645 record definitions may be plain "'null' 'record'" definitions, or 3646 full record definitions that contain only null components. 3647 However, a definition is not considered null if it contains a 3648 variant part. 3649 * 'null_procedure_body' controls procedure declarations whose 3650 sequence of statements contain only 'null' statements (or blocks 3651 without declarations and containing only 'null' statements). 3652 'null_procedure_declaration' controls Ada2005 null procedure 3653 declarations (i.e., "procedure P is null;"). 'null_procedure' 3654 controls both. 3655 * 'operator' controls the definition of operators (things like 3656 '"+"'); note that the message is given on the specification if 3657 there is an explicit specification, on the body otherwise. 3658 'equality_operator' controls only equality operators ('"="' and 3659 '"/="') and 'predefined_operator' controls only operator 3660 definitions that overload a predefined operator (like '"+"' on a 3661 numeric type, for example). 3662 * 'package_statements' controls the presence of elaboration 3663 statements in the bodies of packages (or generic packages). 3664 * 'private_extension' controls private extensions, i.e. derivations 3665 from a tagged type with a 'with private' extension part. 3666 * 'record_type' controls all record type declarations (tagged or 3667 not), while 'ordinary_record_type' controls only non-tagged record 3668 types, and 'tagged_type' controls only tagged record types. 3669 * 'interface_type' controls interface type declarations. 3670 * 'relay_function' controls functions whose statement part includes 3671 only a single 'return' statement whose expression is another 3672 function call; similarly, 'relay_procedure' controls procedures 3673 whose statement part includes only a call to another procedure, and 3674 'relay_package' controls packages whose visible part includes only 3675 the declaration of another package (regular package, instantiation 3676 of a generic package, or renaming of package). 3677 * 'renaming' controls all renaming declarations, while 3678 'renaming_as_body' controls only those that are renamings as bodies 3679 of subprograms, 'renaming_as_declaration' controls only those that 3680 are regular renamings of subprograms (i.e. not as bodies), 3681 'operator_renaming' controls only those that are renamings of an 3682 operator, 'not_operator_renaming' controls only those that are 3683 _not_ renamings of an operator, 'function_call_renaming' controls 3684 renaming of the result of a function call, and 3685 'library_unit_renaming' controls renaming of library units. 3686 'non_identical_renaming' controls only renamings where the new name 3687 and the old name are not the same, and 3688 'non_identical_operator_renaming' does the same, but only for 3689 renamings of operators. 'synonym_renaming' controls renamings 3690 declared in the same declarative part as the entity being renamed 3691 (these serve no purpose as far as visibility is concerned, and are 3692 thus pure synonyms). 3693 * 'self_calling_function' controls functions whose body contains only 3694 a single (simple) 'return' statement, and the return expression is 3695 a (recursive) call to the same function. Similarly, 3696 'self_calling_procedure' controls procedures whose body contains 3697 only a single statement which is a (recursive) call to the same 3698 procedure. Note that this corresponds to bodies automatically 3699 generated by gnatstub. 3700 * 'subtype' controls all explicit subtype declarations (i.e. not all 3701 anonymous subtypes that appear at various places in the language), 3702 while 'unconstrained_subtype' controls only the subtype 3703 declarations that do not include a constraint. 3704 * 'task' controls task type declarations as well as single tasks 3705 declarations while 'single_task' and 'task_type' control only 3706 single task declarations or task type declarations respectively 3707 (and similarly for 'protected'). 'non_ravenscar_task' controls all 3708 task type and task object declarations from a unit to which no 3709 'pragma Profile (Ravenscar)' applies. 3710 * 'type' controls all type (but not subtype) declarations. 3711 * 'uninitialized_variable' controls variable declarations that do not 3712 include an initialization expression. Depending on the value of 3713 the rule variable "limited_initialization" (see below), variables 3714 of a limited type, or only variables of a task or protected type, 3715 are not reported, since initialization would not be allowed in that 3716 case. 3717 * 'variable' controls all variable declarations. 'scalar_variable' 3718 controls the declarations of variables of a scalar type (integer, 3719 enumeration, float, fixed). 'ordinary_record_variable' controls 3720 declarations of variables of an untagged record type. 3721 'tagged_variable' controls declarations of variables of a tagged 3722 type (including class-wide ones), while 'class_wide_variable' 3723 controls only the declarations of variables of a class-wide type. 3724 'task_variable' and 'protected_variable' control task and protected 3725 objects (respectively), whether given with a named or anonymous 3726 type. 3727 * 'variant_part' controls variant parts in record defintions. 3728 3729 Ex: 3730 -- No task, no exception: 3731 search declarations (task, exception); 3732 3733 -- Don't declare subprograms or packages inside a block: 3734 check declarations (block procedure, block function, block package); 3735 3736 -- No task in the public part of a package: 3737 check declarations (public task); 3738 3739 -- Generics allowed only as top-level units 3740 check declarations (not library generic); 3741 37425.10.3 Variable 3743--------------- 3744 3745The rule provides a variable that allows to adjust the handling of 3746limited types for the subrule "uninitialized_variable". Initialization 3747of variables of a limited time was not permitted until Ada 2005. 3748 3749Variable Values Default Effect 3750Limited_Initializationoff/onoff if "off", uninitialized variables of a 3751 limited type are never reported; if 3752 "on", they are reported like 3753 non-limited variables, unless they are 3754 of a task or protected type, since no 3755 initialization would be allowed in 3756 that case. 3757 37585.10.4 Tips 3759----------- 3760 3761Certain keywords are not exclusive, and it may be the case that several 3762keywords apply to the same declaration; in this case, they are all 3763reported. For example, if you specify: 3764 check declarations (record_type, tagged_type); 3765 tagged types will be reported both as "record_type" and 3766"tagged_type". 3767 3768 There is no subrule for checking functions whose result type is from 3769an anonymous access type; these are controlled by the rule 'return_type 3770(anonymous_access)'. *Note Return_Type::. 3771 3772 Some of the keyword do not seem very useful; it would be strange to 3773have a programming rule that prevents all type declarations... But bear 3774in mind that the <location_kw> can be used to restrict the check to 3775certain locations; moreover, AdaControl can be used not only for 3776checking, but also for searching; finding all type declarations in a set 3777of units can make sense. As another example, "search declarations (own 3778variable);" will find all variables declared directly in package bodies. 3779 3780 Some modifiers do not make sense with certain declarations; for 3781example, a "private out_parameter" is impossible (a parameter occurs in 3782a subprogram declaration, not directly in a private part). This is not 3783a problem as far as the rule is concerned, but don't expect to find 3784any... 3785 3786 Generally, discriminants are considered components of record types. 3787However, discriminants of an anonymous access type (so-called access 3788discriminants) play such a special role in the language that they 3789deserved their own control ('anonymous_access_discriminant'). 3790 3791 Private types are normally followed in determining the kind of access 3792type (i.e., an access to a private type will be controlled according to 3793the full declaration). However, this is not done for an access type 3794that designates a private type defined in a language defined unit (since 3795the full type depends on the implementation); these are controlled as 3796"access_language_type" instead. Of course, language defined visible 3797types are controlled normally. 3798 37995.10.5 Limitation 3800----------------- 3801 3802In some rare cases, AdaControl may not be able to evaluate the modulus 3803of a modular type definition, thus preventing correct operation of 3804"binary_modular_type" and "non_binary_modular_type" subrules. Such 3805cases are detected by the rule "uncheckable". *Note Uncheckable::. 3806 3807 3808File: adacontrol_ug.info, Node: Default_Parameter, Next: Dependencies, Prev: Declarations, Up: Rules reference 3809 38105.11 Default_Parameter 3811====================== 3812 3813This rule checks usage (or non-usage) of defaulted parameters. 3814 38155.11.1 Syntax 3816------------- 3817 3818 <control_kind> default_parameter (<place>, <formal>, <usage>); 3819 <place> ::= <entity> | calls | instantiations 3820 <formal> ::= <formal name> | all 3821 <usage> ::= used | positional | not_used 3822 38235.11.2 Action 3824------------- 3825 3826The rule controls subprogram calls or generic instantiations that use 3827the default value for the indicated parameter, or conversely don't use 3828it, either in positional notation or in any notation. If a subprogram 3829is called, or a generic instantiated, whose name matches <entity>, and 3830it has a formal whose name is <formal name>, then: 3831 * If the string 'used' (case irrelevant) is given as the third 3832 parameter, the rule reports when there is no corresponding actual 3833 parameter (i.e. the default value is used for the parameter). 3834 * If the string 'positional' (case irrelevant) is given as the third 3835 parameter, the rule reports when there is an explicit corresponding 3836 actual parameter (i.e. the default is not used for the parameter), 3837 and the actual uses positional (not named) notation. 3838 * If the string 'not_used' (case irrelevant) is given as the third 3839 parameter, the rule reports when there is an explicit corresponding 3840 actual parameter (i.e. the default is not used for the parameter), 3841 independently of whether it uses positional or named notation. 3842 3843 As usual, the whole syntax for entities is allowed for <entity>. 3844*Note Specifying an Ada entity name::. On the other hand, <formal> is 3845the simple name of the formal parameter. 3846 3847 Alternatively, the <entity> can be specified as 'calls', to control 3848all calls or 'instantiations', to control all instantiations. The 3849<formal name> can be replaced by 'all', in which case all formals are 3850controlled. 3851 3852 Ex: 3853 check default_parameter (P, X, used); 3854 check default_parameter (P, Y, not used); 3855 search default_parameter (calls, all, positional); 3856 38575.11.3 Tip 3858---------- 3859 3860If the <entity> is a generic subprogram, it is also possible to give a 3861formal parameter (a parameter of the subprogram, not a generic 3862parameter) as the <formal name>; in this case, all instantiations of the 3863indicated generic subprogram will be controlled for the use of the 3864indicated parameter. 3865 3866 3867File: adacontrol_ug.info, Node: Dependencies, Next: Derivations, Prev: Default_Parameter, Up: Rules reference 3868 38695.12 Dependencies 3870================= 3871 3872This rule controls dependencies of units (i.e. 'with' clauses, parents, 3873child units...), either according to a set of allowed/forbidden units, 3874or by count. 3875 38765.12.1 Syntax 3877------------- 3878 3879 <control_kind> dependencies (others, <unit> {,<unit>}); 3880 <control_kind> dependencies (with, <unit> {,<unit>}); 3881 <control_kind> dependencies (public_child | private_child); 3882 <control_kind> dependencies (<counter>, <bound> [, <bound>]); 3883 <counter> ::= raw | direct | parent 3884 <bound> ::= min | max <value> 3885 38865.12.2 Action 3887------------- 3888 3889The kind of action depends on the specified subrule. 3890 3891 The "others" subrule controls semantic dependencies to units other 3892than those indicated. This subrule can be specified only once, and at 3893least one unit must be given. 3894 3895 The "with" subrule controls with clauses that reference the indicated 3896units. At least one unit must be given. 3897 3898 Note that for these two rules, renamings are followed: if you give 3899the basic name of a unit, it will be identified even if used with other 3900names. Similarly, if you give the name of a generic, all of its 3901instantiations will also be controlled. 3902 3903 "public_child" and "private_child" control units that depend on their 3904own public (respectively private) child units. Since these subrules 3905have no parameters, they can be given only once. 3906 3907 Other subrules control that the number of various dependencies is 3908whithin a specified range. The second (and optionnally third) parameter 3909give the minimum and/or maximum allowed values (i.e. the rule will 3910control values outside the indicated interval). If not specified, the 3911minimum value is defaulted to 0 and the maximum value to infinity. 3912 * "raw" controls the number of units textually given in 'with' 3913 clauses. Redundant 'with' clauses are counted, and a child unit 3914 counts for one. 3915 * "direct" controls the number of different units that this unit 3916 really depends on: if a unit is mentionned in several 'with' 3917 clauses, it is counted only once, but if a child unit is 3918 mentionned, all parents of this child unit are added to the count. 3919 * "parent" counts the number of parents of the current unit. A root 3920 unit has no parent, a child of a root unit has one parent, etc. 3921 3922 Ex: 3923 check dependencies (others, Ada.Text_IO); 3924 check dependencies (raw, max 15); 3925 3926 -- child units should not be nested more than 5 levels: 3927 check dependencies (parent, max 5); 3928 3929 -- units that depend on nothing: 3930 search dependencies (direct, min 1); 3931 3932 -- units that depend on their public children: 3933 check dependencies (public_child); 3934 39355.12.3 Tips 3936----------- 3937 3938If you give a name that's already a renaming to the "others" or "with" 3939subrules, the rule will only apply to this name, not to what has been 3940renamed. Therefore: 3941 -- Allow only Ada.Text_IO: 3942 check dependencies (others, Ada.Text_IO); 3943 3944 -- But not if the plain name Text_IO is used: 3945 check dependencies (with, Text_IO); 3946 3947 The notion of public or private for the rules "public_child" or 3948"private_child" refer to the real unit, which is not necessarily the 3949name used in the with clause, if for example you have a private library 3950renaming of a public unit. 3951 3952 There is a slight overlap between this rule and the rule "entities'. 3953But "entities" will find all uses of an entity (not necessarily a 3954compilation unit), while "dependencies" will control occurrences only of 3955compilation units, and only in 'with' clauses. *Note Entities::. 3956 3957 In certain contexts, only a set of the Ada predefined units is 3958allowed. For example, it can be useful to forbid units defined in 3959special needs annexes. The 'rules' directory of Adacontrol contains 3960files with "Dependencies" rules that forbid the use of various 3961predefined Ada units. Comment out the lines for the units that you want 3962to allow. You can then simply "source" these files from your own rule 3963file (or copy the content) if you want to disallow these units. *Note 3964Rules files provided with AdaControl::. 3965 3966 3967File: adacontrol_ug.info, Node: Derivations, Next: Directly_Accessed_Globals, Prev: Dependencies, Up: Rules reference 3968 39695.13 Derivations 3970================ 3971 3972This rule controls various properties of the declaration of derived 3973types. 3974 39755.13.1 Syntax 3976------------- 3977 3978 <control_kind> derivations (from, <entity>|<category> {, <entity>|<category>}) 3979 <control_kind> derivations (max_parents, <value>) 3980 <category> ::= () | access | array | delta | digits | mod | 3981 private | protected | range | record | tagged | task 3982 39835.13.2 Action 3984------------- 3985 3986The "from" subrule controls derivations according to the parent type. 3987 3988 If <entity> is a type name, it controls types that are derived 3989(directly or indirectly) from the given type, or one of its subtypes; 3990however, if it is a subtype name, only types that are derived (directly 3991or indirectly) from the given subtype are controlled. If <entity> is 3992the name of a compilation unit, it controls types that are derived 3993(directly or indirectly) from a type (or subtype) declared inside the 3994given unit. As usual, the whole syntax for entities is allowed for 3995<entity>. *Note Specifying an Ada entity name::. 3996 3997 If <category> is given, it controls derived types that belong to the 3998corresponding category. The meaning of <category> is: 3999 * "()": The parent is of an enumerated type. 4000 * "access": The parent is of an access type. 4001 * "array": The parent is of an array type. 4002 * "delta": The parent is of a fixed point type (it is not currently 4003 possible to distinguish ordinary fixed point types from decimal 4004 fixed point types). 4005 * "digits": The parent is of a floating point type. 4006 * "mod": The parent is of a modular type. 4007 * "private": The parent is of a private type (including private 4008 extensions). 4009 * "protected": The parent is of a protected type. 4010 * "range": The parent is of a signed integer type. 4011 * "record": The parent is of an (untagged) record type. 4012 * "tagged": The parent is of a tagged type (including type 4013 extensions). 4014 * "task": The parent is of a task type. 4015 4016 It may be the case that several controls apply to a given derived 4017type. In this case, the message corresponds to the most specific 4018control, according to the following priority order: 4019 1. Specific subtype 4020 2. Specific type 4021 3. Type or subtype from a compilation unit 4022 4. Category 4023 4024 Ex: 4025 check derivations (from, Standard.Integer); -- Types derived from Integer 4026 search derivations (from, range); -- Types derived from an integer type, except 4027 -- Standard.Integer (caught above) 4028 search derivations (from, standard); -- Types derived from a type in Standard, except 4029 -- Standard.Integer (caught above) 4030 4031 The "max_parents" subrule controls the maximum number of parents in a 4032derivation. The parents are the direct ancestor in a derived type 4033definition, plus all of the progenitors (the interfaces that are 4034implemented by the type). <n> is the maximum number of allowed parents, 4035i.e. the rule is triggered if the number of parents is strictly greater 4036than <n>. 4037 4038 This subrule can be given once for each of check, search, and count. 4039This way, it is possible to have a number of parents considered a 4040warning (search), and one considered an error (check). Of course, this 4041makes sense only if the number for search is less than the one for 4042check. 4043 4044 check derivations (max_parents, 5); -- error if more than 5 parents 4045 search derivations (max_parents, 3); -- warning if more than 3 parents 4046 40475.13.3 Limitations 4048------------------ 4049 4050Currently, the "from" subrule controls only parent types, progenitors 4051are ignored. This limitation will be removed in future versions. 4052 4053 4054File: adacontrol_ug.info, Node: Directly_Accessed_Globals, Next: Duplicate_Initialization_Calls, Prev: Derivations, Up: Rules reference 4055 40565.14 Directly_Accessed_Globals 4057============================== 4058 4059This rule checks that global variables in package bodies are accessed 4060only through dedicated subprograms. Especially, it can be used to 4061prevent race conditions in multi-tasking programs. 4062 40635.14.1 Syntax 4064------------- 4065 4066 <control_kind> directly_accessed_globals [(<kind> {,<kind>})]; 4067 <kind> ::= plain | accept | protected 4068 40695.14.2 Action 4070------------- 4071 4072The rule controls global variables declared directly in (generic) 4073package bodies that are accessed outside of dedicated callable entities 4074(i.e. procedure or function, possibly protected, protected entries, and 4075'accept' statements). 4076 4077 This rule can be specified only once. The parameters indicate which 4078kinds of callable entity are allowed: "plain" for non-protected 4079subprograms, "protected" for protected subprograms, and "accept" for 4080'accept' statements). Without parameters, all forms are allowed. 4081 4082 More precisely, the rule ensures that the global variables are read 4083from a single callable entity, and written by a single callable entity. 4084Note that the same callable entity can read and write a variable, but in 4085this case no other callable entity is allowed to read or write the 4086variable. 4087 * Subprograms used to read/write the variables must be declared at 4088 the same level as the variable itself (i.e. not nested), and must 4089 not be generic. 4090 * Protected subprograms used to read/write the variables must both be 4091 part of the same single protected object, which must be declared at 4092 the same level as the variable itself (i.e. not nested); they are 4093 not allowed to be declared in a protected type, since if there are 4094 several protected objects of the same type, mutual exclusion would 4095 not be enforced. 4096 * 'accept' statements used to read/write the variables must both be 4097 part of the same single task object, which must be declared at the 4098 same level as the variable itself (i.e. not nested); they are not 4099 allowed to be declared in a task type, since if there are several 4100 task objects of the same type, mutual exclusion would not be 4101 enforced. 4102 In short, this rule enforces that all global variables are accessed 4103by dedicated access subprograms, and that only those subprograms access 4104the variables directly. If given with the keyword "protected" and/or 4105"accept", it enforces that global variables are accessed only by 4106dedicated protected subprograms or tasks, ensuring that no race 4107condition is possible. 4108 4109 Ex: 4110 check directly_accessed_globals 4111 41125.14.3 Tips 4113----------- 4114 4115Note that this rule controls global variables from package bodies, not 4116those from the specification. This is intended, since it makes little 4117sense to declare a variable in a specification, and then require it not 4118to be accessed directly, but through provided subprograms. Obviously, 4119in this case the variable should be moved to the body. 4120 4121 Note that AdaControl can check that no variable is declared in a 4122package specification with the following rule: 4123 check usage (variable, from_spec); 4124 *note Usage:: for details. 4125 41265.14.4 Limitations 4127------------------ 4128 4129AdaControl cannot check entities accessed through dynamic names (dynamic 4130renaming, access on aliased variables). Use of such constructs is 4131detected by the rule "uncheckable". *Note Uncheckable::. 4132 4133 Due to a weakness in the ASIS standard, it is not possible to know 4134the mode (in, out) of variables used as parameters of dispatching calls. 4135Such variables are considered to be read and written at the point of the 4136call, therefore possibly creating false positives (which is safer than 4137false negatives). Use of such constructs is detected by the rule 4138"uncheckable". *Note Uncheckable::. 4139 4140 4141File: adacontrol_ug.info, Node: Duplicate_Initialization_Calls, Next: Entities, Prev: Directly_Accessed_Globals, Up: Rules reference 4142 41435.15 Duplicate_Initialization_Calls 4144=================================== 4145 4146This rule checks that some procedures (notably initialization 4147procedures) are not called several times in identical conditions. 4148 41495.15.1 Syntax 4150------------- 4151 4152 <control_kind> duplicate_initialization_calls (<entity> {, <entity>}); 4153 41545.15.2 Action 4155------------- 4156 4157This rule controls calls to initialization procedures that are 4158duplicated. The <entity> parameters are the initialization procedures 4159to be controlled. As usual, the whole syntax for entities is allowed 4160for <entity>. *Note Specifying an Ada entity name::. 4161 4162 More precisely, the initialization procedures must follow one of 4163these patterns: 4164 * The procedure only has 'in' parameters. All actual parameters used 4165 in calls are static, and not two calls have the same values for all 4166 parameters. 4167 * The procedure has exactly one 'out' parameter (and no 'in out' 4168 parameter). Not two calls refer the same actual variable for the 4169 'out' parameter. 4170 4171 The rule controls any violation of these patterns. If a procedure 4172passed as parameter does not have a profile that corresponds to one of 4173the above patterns, it is an error. 4174 4175 Ex: 4176 check duplicate_initialization_calls (pack.init_proc); 4177 41785.15.3 Limitation 4179----------------- 4180 4181If a variable passed as an 'out' parameter is not statically 4182determinable, it is not controlled by the rule. Such a case is detected 4183by the rule "uncheckable". *Note Uncheckable::. 4184 4185 4186File: adacontrol_ug.info, Node: Entities, Next: Entity_Inside_Exception, Prev: Duplicate_Initialization_Calls, Up: Rules reference 4187 41885.16 Entities 4189============= 4190 4191This rule is used to control usage of Ada entities, i.e. any declared 4192element (type, variables, packages, etc). 4193 41945.16.1 Syntax 4195------------- 4196 4197 <control_kind> entities ({[not] <location>} [instance] <entity> 4198 {, {[not] <location>} [instance] <entity>}); 4199 <location> ::= block | library | local | nested | own | 4200 private | public | in_generic | task_body 4201 4202 42035.16.2 Action 4204------------- 4205 4206This rule controls all uses of the indicated entities,or only those that 4207appear within the specified locations. As usual, the whole syntax for 4208entities is allowed for <entity>. *Note Specifying an Ada entity 4209name::. 4210 4211 When present, the <location_kw> restricts the places where the entity 4212is controlled. If it is preceded by "not", the entity is controlled 4213except at this location. Several <location_kw> can be given, in which 4214case the entity is controlled at places where all the keywords apply. 4215 * 'block': the entity appears in a block statement. 4216 * 'library': the entity appears at library level. 4217 * 'local': the entity appears in a local scope (i.e. not in 4218 (generic) packages, possibly nested) 4219 * 'own': the entity appers in a (generic) package body. 4220 * 'public': the entity appears in the visible part of a (generic) 4221 package. 4222 * 'private': the entity appears directly in a private part. 4223 * 'in_generic': the entity appears directly or indirectly in a 4224 generic specification or body. 4225 * 'task_body': the entity appears directly in a task body. 4226 4227 If the given entity is a generic unit or an entity declared inside a 4228generic unit, all corresponding uses in all instances will be reported. 4229Uses of the generic entity itself will also be reported normally, unless 4230the keyword 'instance' is given. 4231 4232 Note that this rules reports on the use of the entity, not the name: 4233if an entity has been renamed, it will be found under its various names. 4234 4235 Ex: 4236 search entities (Debug.Trace); 4237 check entities (Ada.Text_IO.Float_IO.Put); 4238 check entities (instance Ada.Unchecked_Conversion); 4239 The second line will report on any use of a 'Put' from any 4240instantiation of 'Float_IO'. The third one will report only on uses of 4241instances of 'Ada.Unchecked_Conversion'. 4242 42435.16.3 Tips 4244----------- 4245 4246This rule is safer than cross-references if you want to check where 4247certain entities are used, since it follows renamings but does not 4248report on homonyms of the intended entity. 4249 4250 This rule can also be used to check for all occurrences of certain 4251attributes with the "'all <Attribute>'" syntax. For example, the 4252following will report on any usage of ''Unchecked_Access': 4253 check entities (all 'Unchecked_Access); 4254 4255 If you want to make sure that certain compilation units are not used, 4256it is preferable to use the rule "Depencies (with,...)" rather than 4257"Entities", because "Entities" will control all uses of the unit, while 4258"Dependencies" will control only those in 'with' clauses (which is of 4259course sufficient). 4260 4261 In certain contexts, it can be useful to forbid certain entities, 4262like those from 'Standard', 'System', or entities defined in special 4263needs annexes packages. The 'rules' directory of Adacontrol contains 4264files with "Dependencies" and "Entities" rules that forbid the use of 4265various predefined Ada elements. Comment out the lines for the elements 4266that you want to allow. You can then simply "source" these files from 4267your own rule file (or copy the content) if you want to disallow these 4268elements. *Note Rules files provided with AdaControl::. 4269 42705.16.4 Limitation 4271----------------- 4272 4273GNAT defines 'Unchecked_Conversion' and 'Unchecked_Deallocation' as 4274separate entities, rather than renamings of 'Ada.Unchecked_Conversion' 4275and 'Ada.Unchecked_Deallocation'. As a consequence, it is necessary to 4276specify explicitely both forms if you want to make sure that the 4277corresponding generics are not used. 4278 4279 4280File: adacontrol_ug.info, Node: Entity_Inside_Exception, Next: Exception_Propagation, Prev: Entities, Up: Rules reference 4281 42825.17 Entity_Inside_Exception 4283============================ 4284 4285This rule controls entities that appear within exception handlers. 4286 42875.17.1 Syntax 4288------------- 4289 4290 <control_kind> entity_inside_exception (<spec> {, <spec>}); 4291 <spec> ::= [not] <entity> | calls | entry_calls 4292 42935.17.2 Action 4294------------- 4295 4296This rule controls exception handlers that contain references to one or 4297several Ada entities specified as parameters. If the keyword "calls" is 4298given, it stands for all subprogram and entry calls. If the keyword 4299"entry_calls" is given, it stands for all entry calls (task or 4300protected). If an <entity> (or "calls" or "entry_calls") is preceded by 4301the keyword "not", it is not included in the list of controlled entities 4302(i.e. the entity is allowed in the exception handler). This allows to 4303make exceptions to a more general specification of an entity, or to 4304allow calls to well-defined procedures if the keyword "calls" is given. 4305 4306 Ex: 4307 -- No Put_Line in exception handlers: 4308 check entity_inside_exception (ada.text_io.put_line); 4309 4310 -- No entry calls in exception handlers: 4311 check entity_inside_exception (entry_calls); 4312 4313 -- No calls allowed, except to the Report_Exception procedure: 4314 check entity_inside_exception (calls, not Reports.Report_Exception); 4315 4316 -- No Put allowed, except the one on Strings: 4317 check entity_inside_exception (all Put, 4318 not Ada.Text_IO.Put{Standard.String}); 4319 4320 4321File: adacontrol_ug.info, Node: Exception_Propagation, Next: Expressions, Prev: Entity_Inside_Exception, Up: Rules reference 4322 43235.18 Exception_Propagation 4324========================== 4325 4326This rule controls that certain program units are guaranteed to never 4327propagate exceptions, or that local exceptions cannot propagate out of 4328their scope. 4329 43305.18.1 Syntax 4331------------- 4332 4333 <control_kind> exception_propagation 4334 (local_exception); 4335 <control_kind> exception_propagation 4336 ([<level>,] interface, <convention> {, <convention> }); 4337 <control_kind> exception_propagation 4338 ([<level>,] parameter, <entity> {, <entity>}); 4339 <control_kind> exception_propagation 4340 ([<level>,] task); 4341 <control_kind> exception_propagation 4342 (<level>, declaration); 4343 43445.18.2 Action 4345------------- 4346 4347The "local_exception" subrule controls a design pattern that ensures 4348that a local exception cannot propagate outside the scope where it is 4349declared. If an exception is declared within a block, a subprogram 4350body, an entry body, or a task body, then this body must have either a 4351handler for this exception or for 'others'; this handler must not 4352reraise the exception; and no handler is allowed to raise explicitely 4353the exception. The subrule controls explicit 'raise' statements and 4354calls to 'Raise_Exception' and 'Reraise_Occurrence', but it does not 4355control exceptions raised as a consequence of calling other subprograms. 4356 4357 The other subrules control subprograms, tasks, or all declarations 4358that can propagate exceptions, while being used in contexts where it is 4359desirable to ensure that no exception can be propagated. 4360 4361 A subprogram or task is considered as _not_ propagating if: 4362 1. it has an exception handler with a "'when others'" choice 4363 2. no exception handler contains a 'raise' statement, nor any call to 4364 'Ada.Exception.Raise_Exception' or 4365 'Ada.Exception.Reraise_Occurrence'. 4366 3. no declaration from its own declarative part propagates exceptions. 4367 4368 A declaration is considered propagating if it includes elements that 4369could propagate exceptions. This is impossible to assess fully using 4370only static analysis, therefore the <level> parameter determines how 4371pessimistic (or optimistic) AdaControl is in determining the possibility 4372of exceptions. Possible values of the <level> parameter, and their 4373effect, are: 4374 * 0: expressions in declarative parts are not considered as 4375 propagating (anything allowed, this is the default value for 4376 "interface", "parameter" and "task". Not allowed for 4377 "declaration"). 4378 * 1: all function calls (including operators) in declarations are 4379 considered as potentially propagating exceptions, except those 4380 appearing in named number declarations or scalar types 4381 declarations, since those are required by the language to be 4382 static. 4383 * 2: same as 1, plus every use of variables in expressions is 4384 considered as potentially propagating. 4385 * 3: same as 2, plus any declaration of objects (constants or 4386 variables) is considered potentially propagating (not very useful 4387 for "declaration"). 4388 4389 These subrules serve several purposes: 4390 * The "interface" subrule analyzes all subprograms to which an 4391 'Interface' or 'Export' pragma applies (with the given 4392 convention(s)), and reports on those that can propagate exceptions. 4393 4394 Since it is dangerous to call an Ada subprogram that can propagate 4395 exceptions from a language that has no exception (and especially 4396 C), any such subprogram should have a "catch-all" exception 4397 handler. 4398 * The "parameter" subrule accepts one or more fully qualified formal 4399 parameter names (i.e. in the form of the parameter name prefixed 4400 by the full name of its subprogram, see *note Specifying an Ada 4401 entity name::). The subrule reports any subprogram that can 4402 propagate exceptions and is used as the prefix of a ''Access' or 4403 ''Address' attribute that appears as part of an actual value for 4404 the indicated formal. Similarly, the indicated formal can also be 4405 the name of a formal procedure or function of a generic. In this 4406 case, the rule will report on any subprogram that can propagate 4407 exceptions and is used as an actual in an instantiation for the 4408 given formal. 4409 4410 Many systems (typically windowing systems) use call-back 4411 subprograms. Although the native interface is generally hidden 4412 behind an Ada binding, the call-back subprograms will eventually be 4413 called from another language, and like for the "interface" subrule, 4414 any such subprogram should have a "catch-all" exception handler. 4415 * The "task" subrule reports any task that can propagate exceptions. 4416 4417 Since tasks die silently if an exception is propagated out of their 4418 body, it is generally desirable to ensure that every task has an 4419 exception handler that (at least) reports that the task is being 4420 completed due to an exception. 4421 * The "declaration" subrule reports any declaration that can 4422 propagate exceptions, irrespectively of where it appears. In this 4423 case, the specification of <level> is required and cannot be 0. 4424 4425 It is sometimes desirable to make sure that no declaration raises 4426 an exception, ever. 4427 4428 Ex: 4429 -- Make sure that C-compatible subprograms don't propagate exceptions: 4430 check exception_propagation (interface, C); 4431 4432 -- Parameter CB of of procedure Pack.Register is used as a call-back 4433 -- Make sure that not procedure passed to it can propagate exceptions. 4434 check exception_propagation (parameter, Pack.Register.CB); 4435 4436 -- Make sure that tasks do not die silently due to unhandled exception: 4437 check exception_propagation (task); 4438 4439 -- Make sure that no exception is raised by elaboration of declarations: 4440 check exception_propagation (2, declaration); 4441 4442 The first example will report on any subprogram to which a 'pragma 4443Interface (C,...)' applies that can propagate exceptions. 4444 4445 If 'Proc' is a procedure that can propagate exceptions, the second 4446example will report on every call like: 4447 Pack.Register (CB => Proc'Access); 4448 4449 The third example will report on any task that can terminate silently 4450due to an unhandled exception. 4451 4452 The fourth example will report on any declaration that makes use of 4453function calls or variables. 4454 44555.18.3 Tips 4456----------- 4457 4458Note that the registration procedure for a call-back can be designated 4459by an access type, but in this case, use the name of the formal for the 4460access type. For example, given: 4461 package Pack is 4462 type Acc_Proc is access procedure; 4463 type Acc_Reg is access procedure (CB : Acc_Proc); 4464 ... 4465 Ptr : Acc_Reg := ...; 4466 4467 You can give a rule such as: 4468 check exception_propagation (parameter, Pack.Acc_Reg.CB); 4469 All procedures registered by a call to 'Pack.Ptr.all' will be 4470considered. 4471 4472 The declaration of a for loop parameter is not checked by this rule. 4473In other words, the rule "check exception_propagation (2, declaration)" 4474will not issue a message for: 4475 for I in Positive range 1 .. X loop ... 4476 although formally the declaration of I could raise Constraint_Error 4477if X is negative. We consider that for the casual user, 4478Constraint_Error appears to be raised by the for loop statement. 4479 44805.18.4 Limitations 4481------------------ 4482 4483An exception may be raised in a subprogram considered as not propagating 4484by this rule, if an exception handler calls a subprogram that propagates 4485an exception. 4486 4487 The rule will not consider subprograms whose body is missing, or that 4488are not statically known (i.e. if a subprogram is registered through a 4489dereference of a pointer to subprogram), like in the following example: 4490 Pack.Register (CB => Pointer.all'Access); 4491 4492 Due to a weakness of the ASIS standard, references to subprograms 4493that appear in dispatching calls are not considered. This limitation 4494will be removed as soon as we find a way to work around this problem, 4495but the issue is quite difficult! 4496 4497 These last two cases are detected by the rule "uncheckable". *Note 4498Uncheckable::. 4499 4500 4501File: adacontrol_ug.info, Node: Expressions, Next: Generic_Aliasing, Prev: Exception_Propagation, Up: Rules reference 4502 45035.19 Expressions 4504================ 4505 4506This rule controls usage of various kinds of expressions. 4507 45085.19.1 Syntax 4509------------- 4510 4511 <control_kind> expressions (<subrule> {, <subrule>}); 4512 <subrule> ::= {<category>} <expression_kw> 4513 <expression_kw> ::= 4514 and | and_array | 4515 and_binary | and_boolean | 4516 and_then | array_aggregate | 4517 array_named_others | array_non_static_range | 4518 array_others | array_partial_others | 4519 array_positional_others | array_range | 4520 case | complex_parameter | 4521 downward_conversion | dispatching_function_calls | 4522 dynamic_function_calls | extendable_aggregate | 4523 extension_aggregate | explicit_dereference | 4524 fixed_multiplying_op | for_all | 4525 for_some | function_calls | 4526 if | if_elsif | 4527 if_no_else | implicit_dereference | 4528 in | inconsistent_attribute_dimension | 4529 inherited_function_call | mixed_operators | 4530 not | not_in | 4531 or | or_array | 4532 or_binary | or_boolean | 4533 or_else | parameter_view_conversion | 4534 prefixed_operator | real_equality | 4535 record_partial_others | record_aggregate | 4536 record_others | redispatching_function_calls | 4537 slice | static_membership | 4538 type_conversion | upward_conversion | 4539 unconverted_multiplying_op | underived_conversion | 4540 universal_range | unqualified_aggregate | 4541 xor | xor_array | 4542 xor_binary | xor_boolean 4543 <category> ::= 4544 <> | () | range | mod | delta | digits | array | 4545 record | tagged | access | new | private | task | protected 4546 45475.19.2 Action 4548------------- 4549 4550This rule controls usage of certain forms of expressions. The rule can 4551be specified at most once for each subrule (i.e. subrules that accept 4552categories can be specified once for each combination of categories and 4553expression keyword). 4554 4555 Categories are used by certain subrules to further refine the 4556control. They define categories of types to which they apply: 4557 * "<>": Any type 4558 * "()": Enumerated types 4559 * "range": Signed integer types 4560 * "mod": Modular types 4561 * "delta": Fixed point types (no possibility to differentiate 4562 ordinary and decimal fixed point types yet). 4563 * "digits": Floating point types 4564 * "array": Array types 4565 * "record": (untagged) record types 4566 * "tagged": Tagged types (including type extensions) 4567 * "access": Access types 4568 * "new": Derived types 4569 * "private": Private types 4570 * "task": Task types 4571 * "protected": Protected types 4572 4573 The subrule define the kind of expression being controlled: 4574 * 'not', 'and', 'or', 'xor', 'and_then', 'or_else', 'in', and 4575 'not_in' control usage of the corresponding logical operator (or 4576 short circuit form, or membership test). 4577 * 'and_array', 'or_array', and 'xor_array' do the same, but only for 4578 operators whose result type is an array type. 4579 * 'and_binary', 'or_binary', and 'xor_binary' do the same, but only 4580 for operators whose result type is a modular type. 4581 * 'and_boolean', 'or_boolean', and 'xor_boolean' do the same, but 4582 only for operators whose result type is 'Standard.Boolean'. 4583 * 'array_aggregate' and 'record_aggregate' control array and record 4584 aggregates, respectively, while 'unqualified_aggregate' controls 4585 aggregates (both arrays and records) that do not appear directly 4586 within a qualified expression. 'extension_aggregate' controls 4587 extension aggregates, while 'extendable_aggregate' controls 4588 aggregates that are not extension aggregates, but whose type is a 4589 non-root tagged type, or are extension aggregates whose ancestor 4590 part is not their immediate parent (such aggregates could be 4591 written as extension aggregates). 4592 * 'array_others' and 'record_others' control the occurrence of a 4593 'others =>' association in array and record aggregates, 4594 respectively. 4595 * 'array_partial_others' and 'record_partial_others' do the same, but 4596 only if there are other associations in addition to the 'others =>' 4597 in the aggregate. 'array_named_others' and 4598 'array_positional_others' do the same, but only for named 4599 (respectively positional) array aggregates. 4600 * 'array_range' controls array aggregates that include a range (i.e. 4601 an association like 'A .. B =>'). 'array_non_static_range' does 4602 the same, but only if (at least) one of the bounds is not static. 4603 * 'case' controls case expressions (introduced in Ada 2012). 4604 * 'complex_parameter' controls complex expressions used as actual 4605 parameters in subprogram (or entry) calls. A complex expression is 4606 any expression that includes a function call (including operators). 4607 This rule is not applied to the parameters of operators, since 4608 otherwise it would forbid any expression with more than a single 4609 operator. 4610 * 'explicit_dereference' controls explicit dereferences of access 4611 values (i.e. with an explicit '.all'). 4612 * 'fixed_multiplying_op' controls calls to predefined fixed-point 4613 multiplication and division (regular fixed-point or decimal-fixed 4614 point). 'unconverted_fixed_multiplying_op' does the same, but only 4615 when both operands are objects (not literals) of a fixed_point type 4616 (not Integer); this is when type conversion is required by Ada 83. 4617 * 'for_all' and 'for_some' control the two forms of quantifiers 4618 introduced by Ada 2012. 4619 * 'if' controls all if expressions (introduced in Ada 2012), while 4620 'if_elsif' only controls those that have an elsif part, and 4621 'if_no_else' only controls those that have no else part. 4622 * 'implicit_dereference' controls implicit dereferences of access 4623 values (i.e. when the '.all' is omitted). 4624 * 'inconsistent_attribute_dimension' controls when no dimension is 4625 explicitely given for a ''First', ''Last', ''Range' or ''Length' 4626 attribute and the attribute applies to a multi-dimensional array, 4627 or conversely, when an explicit dimension is given, but the 4628 attribute applies to a one-dimensional array. 4629 * 'function_call' controls all calls to functions, incuding user 4630 defined operators, but not predefined operators (including the 4631 latter would generate too much noise). 'dispatching_function_call' 4632 does the same, but only for dispatching calls while 4633 'redispatching_function_call' does the same, but only for 4634 dispatching calls that are (directly or indirectly) inside a 4635 primitive operation of a tagged type. 'dynamic_function_call' does 4636 the same, but only for calls through pointers. 4637 'inherited_function_call' controls calls to functions that have 4638 been inherited by a derived type and not redefined. 4639 4640 For all '*_function_call' subrules, if a category is specified, 4641 only calls whose result type belongs to the category are 4642 controlled. Derived types are followed, i.e. the "real" category 4643 from the original type is used for the matching; as a consequence, 4644 the "new" category cannot be specified for this subrule. 4645 * 'mixed_operators' controls expressions that involve several 4646 different operators, without parentheses. In a sense, it extends 4647 the language rule that forbids mixing 'and' and 'or' in logical 4648 expressions to all other operators. Note that for the purpose of 4649 this subrule, membership tests ('in', 'not in') and short circuit 4650 forms ('and then', 'or else') are considered operators. 4651 * 'prefixed_operator' controls calls to operators that use prefixed 4652 notation (i.e. '"+"(A, B)'). If a category is specified, only 4653 calls whose result type belongs to the category are controlled. 4654 4655 Derived types are followed, i.e. the "real" category from the 4656 original type is used for the matching; as a consequence, the "new" 4657 category cannot be specified for this subrule. 4658 * 'real_equality' controls usage of predefined exact equality or 4659 inequality ("=" or "/=") between real (floating point or fixed 4660 point) values. 4661 * 'slice' controls usage of array slices. 4662 * 'static_membership' controls membership tests ('in' and 'not in') 4663 where the expression on the left is statically known to belong to 4664 the range (or subtype) on the right, and is therefore always True 4665 (or false for 'not in'). 4666 * 'type_conversion' controls all (sub)type conversions, while 4667 'underived_conversion' controls conversions between types that do 4668 not belong to the same derivation family. 'downward_conversion' 4669 and 'upward_conversion' control conversions between types that 4670 belong to the same family, converting away from the root or toward 4671 the root, respectively. 'parameter_view_conversion' controls 4672 conversions that appear as 'out' or 'in out' actual parameters. 4673 4674 One or two categories can be specified; if only one category is 4675 specified, only conversions whose result type belong to that 4676 category are controlled. If two categories are specified, only 4677 conversions whose souce type belongs to the first category and 4678 whose target type belong to the second category are controlled. 4679 4680 Derived types are followed, i.e. the "real" category from the 4681 original type is used for the matching; as a consequence, the "new" 4682 category cannot be specified for this subrule. 4683 * 'universal_range' controls discrete ranges that are a part of an 4684 index constraint, constrained array definition, or for-loop 4685 parameter specification (but not type or subtype defintions), and 4686 whose bounds are both of type universal_integer. 4687 4688 Ex: 4689 search expressions (real_equality, slice); 4690 check expressions (mixed_operators); 4691 4692 -- Find logical operators that could be replaced by short-circuits forms: 4693 check expressions (and_boolean, or_boolean); 4694 4695 -- Find all conversions between integer and floating point types 4696 search expression (range digits type_conversion); 4697 4698 -- Find all conversions from a fixed point type: 4699 search expressions (delta <> type_conversion); 4700 4701 -- Find all view conversions between array types: 4702 search expressions (array parameter_view_conversions); 4703 4704 -- Find all "structural" conversions between arrays 4705 search expressions (array underived_conversion); 4706 4707 -- Some think that downward conversions of tagged types are evil: 4708 check expressions (tagged downward_conversion); 4709 47105.19.3 Tips 4711----------- 4712 4713The 'real_equality' subrule does not control calls to an equality 4714operator that has been defined by the user; actually, it would make 4715little sense to write a function and then forbid its use! However, if 4716control of calls to such a function is desired, it can be easily 4717accomplished by using the 'entities' rule. *Note Entities::. 4718 4719 This rule does not check the use of allocators ('new'), use the rule 4720'Allocators' instead. *Note Allocators::. 4721 4722 "inherited_function_call" controls only function calls. For 4723procedure calls, see rule *note Statements::. 4724 4725 Specifying 'array_partial_others' is the same as specifying both 4726'array_named_others' and 'array_positional_others'. It is retained for 4727compatibility, and also for symetry with 'record_partial_others'. 4728 4729 Per language rules, underived conversions are allowed only between 4730numeric types, and between structurally equivalent array types. 4731 4732 "static_membership" is handy for finding a common misuse of 4733membership tests, where the user assigns an external value (obtained 4734with Unchecked_Conversion for example) to a variable, then checks that 4735the variable belongs to its subtype to make sure the value is valid. 4736Such a check can be optimized away by the compiler; the 'Valid attribute 4737should be used instead. 4738 47395.19.4 Limitations 4740------------------ 4741 4742"static_membership" does not control the complex membership tests with 4743several choices that are possible with Ada 2012. 4744 4745 4746File: adacontrol_ug.info, Node: Generic_Aliasing, Next: Global_References, Prev: Expressions, Up: Rules reference 4747 47485.20 Generic_Aliasing 4749===================== 4750 4751This rule controls instantiations where the same actual is given to more 4752than one formal. 4753 47545.20.1 Syntax 4755------------- 4756 4757 <control_kind> generic_aliasing [(<subrule> {, <subrule>})]; 4758 <subrule> ::= [<condition>] <entity> 4759 <condition> ::= unlikely | possible | certain 4760 <entity> ::= all | variable | type | subprogram | package 4761 47625.20.2 Action 4763------------- 4764 4765This rule identifies instantiations where the same variable, type, 4766subprogram, or package is given several times (to different formal 4767parameters). Such aliasing of variables is dangerous, since it can 4768induce subtile bugs. Other elements are less dangerous, although often 4769questionable (depending on the generic). 4770 4771 The <entity> parameter indicates for which elements aliasing is 4772controlled; "all" stands for all kinds of elements. 4773 4774 There are many cases where aliasing cannot be determined statically. 4775The optional parameter specifies how aggressively the rule will check 4776for possible aliasings (see *note Parameter_Aliasing:: for a more 4777detailed description of these modifiers). Possible values are (case 4778irrelevant): 4779 * Certain (default): Only cases where aliasing is statically certain 4780 are output. 4781 * Possible: In addition, cases where aliasing may occur depending on 4782 the value of an indexed component are output. This can be 4783 specified only for variables. 4784 * Unlikely: In addition, cases where aliasing may occur due to access 4785 variables designating the same element are output. This can be 4786 specified only for variables and subprograms. 4787 4788 Without any parameter, the rule is the same as "certain all". The 4789rule can be specified only once for each combination of <condition> and 4790<entity>. 4791 4792 Ex: 4793 check generic_aliasing (certain variable); 4794 search generic_aliasing (possible variable, type, subprogram, package); 4795 47965.20.3 Limitations 4797------------------ 4798 4799Due to a limitation of ASIS for Gnat, AdaControl might not be able to 4800differentiate predefined operators of different types, and may thus give 4801false positives if a generic is instantiated with, for example, two 4802different functions that are actually '"+"' on Integer and '"+"' on 4803Float. This possibility of false positives is detected by the rule 4804"uncheckable". *Note Uncheckable::. 4805 4806 4807File: adacontrol_ug.info, Node: Global_References, Next: Header_Comments, Prev: Generic_Aliasing, Up: Rules reference 4808 48095.21 Global_References 4810====================== 4811 4812This rule controls accesses to global elements that may be subject to 4813race conditions, or otherwise shared. 4814 48155.21.1 Syntax 4816------------- 4817 4818 <control_kind> global_references (<subrule> {, <root>}); 4819 <subrule> ::= all | read | written | multiple | multiple_non_atomic 4820 <root> ::= <entity> | function | procedure | task | protected 4821 48225.21.2 Action 4823------------- 4824 4825This rule controls access to global variables from several entities (the 4826roots). The '<entity>' must be subprograms, task types, single task 4827objects, protected types, or single protected objects. As usual, the 4828whole syntax for entities is allowed for <entity>. *Note Specifying an 4829Ada entity name::. The special keywords 'function', 'procedure', 4830'task', and 'protected' are used to refer to all functions, procedures, 4831tasks, and protected entities, respectively. 4832 4833 The <subrule> determines the kind of references that are controlled. 4834If it is 'all', all references to global elements from the indicated 4835entities are reported. If <subrule> is 'read' or 'written', only read 4836(respectively write) accesses are reported. If <subrule> is 'multiple', 4837only global elements that are accessed by more than one of the indicated 4838entities (i.e. shared elements) are reported. Note however that if a 4839reference is found from a task type or protected type, it is always 4840reported, since there are potentially several objects of the same type. 4841If <subrule> is 'multiple_non_atomic', references reported are the same 4842as with 'multiple', except that global variables that are 'atomic' or 4843'atomic_components' and written from at most one of the indicated 4844entities are not reported. Note that this latter case corresponds to a 4845safe reader/writer use of atomic variables. 4846 4847 This rule follows the call graph, and therefore finds references from 4848subprogram and protected calls made (directly or indirectly) from the 4849indicated entities. However, calls to subprograms from the Ada standard 4850library are not followed. 4851 4852 Ex: 4853 -- Find global variables used by P1 or P2: 4854 search global_references (all, P1, P2); 4855 4856 -- Find global variables modified by functions: 4857 check global_references (written, function); 4858 4859 -- Find possible race conditions: 4860 check global_references (multiple, task, protected); 4861 4862 This rule can be given several times, and conflicts (with 'multiple') 4863are reported on a per-rule basis, i.e. given: 4864 check global_references (multiple, P1, P2); 4865 check global_references (multiple, P1, P3); 4866 4867 the first rule will report on global variables shared between P1 and 4868P2, and the second rule will report on global variables shared between 4869P1 and P3. 4870 48715.21.3 Tips 4872----------- 4873 4874The notion of "global" is relative, i.e. it designates every variable 4875whose scope encloses (strictly) the indicated entities. This means that 4876a same reference may or may not be global, depending on the indicated 4877entity. Consider: 4878 4879 procedure Outer is 4880 Inner_V : Integer; 4881 4882 procedure Inner_P is 4883 begin 4884 Inner_V := 1; 4885 end Inner_P; 4886 begin 4887 Inner_P; 4888 end Outer; 4889 4890 The rule 4891 check global_references (all, outer); 4892 will not report any global reference, while the rule 4893 check global_references (all, outer.inner_p); 4894 will report a reference to 'Inner_V'. This is as it should be, since 4895there is no race condition if several tasks call 'Outer', while there is 4896a risk if several tasks (declared inside 'Outer') call 'Inner_P'. 4897 4898 Specifying: 4899 check global_references (all, function); 4900 will report on any function that access variables outside of their 4901scope, i.e. all functions that have potential side effects. On the 4902other hand, this check must follow the whole call graph for any function 4903encountered, and can therefore be quite costly in execution time. 4904 49055.21.4 Limitations 4906------------------ 4907 4908Calls through pointers to subprograms and dispatching calls are unknown 4909statically; they are assumed to not access any global. Such calls are 4910detected by the rule "uncheckable". *Note Uncheckable::. 4911 4912 4913File: adacontrol_ug.info, Node: Header_Comments, Next: Improper_Initialization, Prev: Global_References, Up: Rules reference 4914 49155.22 Header_Comments 4916==================== 4917 4918This rule controls that every compilation unit starts with a 4919standardized comment. 4920 49215.22.1 Syntax 4922------------- 4923 4924 <control_kind> header_comments (minimum, <comment lines>); 4925 <control_kind> header_comments (model, "<file name>"); 4926 49275.22.2 Action 4928------------- 4929 4930If the keyword "minimum" is given as first parameter, this rule controls 4931that every compilation unit starts with at least the number of comment 4932lines indicated by the second parameter. If several forms of headers 4933are possible, checking that the headers follow the project's standard 4934requires manual inspection, but this rule is useful to control that unit 4935headers have not been inadvertantly forgotten. 4936 4937 If the keyword "model" is given as first parameter, the second 4938parameter is a string, interpreted as a file name. If the file name is 4939not an absolute path, it is interpreted as relative to the directory of 4940the file that contains the rule, or to the current directory if the rule 4941is given on the command line. Each line of the indicated file is a 4942regular expression, and the rule controls that the corresponding line of 4943the source file matches the expression. *Note Syntax of regular 4944expressions::. In addition, it is possible to specify a repetition for 4945a line. If the first character of a line is a ''{'', the line must have 4946the following syntax: 4947 {<min>,[<max>]} 4948 where <min> and <max> specify the minimum and maximum number of 4949occurrences of the pattern in the line that follows this one. <min> 4950must be at least 0, and <max> must be at least 1, and be equal or 4951greater than <min>. If <max> is omitted, it means that the line may 4952occur any number of times. 4953 4954 As a convenience, if the first character of a line is a ''*'' it 4955means that the next line is a pattern that can occur any number of times 4956(same as '{0,}'). If the first character is a ''+'', it means that the 4957next line is a pattern that must occur at least once (same as '{1,}'). 4958If the first character is a ''?'', it means that the next line is an 4959optional pattern (same as '{0,1}'). 4960 4961 Note that the repetition lines all start with a special character 4962which is not allowed at the start of a regular expression; there is 4963therefore no ambiguity. Everything after the special character (or the 4964closing ''}'') is ignored, and can be used to provide comments. 4965 4966 This rule can be given at most once with "minimum" for each of 4967"check", "search", and "count". The rule can be given only once with 4968"model" (but it can be given together with one or more "minimum" rules). 4969 4970 Ex: 4971 check header_comments (minimum, 10); 4972 search header_comments (model, "header.pat"); 4973 count header_comments (minimum, 20); 4974 This makes an error for every unit that starts with less than 10 4975comment lines, and a warning for units that do not follow the pattern 4976contained in the file 'header.pat'. A count of units that start with 4977less than 20 comment lines is reported. 4978 4979 Example of a pattern file: 4980 {1,3} 1 to 3 occurrences of next line 4981 ^--$ 4982 ^-- Author: .+$ 4983 ^-- Date: \d{2}/\d{2}/\\d{4}$ 4984 49855.22.3 Tips 4986----------- 4987 4988Remember that the lines of the file are regular expressions; every 4989character that is specially interpreted (like "+", "*", etc.) must be 4990quoted with "\" if it must appear textually. To ease the process of 4991generating the model file, the directory 'source' contains a script file 4992for sed named 'makepat.sed'; if you run this script on a file that 4993contains a standard header, it will produce a pattern file where each 4994line starts with "^", ends with "$", and every special character is 4995quoted with "\". 4996 4997 When the model contains an indication of repeated lines ("*"), the 4998repetition is not "greedy", i.e. matching will stop as soon as what 4999follows the repetition matches. This is very useful to check header 5000comments that have sections, but where you don't want to impose a 5001precise content to each section. Imagine for example that the structure 5002is: 5003 * A comment with "HISTORY" 5004 * Any number of comment lines 5005 * A comment with "AUTHORS" 5006 * Any number of comment lines 5007 the following pattern will work as expected: 5008 ^-- HISTORY$ 5009 * 5010 ^-- 5011 ^-- AUTHORS 5012 * 5013 ^-- 5014 50155.22.4 Limitation 5016----------------- 5017 5018Since the "model" subrule analyzes the content of comments, there is a 5019conflict with the disabling mechanism of AdaControl that uses special 5020comments. *Note Disabling controls::. 5021 5022 Specifically, line disabling is not possible at all. Block disabling 5023is possible, provided the disabling line is allowed by the pattern. In 5024short, if you want to be able to disable this rule, the first lines of 5025the model file should be: 5026 ? 5027 --## 5028 i.e. allow an optional block disabling comment as the first line of 5029the file. Note that there is no need to re-enable this rule, since it 5030is checked only at the start of a compilation unit. 5031 5032 5033File: adacontrol_ug.info, Node: Improper_Initialization, Next: Instantiations, Prev: Header_Comments, Up: Rules reference 5034 50355.23 Improper_Initialization 5036============================ 5037 5038This rule enforces a coding pattern that ensures that variables and 5039'out' parameters are properly initialized befor use. 5040 50415.23.1 Syntax 5042------------- 5043 5044 <control_kind> improper_initialization [(<subrule> {,<subrule>})] 5045 <subrule> ::= {<extra>} <target> 5046 <extra> ::= access | limited | package | return 5047 <target> ::= out_parameter | variable | initialized_variable 5048 50495.23.2 Action 5050------------- 5051 5052This rule controls variables and/or 'out' parameters that are not 5053"properly" initialized, i.e. those that are not "safely" initialized, 5054those that have a useless initialization in their declaration, and those 5055where the value is known to be used before having been assigned. The 5056notion of variable includes the return object of an extended return 5057statement (Ada 2005+). 5058 5059 A variable (or 'out' parameter) is considered safely initialized if 5060there is an initialization expression in its declaration, or if it is 5061given a value in the first statements of the corresponding body, before 5062any "non-trivial" statement. The goal is not to perform a complete 5063data-flow analysis, but rather to follow a design pattern where all 5064variables are initialized before entering the "active" part of the 5065algorithm. This makes it easier to ensure that variables are properly 5066initialized. 5067 5068 "Trivial" statements are: 5069 * 'null' statements; 5070 * assignment statements; 5071 * procedure calls; 5072 * return statements; 5073 * raise statements; 5074 * extended return statements, unless they contain a nested 5075 non-trivial statement. 5076 * 'if' and 'case' statements, unless they contain a nested 5077 non-trivial statement. 5078 The <target> parameters determines what is to be checked: 5079 * 'out_parameter' controls that 'out' parameters are safely 5080 initialized before the first non-trivial statement, and before 5081 every (trivial) 'return' statement. Note that 'out' parameters are 5082 not checked before 'raise' statements, since the language does not 5083 guarantee that 'out' parameters are transmitted back in the case of 5084 exceptions. 5085 * 'variable' controls that local variables are safely initialized 5086 before the first non-trivial statement. If the <extra> modifier 5087 'return' is specified, only return objects of extended return 5088 statements are controlled. 5089 * 'initialized_variable' controls variables that are safely 5090 initialized before the first non-trivial statement, but also have 5091 an explicit (and therefore useless) explicit initialization in 5092 their declaration. If the modifier 'return' is specified, only 5093 return objects of extended return statements are controlled. 5094 In all cases, variables used in trivial statements before being 5095initialized are reported. 5096 5097 A variable is considered initialized if it is the target of an 5098assignment statement, or if it is used as an actual for an 'out' (but 5099not 'in out') parameter of a procedure call. Variables assigned in 'if' 5100or 'case' statements must receive a value in all paths to be considered 5101initialized after the statement. Note that the variable must be 5102assigned to globally, i.e. assigning to some elements of an array, or 5103some fields of a record, does not count as an initialization of the 5104variable. 5105 5106 Some variables are not controlled, unless the corresponding <extra> 5107modifier is given: 5108 * Variables declared immediately within a (generic) package 5109 specification or body, since in general, package state variables 5110 are initialized through calls to dedicated procedures. Use the 5111 "package" modifier to control also package variables. 5112 * Variables of an access types, or arrays whose components are of an 5113 access type, since these are always initialized by the compiler. 5114 Use the "access" modifier to control also variables of an access 5115 type. 5116 * Variables of a limited type, since global assignment is not 5117 available for them. Use the "limited" modifier to control also 5118 variables of a limited type. 5119 5120 This rule can be given only once for each value of <target>. Without 5121parameters, it is equivalent to giving all, without any <extra>. 5122 5123 Ex: 5124 check improper_initialization (out_parameter); 5125 check improper_initialization (access limited variable); 5126 search improper_initialization (initialized_variable); 5127 51285.23.3 Tips 5129----------- 5130 5131'variable' and 'initialized_variable' control also return objects from 5132extended return statements, since it would be strange to guarantee safe 5133initialization of local variables and not return objects. On the other 5134hand, the design pattern enforced by this rule may seem to limitative 5135for regular variables, but it might be desirable to enforce it for 5136return objects; hence the possibility to limit the rule to return 5137objects by specifying the 'return' modifier. 5138 51395.23.4 Limitations 5140------------------ 5141 5142Due to a weakness of the ASIS standard, dispatching calls and calls to 5143procedures that are attributes are not considered for the initialization 5144of variables. Note that for attributes, only ''Read' and ''Input' have 5145an 'out' parameter. 5146 5147 In the rare case where a variable is initialized by a dispatching 5148call or an attribute call, this limitation will result in a false 5149positive. Such a case is detected by the rule "uncheckable". *Note 5150Uncheckable::. It is then easy to disable the rule for this variable. 5151*Note Disabling controls::. 5152 5153 The rule analyzes only initializations and uses that are directly in 5154the unit, not those from nested units, since these are in the general 5155case not statically checkable. 5156 5157 There are other cases where an object is automatically initialized by 5158the declaration, like controlled types that have redefined the 5159'Initialize' procedure, records where all components have a default 5160initialization, etc. The rule does not consider these as automatically 5161initialized, as it does for access types. Maybe later... 5162 5163 5164File: adacontrol_ug.info, Node: Instantiations, Next: Insufficient_Parameters, Prev: Improper_Initialization, Up: Rules reference 5165 51665.24 Instantiations 5167=================== 5168 5169This rule controls all instantiations of a generic, or only 5170instantiations that are made with specific values of the parameters. 5171Control can be restricted to instantiations in specified places. 5172 51735.24.1 Syntax 5174------------- 5175 5176 <control_kind> instantiations (<generic_spec>); 5177 <generic_spec> ::= {[not] <location_kw>} <entity> {, <formal_spec>} 5178 <formal_spec> ::= <entity> | <category> | <> | = 5179 <location_kw> ::= all | block | library | local | nested | 5180 own | private | public | in_generic | task_body 5181 <category> ::= () | access | array | delta | digits | mod | 5182 private | protected | range | record | tagged | task 5183 51845.24.2 Action 5185------------- 5186 5187The rule controls instantiations of the specified <entity>. As usual, 5188the whole syntax for entities is allowed for <entity>. *Note Specifying 5189an Ada entity name::. 5190 5191 The <location_kw> restricts the places where the occurrence of the 5192instantiation is controlled. If it is preceded by "not", the 5193instantiation is controlled except at this location. Several 5194<location_kw> can be given, in which case the instantiation is 5195controlled at places where all the keywords apply. If there is no 5196<location_kw>, it is assumed to be "all". 5197 * 'all': puts no special restriction to the location. This keyword 5198 can be specified for readability purposes, and if specified must 5199 appear alone (not with other <location_kw>), and "not" is not 5200 allowed. 5201 * 'block': only instantiations appearing in block statements are 5202 controlled. 5203 * 'library': only library level instantiations are controlled. 5204 * 'local': only local instantiations are controlled (i.e. only 5205 instantiations appearing in (generic) packages, possibly nested, 5206 are allowed). 5207 * 'own': only instantiations that are local to a (generic) package 5208 body are controlled. 5209 * 'public': only declarations appearing in the visible part of 5210 (generic) packages are controlled. 5211 * 'private': only instantiations appearing directly in a private part 5212 are controlled. 5213 * 'in_generic': only instantiations appearing directly or indirectly 5214 in a generic specification or body are controlled. 5215 * 'task_body': only instantiations appearing directly in a task body 5216 are controlled. Note that it would not make sense to have a 5217 <location_kw> for task specifications, since instantiations are not 5218 allowed there. 5219 5220 An instantiation matches if it appears at a specified location (if 5221any) and either: 5222 1. No <formal_spec> is given in the rule 5223 2. The actual parameters of the instantiation match the corresponding 5224 <formal_spec>, in order (there can be more actual parameters in the 5225 instantiation than specified in the rule). An actual parameter 5226 matches an <entity> at a given place if it is the same entity, or 5227 if the <entity> designates a (sub)type and the actual is a subtype 5228 of this type. As usual, the whole syntax for entities is allowed 5229 for <entity>. *Note Specifying an Ada entity name::. In addition, 5230 it matches if the actual is a type name that belongs to the 5231 indicated category: 5232 * "()": The parameter is of an enumerated type. 5233 * "access": The parameter is of an access type. 5234 * "array": The parameter is of an array type. 5235 * "delta": The parameter is of a fixed point type (it is not 5236 currently possible to distinguish ordinary fixed point types 5237 from decimal fixed point types). 5238 * "digits": The parameter is of a floating point type. 5239 * "mod": The parameter is of a modular type. 5240 * "private": The parameter is of a private type (including 5241 private extensions). 5242 * "protected": The parameter is of a protected type. 5243 * "range": The parameter is of a signed integer type. 5244 * "record": The parameter is of an (untagged) record type. 5245 * "tagged": The parameter is of a tagged type (including type 5246 extensions). 5247 * "task": The parameter is of a task type. 5248 5249 In addition, two special signs can be given instead of an <entity> 5250 (or <category>): a box ('<>') matches any actual parameter (i.e. 5251 it stands for any value), and an equal sign ('=') matches if there 5252 has been already an instantiation with the same value for this 5253 parameter (i.e. it matches the second time it is encountered). 5254 5255 Formal 'in' parameters cannot be matched, since the actual can be any 5256expression and it is not clear how to specify it in the rule; therefore, 5257the rule should normally specify a box ('<>') at the place of such 5258parameters. 5259 5260 Ex: 5261 -- Check all instantiations of Unchecked_Deallocation: 5262 search instantiations (ada.unchecked_deallocation); 5263 5264 -- Check all instantiations of Unchecked_Conversion from or to String: 5265 check instantiations (ada.unchecked_conversion, standard.string); 5266 check instantiations (ada.unchecked_conversion, <>, standard.string); 5267 5268 -- Check all instantiations of Unchecked_Conversion from address 5269 -- to an integer type: 5270 check instantiations (ada.unchecked_conversion, system.address, range); 5271 5272 -- Check that Unchecked_Conversion is instantiated only once 5273 -- for any pair of arguments: 5274 check instantiations (ada.unchecked_conversion, =, =); 5275 52765.24.3 Tips 5277----------- 5278 5279The various forms of <formal_spec> make the rule quite powerful. For 5280example: 5281 -- Not two instantiations of Gen with the same first parameter: 5282 check instantations (Gen, =); 5283 5284 -- Not two instantiations of Gen with the same first and third parameter: 5285 check instantiations (Gen, =, <>, =); 5286 5287 -- Not two instantiations of Gen with the same first parameter if the 5288 -- second parameter is Pack.Proc: 5289 check instantiations (Gen, =, Pack.Proc); 5290 5291 -- Not two instantiations of Gen with the same first parameter if the 5292 -- second parameter is any procedure named Proc: 5293 check instantiations (Gen, =, all Proc); 5294 5295 Note that a generic actual wich is a subtype matches all types (and 5296subtypes) above it. Therefore, 5297 check instantiations (ada.unchecked_deallocation (standard.natural)); 5298 will find only instantiations that use 'Natural', while: 5299 check instantiations (ada.unchecked_deallocation (standard.integer)); 5300 will find instantiations that use either 'Integer', 'Positive', or 5301'Natural'. 5302 5303 If an equal sign ('=') is provided for a formal 'in' parameter, it is 5304not part of the comparison of existing instantiations (it behaves like a 5305box ('<>')), i.e. given: 5306 generic 5307 type T1 is private; 5308 Val : String := ""; 5309 package Gen; 5310 5311 package body Gen is ... end Gen; 5312 5313 package Inst1 is new Gen (Float, "Some Message"); 5314 package Inst2 is new Gen (Float, "Some Other Message"); 5315 and the rule: 5316 check instantiations (Gen, =, =); 5317 Adacontrol will issue a message for Inst2 that it has already been 5318instantiated with the same parameters, although the second ('in') 5319parameter is different. 5320 53215.24.4 Limitation 5322----------------- 5323 5324GNAT defines 'Unchecked_Conversion' and 'Unchecked_Deallocation' as 5325separate entities, rather than renamings of 'Ada.Unchecked_Conversion' 5326and 'Ada.Unchecked_Deallocation'. As a consequence, it is necessary to 5327specify explicitely both forms if you want to make sure that the 5328corresponding generics are not instantiated. 5329 5330 5331File: adacontrol_ug.info, Node: Insufficient_Parameters, Next: Local_Access, Prev: Instantiations, Up: Rules reference 5332 53335.25 Insufficient_Parameters 5334============================ 5335 5336This rule controls calls to subprograms and entries where the values of 5337parameters does not provide sufficient information to the reader to 5338correctly identify the parameter's purpose. 5339 53405.25.1 Syntax 5341------------- 5342 5343 <control_kind> insufficient_parameters (<max_allowed> {, <entity>}); 5344 53455.25.2 Action 5346------------- 5347 5348<max_allowed> is the maximum number of allowed "insufficient" parameters 5349(can be 0). The <entity> parameters designate enumeration types whose 5350values should be included in the check. As usual, the whole syntax for 5351entities is allowed for <entity>. *Note Specifying an Ada entity 5352name::. 5353 5354 An actual parameter is deemed "insufficient" if it is given in 5355positional (as opposed to named) notation, it is an expression whose 5356primaries are all numeric literals, or enumeration literals belonging to 5357one of the types passed as parameters to the rule ('Standard.Boolean' 5358for example). 5359 5360 This rule can be given once for each of check, search, and count. 5361This way, it is possible to have a level considered a warning (search), 5362and one considered an error (check). 5363 5364 Ex: 5365 search Insufficient_Parameters (1, Standard.Boolean); 5366 check Insufficient_Parameters (2, Standard.Boolean); 5367 53685.25.3 Tips 5369----------- 5370 5371This rule does not apply to operators that use infix notation, nor to 5372calls to subprograms that are attributes, since named notation is not 5373allowed for these. 5374 5375 This rule controls the use of positional parameters according to 5376their values; it is also possible to control the use of positional 5377parameters according to the number of parameters with the rule 5378'positional_associations'. *Note Positional_Associations::. 5379 5380 Note also that this rules applies only to calls, while 5381'positional_associations' applies to all forms of associations. 5382 5383 5384File: adacontrol_ug.info, Node: Local_Access, Next: Local_Hiding, Prev: Insufficient_Parameters, Up: Rules reference 5385 53865.26 Local_Access 5387================= 5388 5389This rule controls the taking of access values (through the ''Access', 5390''Unchecked_Access', or the GNAT specific ''Unrestricted_Access' 5391attributes) of local (i.e. non global) entities. 5392 53935.26.1 Syntax 5394------------- 5395 5396 <control_kind> local_access [(<subrule> {,<subrule>})]; 5397 <subrule> ::= constant | variable | procedure | function | 5398 protected_procedure | protected_function 5399 54005.26.2 Action 5401------------- 5402 5403Without parameters, the rule controls all entities given as prefixes of 5404''Access', ''Unchecked_Access', or ''Unrestricted_Access' attributes and 5405reports on those that are not global, i.e. not defined in (possibly 5406nested) library packages. 5407 5408 If parameters are specified, only entities belonging to the 5409corresponding categories are controlled. 5410 5411 Ex: 5412 Dangerous_Objects: check local_access (Constant, Variable); 5413 54145.26.3 Tips 5415----------- 5416 5417In Ada 95, accessibility rules make sure that taking the ''Access' of an 5418entity cannot create dangling pointers, but this check can be 5419circumvented by using ''Unchecked_Access' (but not on subprograms), or 5420in GNAT, by using ''Unrestricted_Access'. Moreover, Ada 2005 5421generalized anonymous access types create more cases where accessibility 5422levels are dynamically checked. 5423 5424 Taking an access value on a global entity is never a risk, but every 5425use of access values designating local entities has a potential of a 5426failing dynamic accessibility check or even of a dangling pointer. This 5427rule is helpful in finding the places that need careful inspection - or 5428for disallowing taking accesses on anything but global entities. 5429 5430 5431File: adacontrol_ug.info, Node: Local_Hiding, Next: Max_Blank_Lines, Prev: Local_Access, Up: Rules reference 5432 54335.27 Local_Hiding 5434================= 5435 5436This rule controls declarations that hide an outer declaration with the 5437same name. 5438 54395.27.1 Syntax 5440------------- 5441 5442 <control_kind> local_hiding [(<subrule> {,"<allowed pattern>"})]; 5443 <subrule> ::= {<exception>} strict | overloading 5444 <exception> ::= not_operator | not_enumeration | 5445 not_identical_renaming | not_different_families 5446 54475.27.2 Action 5448------------- 5449 5450If "strict" is given (or if there is no subrule), the rule controls 5451strict hiding (an inner subprogram that overloads an outer one is not 5452considered hiding). If "overloading" is given, only subprograms that 5453overload another subprogram in the same scope or in an outer scope are 5454controlled. Note that following the normal Ada model, the declarations 5455of enumeration literals are considered functions (and thus controlled). 5456 5457 Modifiers are used to exclude some controls (i.e. to allow the 5458corresponding hiding): 5459 * "not_operator": the subrule does not apply to the declarations of 5460 operators (i.e. things like "'"+"'"). 5461 * "not_enumeration": the subrule does not apply to the 5462 hiding/overloading of enumeration literals by other enumeration 5463 literals (the rule still applies to the hiding/overloading of 5464 functions by enumeration litterals, for example). 5465 * "not_identical_renaming" (only allowed with "strict"): the subrule 5466 does not apply to renamings where the renaming name is the same as 5467 the name of the renamed entity. Such renamings are commonly used 5468 to provide visibility of identifiers in a controlled way. 5469 * "not_different_families" (only allowed with "strict"): the subrule 5470 does not apply if the hiding identifier and the hidden one do not 5471 belong to the same "family". Families are either data (constant, 5472 variables, numbers, etc.), types, subprograms (including entries), 5473 packages, generics, exceptions, and labels (including block and 5474 loop names). 5475 If one or more <allowed pattern> are given, hiding (or overloading) 5476of identifiers that match one of the patterns are not reported. The 5477whole syntax for regular expressions is allowed for the pattern, but the 5478matching is always case insensitive. *Note Syntax of regular 5479expressions::. 5480 5481 This rule can be given only once for "strict" and once for 5482"overloading". 5483 5484 Ex: 5485 Hiding: check local_hiding (strict); 5486 Overloading: search local_hiding (not_operator overloading); 5487 54885.27.3 Variables 5489---------------- 5490 5491The rule provides a variable that allows to adjust the verbosity of 5492messages for the subrule "overloading". 5493 5494Variable Values Default Effect 5495Overloading_Reportcompact/detaileddetailedif "detailed", when a construct 5496 that overloads several other 5497 constructs is encountered, 5498 "overloading" will issue a message 5499 for each overloaded construct; if 5500 "compact", it will issue a single 5501 message mentionning how many 5502 constructs are overloaded, and a 5503 pointer to the last one. 5504 55055.27.4 Tips 5506----------- 5507 5508If you have a naming convention like having all tagged types named 5509"instance" (with a meaningful name for the enclosing package), and if in 5510addition your package structure follows the inheritance hierarchy (i.e. 5511a descendent class is in a child package), then all "instance" will hide 5512each other - but this is of course intended. Specifying "'^instance$'" 5513as an allowed pattern will prevent error messages for these 5514declarations. 5515 5516 Note that the name is given between "'^'" and "'$'". Otherwise, 5517following normal regexp syntax, any identifier containing "instance" 5518would be allowed. 5519 5520 A confusion between names belonging to different "families" (as 5521defined here) always leads to a compilation error; it may be acceptable 5522to allow local hiding of names belonging to different families, since 5523there is no risk involved. 5524 5525 5526File: adacontrol_ug.info, Node: Max_Blank_Lines, Next: Max_Call_Depth, Prev: Local_Hiding, Up: Rules reference 5527 55285.28 Max_Blank_Lines 5529==================== 5530 5531This rule controls excessive spacing in the program text. 5532 55335.28.1 Syntax 5534------------- 5535 5536 <control_kind> max_blank_lines (<max allowed blank lines>); 5537 55385.28.2 Action 5539------------- 5540 5541This rule controls the occurrence of more than the indicated number of 5542consecutive blank lines (empty lines, or lines that contain only 5543spaces). This rule can be given once for each of check, search, and 5544count. This way, it is possible to have a number of blank lines 5545considered a warning (search), and one considered an error (check). Of 5546course, this makes sense only if the number for search is less than the 5547one for check. 5548 5549 Ex: 5550 search max_blank_lines (2); 5551 check max_blank_lines (5); 5552 5553 5554File: adacontrol_ug.info, Node: Max_Call_Depth, Next: Max_Line_Length, Prev: Max_Blank_Lines, Up: Rules reference 5555 55565.29 Max_Call_Depth 5557=================== 5558 5559This rule controls the maximum depth of subprograms (or entry) calls. 5560 55615.29.1 Syntax 5562------------- 5563 5564 <control_kind> max_call_depth (<allowed depth> | finite {, <entity>}); 5565 55665.29.2 Action 5567------------- 5568 5569Roughly speaking, the call depth is the number of frames that are 5570stacked by a call: if you call a subprogram that calls another 5571subprogram that calls nothing, then the call depth is 2. Note that a 5572call to a task (not protected) entry has always a depth of 1, since the 5573accept body that corresponds to the entry is executed on a different 5574stack. 5575 5576 The value of the first parameter is the maximum allowed depth, i.e. 5577the rule will trigger if the call depth is strictly greater than the 5578indicated value. A call to a (directly or indirectly) recursive 5579procedure is considered of infinite depth, and will be therefore 5580signaled (with an appropriate message) for any value of <allowed depth>. 5581Alternatively, the keyword "finite" can be given in place of the 5582<allowed depth>: in this case, only calls to recursive subprograms will 5583be signalled. 5584 5585 If entity names are given after the first parameter, they are 5586interpreted as callable entities that are not to be analyzed, and 5587assumed of depth 0 (not calling anything else). As usual, the whole 5588syntax for entities is allowed for <entity>. *Note Specifying an Ada 5589entity name::. This can be useful, for example, when a subprogram 5590appears to be recursive (but is not, due to the algorithm), to prevent 5591all those who call it to be flagged as having infinite call depth. 5592 5593 This rule can be given once for each of check, search, and count. 5594This way, it is possible to have a call depth considered a warning 5595(search), and one considered an error (check). Of course, this makes 5596sense only if the number for search is less than the one for check. 5597 5598 Ex: 5599 search max_call_depth (9); 5600 check max_call_depth (finite); 5601 56025.29.3 Variable 5603--------------- 5604 5605The rule provides a variable that allows to specify how to handle 5606expression functions (Ada 2012). 5607 5608Variable Values Default Effect 5609Count_Expr_Fun_Callson/off on if "on", calls to expression functions 5610 are counted like regular calls; if 5611 "off", such calls are assumed to be 5612 inlined and do not add an extra depth 5613 level. 5614 56155.29.4 Tip 5616---------- 5617 5618It is possible to give the value 0 for <allowed depth>. Of course, it 5619would not make sense to forbid all subprogram calls in an Ada program, 5620but this can be useful for inspection purposes, since every call will be 5621reported, and the message indicates the depth of the call. 5622 5623 If the message says that the call depth "is N", it is exactly N. If 5624the message says that the call depth is "at least N", it means that the 5625call chain includes a call to a subprogram whose depth is unknown (see 5626"Limitations" below); "N" is the call depth if this subprogram does not 5627call anything else. Of course, the rule issues a message if this 5628minimal value is greater than the maximum allowed value. 5629 5630 There is only one set of entities that are forced to depth 0; 5631therefore, if the control is given several times, each with various 5632<entity>, all controls will use the union of all entities given. 5633 56345.29.5 Limitations 5635------------------ 5636 5637Calls to subprograms that are attributes are assumed to have a depth of 56381. Calls to predefined operators are assumed to be in-lined (i.e. a 5639depth of 0). 5640 5641 Calls through pointers to subprograms and dispatching calls are 5642unknown statically; in addition, some subprograms may not have a body 5643available for analysis, like imported subprograms, or possibly 5644subprograms from the standard library; they are all assumed to have a 5645depth of 1. Such calls are detected by the rule "uncheckable". *Note 5646Uncheckable::. 5647 5648 5649File: adacontrol_ug.info, Node: Max_Line_Length, Next: Max_Nesting, Prev: Max_Call_Depth, Up: Rules reference 5650 56515.30 Max_Line_Length 5652==================== 5653 5654This rule controls that no line exceeds a given length. 5655 56565.30.1 Syntax 5657------------- 5658 5659 <control_kind> max_line_length (<max allowed length>); 5660 56615.30.2 Action 5662------------- 5663 5664This rule controls the maximum length of source lines. This rule can be 5665given once for each of check, search, and count. This way, it is 5666possible to have a length considered a warning (search), and one 5667considered an error (check). Of course, this makes sense only if the 5668length for search is less than the one for check. 5669 5670 Ex: 5671 search max_line_length (80); 5672 check max_line_length (120); 5673 5674 5675File: adacontrol_ug.info, Node: Max_Nesting, Next: Max_Size, Prev: Max_Line_Length, Up: Rules reference 5676 56775.31 Max_Nesting 5678================ 5679 5680This rule controls excessive nesting of declarations. 5681 56825.31.1 Syntax 5683------------- 5684 5685 <control_kind> max_nesting ([<subrule>,] <max allowed depth>); 5686 <subrule> ::= all | generic | separate | task 5687 56885.31.2 Action 5689------------- 5690 5691If "all" (or no subrule) is given as the first parameter, this rule 5692controls the nesting of declarative constructs (like subprograms, 5693packages, generics, block statements...) that exceed a given depth. 5694Nesting of statements ('loop', 'case') is not considered. 5695 5696 If "generic" is given as the first parameter, this rule controls the 5697nesting of generics, ignoring all non-generic units. 5698 5699 If "separate" is given as the first parameter, this rule controls the 5700nesting of separate bodies. 5701 5702 If "task" is given as the first parameter, this rule controls the 5703nesting of tasks (task types and single task objects), ignoring all 5704non-task units. 5705 5706 This rule can be given once for each subrule and each of check, 5707search, and count. This way, it is possible to have a level considered 5708a warning (search), and one considered an error (check). Of course, 5709this makes sense only if the level for search is less than the one for 5710check. 5711 5712 Note that the value given is the maximum allowed nesting; f.e. if 5713the value given for "generic" is 1, it means that a generic inside a 5714generic is allowed, but not more. 5715 5716 Ex: 5717 search max_nesting (5); 5718 check max_nesting (all, 7); 5719 check max_nesting (generic, 1); 5720 check max_nesting (separate, 0); -- Do not allow separate in separate 5721 check max_nesting (task, 0); -- Do not allow a task in another task 5722 5723 5724File: adacontrol_ug.info, Node: Max_Size, Next: Max_Statement_Nesting, Prev: Max_Nesting, Up: Rules reference 5725 57265.32 Max_Size 5727============= 5728 5729This rule controls the maximum size, in source lines of code, of various 5730statements and declarations. 5731 57325.32.1 Syntax 5733------------- 5734 5735 <control_kind> max_size (<subrule>, <max allowed lines>); 5736 <subrule> ::= accept | block | case | case_branch | 5737 if | if_branch | loop | simple_block | 5738 unnamed_block | unnamed_loop | 5739 package_spec | package_body | procedure_body | 5740 function_body | protected_spec | protected_body | 5741 entry_body | task_spec | task_body | 5742 unit 5743 57445.32.2 Action 5745------------- 5746 5747The first parameter is a subrule keyword that determines which elements 5748are controlled: 5749 * "accept" controls accept statements. 5750 * "block" controls all block statements, while "simple_block" 5751 controls only blocks without a 'declare' part, and "unnamed_block" 5752 controls only blocks without a name. 5753 * "loop" controls all loop statement, while "unnamed_loop" controls 5754 only loops without a name. 5755 * "if_branch" and "case_branch" control the length of each 5756 alternative of an 'if' (respectively 'case') statement. 5757 * "package_spec", "package_body", "procedure_body", "function_body", 5758 "protected_spec", "protected_body", "entry_body", "task_spec", and 5759 "task_body" control the length of the declaration of the 5760 corresponding element. 5761 * "unit" controls the whole length of compilation units. 5762 5763 For each kind of element, the indicated value is the maximum allowed 5764size of the full element; however, for branches ("if_branch" and 5765"case_branch") it is the maximum size of the sequence of statements in 5766the branch (i.e., the line that contains the 'elsif' is not counted as 5767part of an "if_branch"). 5768 5769 This rule can be given once for each of check, search, and count for 5770each kind of element. This way, it is possible to have a level 5771considered a warning (search), and one considered an error (check). Of 5772course, this makes sense only if the number of lines for search is less 5773than the one for check. 5774 5775 Ex: 5776 check Max_Size (if_branch, 30); 5777 search Max_Size (if_branch, 50); 5778 check Max_Size (unnamed_loop, 20); 5779 57805.32.3 Tip 5781---------- 5782 5783Note that "procedure_body" and "function_body" apply to protected 5784subprograms as well as regular ones, and that there is no subrule for 5785the length of the declaration of subprograms. Such fine specifications 5786didn't seem useful, but could be added if someone expresses a need for 5787it. 5788 5789 5790File: adacontrol_ug.info, Node: Max_Statement_Nesting, Next: Movable_Accept_Statements, Prev: Max_Size, Up: Rules reference 5791 57925.33 Max_Statement_Nesting 5793========================== 5794 5795This rule controls the nesting of compound statements. 5796 57975.33.1 Syntax 5798------------- 5799 5800 <control_kind> max_statement_nesting (<subrule>, <max allowed depth>); 5801 <subrule> ::= block | case | if | loop | all 5802 58035.33.2 Action 5804------------- 5805 5806If one of "block", "case", "if", or "loop" is specified, it controls the 5807nesting of statements of the same kind, i.e. an 'if' within a 'loop' 5808within an 'if' counts only 2 for the "if" keyword. If "all" is 5809specified, all kinds of compound statements are counted together, i.e. 5810an 'if' within a 'loop' within an 'if' counts for 3. This rule can be 5811given once for each of check, search, and count, and for each of the 5812subrules. This way, it is possible to have a level considered a warning 5813(search), and one considered an error(check). Of course, this makes 5814sense only if the level for search is less than the one for check. 5815 5816 Ex: 5817 check max_statement_nesting (loop, 3); 5818 search max_statement_nesting (all, 5); 5819 5820 5821File: adacontrol_ug.info, Node: Movable_Accept_Statements, Next: Naming_Convention, Prev: Max_Statement_Nesting, Up: Rules reference 5822 58235.34 Movable_Accept_Statements 5824============================== 5825 5826This rule controls statements that are inside accept statements and 5827could safely be moved outside. 5828 58295.34.1 Syntax 5830------------- 5831 5832 <control_kind> movable_accept_statements (certain|possible {, <entity>}) 5833 58345.34.2 Action 5835------------- 5836 5837Since it is good practice to block a client for the shortest time 5838possible, any action that does not depend on the accept parameters 5839should not be part of an accept statement. 5840 5841 Statements that involve synchronisation (delay statements, accept or 5842entry calls...) are not movable. Statements (including compound 5843statements) that reference the parameters of the enclosing accept are 5844not movable. In addition, statements that use one of the <entity> given 5845as parameters are never considered movable. As usual, the whole syntax 5846for entities is allowed for <entity>. *Note Specifying an Ada entity 5847name::. Note that if a generic entity, or an entity declared in a 5848generic package, is given, all statements that use the corresponding 5849instantiated entity are considered not movable. 5850 5851 If the first parameter of the rule is 'certain', only statements 5852after the last non-movable statement are reported. If the first 5853parameter is 'possible', a simple data flow analysis is performed, and 5854every statement that does not reference a variable that appears to 5855depend (directly or indirectly) on a parameter is also reported. 5856 5857 Ex: 5858 check movable_accept_statements (possible, Log.Report_Rendezvous); 5859 58605.34.3 Tips 5861----------- 5862 5863The list of <entity> given to the rule can be, for example, procedures 5864whose execution must be part of the accept statement for logical 5865reasons. They can also be global variables, when the rendezvous is 5866intended to prevent concurrent access to these variables. 5867 5868 5869File: adacontrol_ug.info, Node: Naming_Convention, Next: No_Operator_Usage, Prev: Movable_Accept_Statements, Up: Rules reference 5870 58715.35 Naming_Convention 5872====================== 5873 5874This rule controls the form of identifiers to make sure that they follow 5875the project's naming conventions. Different naming conventions can be 5876specified, depending on the kind of Ada entity that the name is refering 5877to. 5878 58795.35.1 Syntax 5880------------- 5881 5882 <control_kind> naming_convention 5883 ([root] [others] {<location>} [<type_spec>] <filter_kind>, 5884 [case_sensitive|case_insensitive] [not] "<pattern>" 5885 {, ...}); 5886 <location> ::= global | local | unit 5887 <type_spec> ::= <entity> | {<category>} 5888 <category> ::= () | access | array | delta | digits | mod | 5889 private | protected | range | record | tagged | task 5890 <filter_kind> ::= All | 5891 Type | 5892 Discrete_Type | 5893 Enumeration_Type | 5894 Integer_Type | 5895 Signed_Integer_Type | 5896 Modular_Integer_Type | 5897 Floating_Point_Type | 5898 Fixed_Point_Type | 5899 Binary_Fixed_Point_Type | 5900 Decimal_Fixed_Point_Type | 5901 Array_Type | 5902 Record_Type | 5903 Regular_Record_Type | 5904 Tagged_Type | 5905 Interface_Type | 5906 Class_Type | 5907 Access_Type | 5908 Access_To_Regular_Type | 5909 Access_To_Tagged_Type | 5910 Access_To_Class_Type | 5911 Access_To_SP_Type | 5912 Access_To_Task_Type | 5913 Access_To_Protected_Type | 5914 Private_Type | 5915 Private_Extension | 5916 Generic_Formal_Type | 5917 Variable | 5918 Regular_Variable | 5919 Field | 5920 Discriminant | 5921 Record_Field | 5922 Protected_Field | 5923 Procedure_Formal_Out | 5924 Procedure_Formal_In_Out | 5925 Generic_Formal_In_Out | 5926 Constant | 5927 Regular_Constant | 5928 Regular_Static_Constant | 5929 Regular_Nonstatic_Constant | 5930 Named_Number | 5931 Integer_Number | 5932 Real_Number | 5933 Enumeration | 5934 Sp_Formal_In | 5935 Generic_Formal_In | 5936 Loop_Control | 5937 Occurrence_Name | 5938 Entry_Index | 5939 Label | 5940 Stmt_Name | 5941 Loop_Name | 5942 Block_Name | 5943 Subprogram | 5944 Procedure | 5945 Regular_Procedure | 5946 Protected_Procedure | 5947 Generic_Formal_Procedure | 5948 Function | 5949 Regular_Function | 5950 Protected_Function | 5951 Generic_Formal_Function | 5952 Entry | 5953 Task_Entry | 5954 Protected_Entry | 5955 Package | 5956 Regular_Package | 5957 Generic_Formal_Package | 5958 Task | 5959 Task_Type | 5960 Task_Object | 5961 Protected | 5962 Protected_Type | 5963 Protected_Object | 5964 Exception | 5965 Generic | 5966 Generic_Package | 5967 Generic_Sp | 5968 Generic_Procedure | 5969 Generic_Function | 5970 Renaming | 5971 Object_Renaming | 5972 Exception_Renaming | 5973 Package_Renaming | 5974 Subprogram_Renaming | 5975 Procedure_Renaming | 5976 Function_Renaming | 5977 Generic_Renaming | 5978 Generic_Package_Renaming | 5979 Generic_Sp_Renaming | 5980 Generic_Procedure_Renaming | 5981 Generic_Function_Renaming 5982 59835.35.2 Action 5984------------- 5985 5986The first parameter defines the kind of declaration to which the rule is 5987applicable, and other parameters are strings, interpreted as regular 5988expressions that define the patterns that must be matched (or not). 5989*Note Syntax of regular expressions::. 5990 5991 If one or more <location> keyword is specified, the pattern applies 5992only to identifiers declared at the corresponding place. Otherwise, the 5993pattern applies to all identifiers, irrespectively of where they are 5994declared. The definition of locations is as follows: 5995 * "unit": The identifier is the defining name of a compilation unit. 5996 * "global": The identifier is declared in a package or a generic 5997 package, possibly nested in other packages or generic packages. 5998 * "local": All other cases. 5999 6000 In the case of objects (corresponding to filters in the "variable" 6001and "constant" families) and functions (in the "function" family), it is 6002possible to be more specific, depending on the type of the object (or 6003the return type of the function), as specified by the <type_spec> 6004modifier. The <type_spec> modifier is either a single <entity> giving 6005the type of the object or one or more <category> keywords. As usual, 6006the whole syntax for entities is allowed for <entity>. *Note Specifying 6007an Ada entity name::. The meaning of <category> is: 6008 * "()": The object is of an enumerated type. 6009 * "access": The object is of an access type. 6010 * "array": The object is of an array type. 6011 * "delta": The object is of a fixed point type (it is not currently 6012 possible to distinguish ordinary fixed point types from decimal 6013 fixed point types). 6014 * "digits": The object is of a floating point type. 6015 * "mod": The object is of a modular type. 6016 * "private": The object is of a private type (including private 6017 extensions). 6018 * "protected": The object is of a protected type. 6019 * "range": The object is of a signed integer type. 6020 * "record": The object is of an (untagged) record type. 6021 * "tagged": The object is of a tagged type (including type 6022 extensions). 6023 * "task": The object is of a task type. 6024 6025 For a given layer of the hierarchy (i.e. "variable", 6026"regular_variable"), only the most specific filter is applicable, i.e. 6027"standard.boolean variable" will apply to all boolean variables, while 6028plain "variable" will apply to other variables. See examples below. 6029 6030 If "case_sensitive" is specified, pattern matching considers casing. 6031Otherwise ("case_insensitive"), casing is irrelevant. The default is 6032"case_insensitive", and can be changed by setting the variable 6033"Default_Case_Sensitivity", see below. Note that the rule checks the 6034name only at the place where it is declared; casing might be different 6035when the name is used later. 6036 6037 If a pattern is preceded by "not", then the pattern must not be 6038matched (i.e. the rule reports when there is a match). 6039 6040 The rule will be activated if an identifier is declared that does not 6041match any of the "positive" patterns (the ones without "not"), or if it 6042matches any of the "negative" patterns (the ones with a "not"). If only 6043negative patterns are given, it is implicitely assumed that all other 6044identifiers are OK. In other words, accepted identifiers must have the 6045form of (at least) one of the "positive" patterns (if any), but not the 6046form of one of the "negative" patterns. 6047 6048 The filter kinds are organized hierarchically, as reflected by 6049indentation in the syntax above. To be valid, the name must match the 6050patterns specified for its own filter, and for all filters above it in 6051the hierarchy. For example, a modular type declaration must follow the 6052rules (if specified) for "all", "type","discrete_type", "integer_type" 6053and "modular_integer_type". However, if a filter kind is preceded by 6054"others", the rule will apply only if there is no applicable positive 6055pattern deeper in the hierarchy; similarly, if a filter kind is preceded 6056by "root", no rule above it in the hierarchy is considered (neither for 6057itself nor its children). This is useful to make exceptions to a more 6058general rule. For example: 6059 6060 -- All identifiers must have at least 3 characters: 6061 check naming_convention (all, "..."); 6062 -- And start with an upper-case letter 6063 -- (will not apply to types and access types, because of "others" and 6064 -- other rules given below) 6065 check naming_convention (others all, case_sensitive "^[A-Z]"); 6066 6067 -- Exception to the rule for "all": 6068 -- No minimum length for "for loop" identifiers, but must be 6069 -- all uppercase 6070 check naming_convention (root loop_control, case_sensitive "^[A-Z]+$"); 6071 6072 -- Types must start with "t", then an upper-case letter: 6073 -- (will not apply to access types, because of "others" and 6074 -- other rule given below) 6075 check naming_convention (others type, case_sensitive "^t[A-Z]"); 6076 6077 -- Access types must start with "ta", then an upper-case letter: 6078 check naming_convention (access_type, case_sensitive "^ta[A-Z]"); 6079 6080 -- Boolean variables, and only these, must start with "Is_" or 6081 -- "Has_": 6082 check naming_convention (variable, not "^Is_", not "^Has_"); 6083 check naming_convention (standard.boolean variable, "^Is_", "^Has_"); 6084 6085 -- Functions returning Wide_String must start with "Wide_", and 6086 -- similarly for Wide_Wide_String, and no other: 6087 check naming_convention (standard.wide_string function, 6088 "^Wide_", 6089 not "^Wide_Wide_"); 6090 check naming_convention (standard.wide_wide_string function, 6091 "^Wide_Wide_"); 6092 check naming_convention (function, not "^Wide_"); 6093 6094 It is of course not necessary to specify all the filter kinds, nor to 6095specify filters down to the deepest level; if you specify a rule for 6096"type", it will be applied to all type declarations, whether there is a 6097more specific rule or not. 6098 6099 Subtypes and derived types must follow the rule for their respective 6100original (full) type. Incomplete type declarations are not checked, 6101since their corresponding full declaration is (normally) checked. 6102Private types (including of course the full declaration of a private 6103type) follow the rule for private types, not the rules for their full 6104type view (otherwise it would be privacy breaking). 6105 6106 Renamings are treated specially: if there is no explicit rule for a 6107given renaming, the applicable rule is the one for the renamed entity. 6108 6109 Ex: 6110 -- Predefined name is forbidden: 6111 check naming_convention (all, not "Integer"); 6112 6113 -- Types must either start or end with T 6114 check naming_convention (type, case_sensitive "^T_", 6115 case_sensitive "_T$"); 6116 6117 -- "Upper_Initials" naming convention: 6118 check naming_convention 6119 (all, case_sensitive "^[A-Z][a-z0-9]*(_[A-Z0-9][a-z0-9]*)*$"); 6120 6121 -- All global variables must start with "G_" 6122 check naming_convention (global variable, "G_"); 6123 61245.35.3 Variables 6125---------------- 6126 6127The rule provides a variable that allows to specify the default casing. 6128 6129Variable Values Default Effect 6130Default_Case_Sensitivityon/offoff if "on", controls that do not 6131 explicitely specify case sensitivity 6132 are case sensitive. 6133 61345.35.4 Tips 6135----------- 6136 6137The rule only checks the casing of identifiers at the place where they 6138are declared. A useful companion rule is "style (casing_identifier, 6139original)", which ensures that every use of the identifier will use the 6140same casing as in the declaration. *Note Style::. Similarly, in the 6141case of a subprogram and its parameters, the check is not done on the 6142body if there is an explicit specification (since specification and body 6143have to match anyway). 6144 6145 The rule does not check the names of operators, since it would make 6146little sense to have naming conventions for things whose name is 6147imposed. If you want to prevent the definition of operators, refer to 6148the rule "declarations" and its subrules "operator", 6149"equality_operator", and"predefined_operator". *Note Declarations::. 6150 6151 Remember that a Regexp matches if the pattern matches any part of the 6152identifier. Use "^" and "$" to match the beginning (resp. end) of the 6153name, or both. 6154 6155 A constant is considered static for the purpose of 6156"Regular_Static_Constant" and "Regular_Nonstatic_Constant" if it is of a 6157discrete type initialized by a static expression, or if it is an 6158aggregate whose components all have static values. This is different 6159from the official definition of "static" in the language, but 6160corresponds to what most users would expect. 6161 6162 "class_type" is applicable to subtypes that designate a class-wide 6163type. Similarly, "access_to_class_type" is applicable to access types 6164whose designated type is class-wide. 6165 6166 If you don't want any special rule for renamings (not even the one 6167that applies to the renamed entity), specify: 6168 check naming_convention (renaming, ""); 6169 This imposes no constraint on renamings, but since it is specified 6170explicitely, the implicit rule for the renamed entity won't apply. 6171 6172 The 'rules' directory of Adacontrol contains two files named 6173'no_standard_entity.aru' and 'no_system_entity.aru'. These are files 6174that contain a naming_convention rule that forbids the declaration of 6175names declared in packages 'Standard' and 'System', respectively. You 6176can simply "source" these files from your own rule file (or copy the 6177content) if you want to disallow these identifiers. 6178 6179 Like usual, naming_convention rule can be given multiple times, and 6180can be disabled. However, consider the following: 6181 Rule1 : check naming_convention (constant, "^c_"); 6182 Rule2 : check naming_convention (constant, "^const_"); 6183 The rule will trigger if a constant is declared that does not start 6184with either "c_" or "const_". But here, we have two different rule 6185labels. The message will refer to the first label encountered in the 6186rule file; this is the label that must be mentionned in a disabling 6187comment, unless you simply disable "naming_convention". 6188 61895.35.5 Limitations 6190------------------ 6191 6192This rule does not support wide characters outside the basic Latin-1 6193set. 6194 6195 6196File: adacontrol_ug.info, Node: No_Operator_Usage, Next: Non_Static, Prev: Naming_Convention, Up: Rules reference 6197 61985.36 No_Operator_Usage 6199====================== 6200 6201This rule controls integer types that do not use any arithmetic 6202operators, which indicates that they might be replaceable with other 6203kinds of types. 6204 62055.36.1 Syntax 6206------------- 6207 6208 <control_kind> no_operator_usage [([<category>] <parameter> [,<parameter>])]; 6209 <category> ::= range | mod 6210 <parameter> ::= [<filter>] <observed> 6211 <filter> ::= not | ignore | report 6212 <observed> ::= relational | logical | indexing 6213 62145.36.2 Action 6215------------- 6216 6217This rule controls integer types where no arithmetic operator of the 6218type is used in the program. If the <category> is 'range', the control 6219applies only to signed integer types; if it is 'mod', it applies only to 6220modular integer types; otherwise, it applies to both. 6221 6222 When such a type is found, it migh be interesting to find out other 6223usages to determine a possible better kind of type. "relational" means 6224that relational operators ('<', '<=', '>', '>=', 'in', 'not in') are 6225used, "logical" means that logical operators ('and', 'or', 'xor') are 6226used, and "indexing" means that the type is used as an index in some 6227array type. 6228 6229 If an <observed> property is given as parameter, only types that 6230feature the property are controlled, or those that do not feature the 6231property if the <observed> is preceded by "not". If the <observed> is 6232preceded by "ignore" the type is controlled irrrespectively of the 6233property, and the message does not mention it at all, while if it is 6234preceded by "report", the message still mentions whether the <observed> 6235is used or not. 6236 6237 Without parameters, the rule is equivalent to "ignore relational, 6238ignore logical, ignore indexing" (i.e. it controls all types that do 6239not use any arithmetic operator). 6240 6241 This rule can be given only once for each combination of values of 6242the parameters. 6243 6244 Ex: 6245 -- Simply report types that don't use arithmetic operators: 6246 check no_operator_usage; 6247 6248 -- Do the same, but mention if indexing/logical ops are used: 6249 check no_operator_usage (report indexing, report logical); 6250 6251 -- Find modular integer types that use only logical operators: 6252 check no_operator_usage (mod logical); 6253 6254 -- Find integer types that don't use artihmetic operators and are 6255 -- not used for indexing nor in relational operators: 6256 check no_operator_usage (not indexing, not relational); 6257 62585.36.3 Tips 6259----------- 6260 6261An integer type that uses no operator at all is a good candidate to be 6262replaced by an enumerated type. A modular type where only logical 6263operators are used is likely to be used as a bit field or a set, and is 6264a good canditate for being replaced by an array of booleans. 6265 6266 The rule does not make a distinction between predefined and 6267user-defined operators. On the other hand, only calls to operators are 6268considered, operators used for example as actual generic parameters in 6269instantiations are not considered. 6270 6271 The rule applies also to private types whose full declaration is an 6272integer type. 6273 6274 6275File: adacontrol_ug.info, Node: Non_Static, Next: Not_Elaboration_Calls, Prev: No_Operator_Usage, Up: Rules reference 6276 62775.37 Non_Static 6278=============== 6279 6280This rule controls that expressions used in certain contexts are static. 6281 62825.37.1 Syntax 6283------------- 6284 6285 <control_kind> non_static [(<subrule> {, <subrule>})]; 6286 <subrule> ::= constant_initialization | variable_initialization | 6287 index_constraint | discriminant_constraint | 6288 instantiation | index_check 6289 62905.37.2 Action 6291------------- 6292 6293The <subrule> defines the elements that are required to be static: 6294 * "constant_initialization": expressions used as initial value in 6295 constant declarations. 6296 * "variable_initialization": expressions used as initial value in 6297 variable declarations. 6298 * "index_constraint": expressions used in index constraints (aka 6299 array sizes). 6300 * "discriminant_constraint": expressions used in discriminant 6301 constraints 6302 * "instantiation": expressions used as generic actual parameters in 6303 instantiations. 6304 * "index_check": expressions used as indices must satisfy statically 6305 the index check. I.e., the expression needs not be static, but it 6306 should be statically provable that the index check cannot fail. 6307 6308 If no keyword is given, all contexts are controlled. 6309 6310 Ex: 6311 check non_static (index_constraint); 6312 63135.37.3 Limitations 6314------------------ 6315 6316Currently, "constant_initialization" and "variable_initialization" do 6317not control structured (record and array) variables. For access 6318variables, the initial value is considered static only if it is a plain 6319'null'. This may improve in future versions of AdaControl. 6320 63215.37.4 Tips 6322----------- 6323 6324If all index and discriminant constraints are static, the space occupied 6325by data structures is computable from the program text. This rule is 6326useful to enforce this in contexts where the memory space must be 6327statically determined. 6328 6329 6330File: adacontrol_ug.info, Node: Not_Elaboration_Calls, Next: Not_Selected_Name, Prev: Non_Static, Up: Rules reference 6331 63325.38 Not_Elaboration_Calls 6333========================== 6334 6335This rule controls that certain subprograms (or allocators) are called 6336only during program initialization. 6337 63385.38.1 Syntax 6339------------- 6340 6341 <control_kind> not_elaboration_calls (<entity>|new {, <entity>|new}); 6342 63435.38.2 Action 6344------------- 6345 6346The <entity> parameters are callable entities (procedure, function or 6347entry calls). As usual, the whole syntax for entities is allowed for 6348<entity>. *Note Specifying an Ada entity name::. This rule controls 6349calls to the indicated callable entities, or allocators if "new" is 6350given, that are performed at any time except during the elaboration of 6351library packages. 6352 6353 Ex: 6354 search not_elaboration_calls (Data.Initialize, new); 6355 63565.38.3 Limitations 6357------------------ 6358 6359Due to an (allowed by ASIS standard) limitation of ASIS-for-Gnat, the 6360rule will not detect calls to subprograms that are implicitely defined, 6361like calling a '"+"' on 'Integer'. Fortunately, it is very unlikely 6362that the user would want to forbid that kind of calls in non-elaboration 6363code. 6364 6365 Note also that calls that cannot be statically determined, like calls 6366to dispatching operations or calls through pointers to subprograms 6367cannot be detected either. 6368 6369 6370File: adacontrol_ug.info, Node: Not_Selected_Name, Next: Object_Declarations, Prev: Not_Elaboration_Calls, Up: Rules reference 6371 63725.39 Not_Selected_Name 6373====================== 6374 6375This rule controls that certain entities are always refered to using 6376selected notation, even in the presence of 'use' clauses. 6377 63785.39.1 Syntax 6379------------- 6380 6381 <control_kind> not_selected_name 6382 (<exception places>, <entity> {, <entity>}); 6383 <exception places> ::= none | unit | compilation | family 6384 63855.39.2 Action 6386------------- 6387 6388A name is "selected" if it is prefixed by the name of the construct 6389where it is declared. Only one level of prefix is required, unless the 6390prefix itself is the target of a not_selected_name rule. 6391 6392 The first parameter specifies places where the rule is not enforced, 6393i.e. where simple notation is allowed: 6394 * "none": selected notation is always required. 6395 * "unit": selected notation is not required within the program unit 6396 where the entity is declared. 6397 * "compilation": selected notation is not required within the 6398 compilation unit where the entity is declared. 6399 * "family": selected notation is not required within the compilation 6400 unit where the entity is declared, nor within its (direct or 6401 indirect) children. 6402 6403 Other parameters indicate the <entity> to which the rule applies. As 6404usual, the whole syntax for entities is allowed for <entity>. *Note 6405Specifying an Ada entity name::. 6406 6407 Ex: 6408 check not_selected_name (unit, all Instance); 6409 search not_selected_name (none, Pack.T); 6410 64115.39.3 Tip 6412---------- 6413 6414Note that, as usual, the entity can be given in the form "all name". 6415This is especially useful for types that must always be declared with a 6416special name (like 'Instance', 'Object', 'T') and are intended to be 6417always used with the name of the enclosing package. 6418 6419 6420File: adacontrol_ug.info, Node: Object_Declarations, Next: Parameter_Aliasing, Prev: Not_Selected_Name, Up: Rules reference 6421 64225.40 Object_Declarations 6423======================== 6424 6425This rule controls various aspects of object (constants and variables) 6426declarations. 6427 64285.40.1 Syntax 6429------------- 6430 6431 <control_kind> object_declarations (min_integer_span, <min_spec> 6432 {, <min_spec>}); 6433 <control_kind> object_declarations (type, <type_spec> {, <type_spec>}); 6434 <control_kind> object_declarations (volatile_no_address); 6435 <control_kind> object_declarations (address_not_volatile); 6436 <min_spec> ::= [constant | variable] <value> 6437 <type_spec> ::= [constant | variable] <entity> 6438 64395.40.2 Action 6440------------- 6441 6442The action depends on the subrule. 6443 * "min_integer_span": controls that every object of an integer type 6444 has a subtype that covers at least the indicated number of values. 6445 Different values can be specified for variables and constants; if 6446 no modifier ("constant" or "variable") is supplied, the value 6447 applies to both. 6448 6449 This subrule can be given only once for each combination of 6450 check/search/count and constant/variable. 6451 * "type": controls every object whose (sub)type matches <entity>. As 6452 usual, the whole syntax for entities is allowed for <entity>. 6453 *Note Specifying an Ada entity name::. If the <entity> is a 6454 subtype, only objects of that exact subtype are controlled; if the 6455 <entity> is a type, objects declared with the type or any subtype 6456 of it are controlled. The control can be restricted to only 6457 variables or only constants; if no modifier ("constant" or 6458 "variable") is supplied, both are controlled. 6459 6460 This subrule can be given only once for each combination of 6461 <entity> and constant/variable. 6462 * "volatile_no_address": controls variables that are the target of a 6463 pragma volatile, but have no address clause. Constants are not 6464 controlled, since it would be very strange to have a volatile 6465 constant... 6466 6467 Since this subrule has no parameters, it can be given only once. 6468 * "address_not_volatile": controls variables that have an address 6469 clause, but are not the target of a pragma volatile. Constants are 6470 not controlled, since it would be very strange to have a volatile 6471 constant... 6472 6473 Since this subrule has no parameters, it can be given only once. 6474 6475 Ex: 6476 check object_declarations (min_integer_span, variable 5, constant 10); 6477 6478 count object_declarations (min_integer_span, 8); 6479 -- Same value for variables and constants 6480 6481 search object_declarations (volatile_no_address); 6482 search object_declarations (address_not_volatile); 6483 64845.40.3 Tip 6485---------- 6486 6487The "min_integer_span" rule can be useful for detecting variables that 6488should use an enumerated type rather than an integer type. 6489 64905.40.4 Limitation 6491----------------- 6492 6493Due to a shortcomming of the ASIS interface, the subrules 6494"volatile_no_address" and "address_not_volatile" will not detect 6495variables of a class-wide type that are volatile due to a pragma 6496volatile applying to the class-wide type. If the pragma applies to the 6497variable, the subrule will work correctly. A pragma volatile applied to 6498a class-wide type is detected by the rule "uncheckable". *Note 6499Uncheckable::. 6500 6501 Declaring a class-wide _type_ as volatile seems very peculiar 6502anyway... 6503 6504 6505File: adacontrol_ug.info, Node: Parameter_Aliasing, Next: Parameter_Declarations, Prev: Object_Declarations, Up: Rules reference 6506 65075.41 Parameter_Aliasing 6508======================= 6509 6510This rule controls aliased use of variables in subprogram calls. 6511 65125.41.1 Syntax 6513------------- 6514 6515 <control_kind> parameter_aliasing [([with_in] <level>)]; 6516 <level> ::= Certain | Possible | Unlikely 6517 65185.41.2 Action 6519------------- 6520 6521This rule identifies calls where the same variable is given as an actual 6522to more than one 'out' or 'in out' parameter, like in the following 6523example: 6524 procedure Proc (X, Y : out Integer); 6525 ... 6526 Proc (X => V, Y => V); 6527 6528 If the modifier "'with_in'" is given, aliasing between 'out' or 'in 6529out' parameters and 'in' parameters is also considered (unless the 'in' 6530parameter is of a user-defined by-copy type). Although aliasing of 'in' 6531parameters is generally considered less of an issue, it can lead to 6532unexpected results when the parameter is passed by reference. 6533 6534 There are many cases where aliasing cannot be determined statically. 6535The optional parameter specifies how aggressively the rule will check 6536for possible aliasings. Possible values are (case irrelevant): 6537 * Certain (default): Only cases where aliasing is statically certain 6538 are output. 6539 * Possible: In addition, cases where aliasing may occur depending on 6540 the value of an indexed component are output. These may or may not 6541 be true aliasing, depending on the algorithm. For example, given: 6542 Swap (Tab (I), Tab (J)); 6543 there is no aliasing, unless 'I' equals 'J'. 6544 6545 If all expressions used for indexing in both variables are static, 6546 the rule will be able to eliminate the diagnosis of aliasing (if 6547 the values are different). This avoids unnecessary messages in 6548 cases like: 6549 Swap (Tab (1), Tab (2)); 6550 6551 * Unlikely: In addition, cases where aliasing may occur due to access 6552 variables pointing to the same variable are output. These may or 6553 may not be true aliasing, depending on the algorithm, but should 6554 normally occur only as the result of very strange practices, like 6555 in the following example: 6556 type R is 6557 record 6558 X : aliased Integer; 6559 end record; 6560 X : R; 6561 Y : Access_All_Integer := R.X'access; 6562 ... 6563 P (X, Y.all); 6564 There will be no false positive with "Certain". There will be no 6565false negative with "Unlikely" (but many false positives). "Possible" 6566is somewhere in-between. 6567 6568 The rule may be specified at most once for each value of the 6569parameter. This allows for example to "check" for "Certain" and 6570"search" for "Possible". 6571 6572 Ex: 6573 check parameter_aliasing (with_in certain); 6574 search parameter_aliasing (Possible); 6575 6576 Note that the rule is quite clever: it will consider partial aliasing 6577(like a record variable as one parameter, and one of its components as 6578another parameter), and will not be fooled by renamings. 6579 65805.41.3 Limitation 6581----------------- 6582 6583Due to a weakness of the ASIS standard, dispatching calls are not 6584analyzed. Some calls cannot obviously have aliasing (if there is only 6585one parameter, or if there are no variables in the parameters f.e.); 6586other calls are detected by the rule "uncheckable". *Note 6587Uncheckable::. 6588 6589 6590File: adacontrol_ug.info, Node: Parameter_Declarations, Next: Positional_Associations, Prev: Parameter_Aliasing, Up: Rules reference 6591 65925.42 Parameter_Declarations 6593=========================== 6594 6595This rule controls various characteristics of the declaration of 6596parameters for all callable entities (i.e. functions, procedures and 6597entries). 6598 65995.42.1 Syntax 6600------------- 6601 6602 <control_kind> parameter_declarations (<subrule> [,<bounds>] {,<callable>}); 6603 <subrule> ::= all_parameters | in_parameters | 6604 defaulted_parameters | out_parameters | 6605 in_out_parameters | access_parameters | 6606 tagged_parameters | class_wide_parameters | 6607 single_out_parameter 6608 <bounds> ::= min|max <value> [, min|max <value> ] 6609 <callable> ::= function | procedure | 6610 dispatching_function | dispatching_procedure | 6611 protected_function | protected_procedure | 6612 protected_entry | task_entry 6613 66145.42.2 Action 6615------------- 6616 6617The first parameter is a subrule keyword. "single_out_parameter" has no 6618parameter; all other subrules require one or two bounds. 6619 * "all_parameters": Controls callable entities whose number of 6620 parameters is less than the given "min" or greater than the given 6621 "max". "min" defaults to 0 and "max" to infinity. 6622 * "in_parameters", "out_parameters", "in_out_parameters": Do the 6623 same, counting only parameters of modes 'in', 'out', or 'in out' 6624 respectively. 6625 * "defaulted_parameters": Does the same, counting only parameters 6626 declared with an explicit default expression. 6627 * "access_parameters": Does the same, counting only (anonymous) 6628 access parameters. 6629 * "tagged_parameters": Does the same, counting only parameters of a 6630 specific tagged type. 6631 * "class_wide_parameters": Does the same, counting only parameters of 6632 a class-wide type. 6633 * "single_out_parameter": Controls callable entities that have 6634 exactly one 'out' parameter. Procedures with a single 'out' 6635 parameter might be candidates to becoming functions. 6636 6637 If one or more <callable_kind> is specified after the <value>, the 6638rule applies only to the corresponding declaration(s), otherwise it 6639applies to all callable entities. "dispatching_function" and 6640"dispatching_procedure" allow different counts for dispatching 6641subprograms (i.e. primitive subprograms of a tagged type). If 6642"dispatching_function" or "dispatching_procedure" is not explicitely 6643specified, "function" (conversely "procedure") applies also to 6644dispatching functions (conversely dispatching procedures). 6645 6646 This rule can be given once for each of check, search, and count for 6647each subrule and each kind of entity. This way, it is possible to have 6648a level considered a warning (search), and one considered an error 6649(check). 6650 6651 Ex: 6652 -- Callable entities should preferably not have more than 5 6653 -- parameters, and in any case not have more that 10 parameters, 6654 check parameter_declarations (all_parameters, max 10); 6655 search parameter_declarations (all_parameters, max 5); 6656 6657 -- All functions must have parameters and no out or in out 6658 -- parameters (allowed in Ada 2012): 6659 check parameter_declarations (all_parameters, min 1, function); 6660 check parameter_declarations (out_parameters, max 0, function); 6661 check parameter_declarations (in_out_parameters, max 0, function); 6662 6663 -- A regular (not protected) procedure with one out parameter 6664 -- should be replaced by a function 6665 check parameter_declarations (single_out_parameter, procedure); 6666 6667 -- Find all callable entities with class-wide parameters: 6668 search parameter_declarations (class_wide_parameters, max 0); 6669 6670 -- Dispatching operations may have only one parameter of a tagged type: 6671 check parameter_declarations (tagged_parameter, 6672 max 1, 6673 dispatching_function, 6674 dispatching_procedure); 6675 66765.42.3 Tips 6677----------- 6678 6679This rule applies to generic subprograms as well as to regular ones. On 6680the other hand, it does not apply to generic formal subprograms, since 6681instantiations would only be possible with subprograms which are 6682supposed to have been already controlled. 6683 6684 Instantiations are also controlled; the number of parameters is taken 6685from the corresponding generic. 6686 6687 Note that this rule controls only "regular" parameters, not generic 6688formal parameters. 6689 6690 Note that dispatching operations have necessarily at least one tagged 6691parameter, although a "max 0" could be specified in the example above. 6692If you do this, all declarations of dispatching subprograms will be 6693controlled. Maybe that's what you want... 6694 6695 6696File: adacontrol_ug.info, Node: Positional_Associations, Next: Potentially_Blocking_Operations, Prev: Parameter_Declarations, Up: Rules reference 6697 66985.43 Positional_Associations 6699============================ 6700 6701This rule controls the use of positional associations (as opposed to 6702named associations) in all kinds of associations. 6703 67045.43.1 Syntax 6705------------- 6706 6707 <control_kind> positional_associations [(<subrule>, <max_allowed> 6708 [, <category> {, <entity>}])]; 6709 <subrule> ::= all | all_positional | same_type 6710 <category> ::= [not_operator] call | pragma | discriminant | 6711 instantiation | array_aggregate | record_aggregate | 6712 enumeration_representation 6713 67145.43.2 Action 6715------------- 6716 6717The rule controls pragmas, discriminants, calls, aggregates, or 6718instantiations that use too many positional associations. The 6719definition of "too many" depends on the subrule: 6720 * "all": when positional associations are given in a place where 6721 there is more than <max_allowed> associations (both positional and 6722 named). 6723 * "all_positional": when there is more than <max_allowed> positional 6724 associations. 6725 * "same_type": when more than <max_allowed> positional parameters are 6726 of the same type. 6727 6728 In addition, a <category> can be specified to restrict the rule to 6729specific kinds of associations; if not specified, all associations are 6730controlled. The categories carry their obvious meaning, with the 6731distinction that "array_aggregate" applies only to "true" array 6732aggregates, while "enumeration_representation" applies to the special 6733array aggregate used in enumeration representation clauses. Note that 6734the "same_type" subrule is not allowed for the "pragma" category. For 6735"pragma", "call", and "instantiation", entities can also be specified; 6736such entities are exempted from the rule (i.e. the rule will not 6737control these entities). See examples below. 6738 6739 For calls, positional association is not reported for operators that 6740use infix notation (since named notation is not possible); in addition, 6741if the "not_operator" modifier is specified before the "call" keyword 6742(not allowed elsewhere), positional association is never reported for 6743operators, even if they are called with the syntax of a normal function 6744call (i.e. 'Pack."+" (A,B)'). Calls to subprograms that are attributes 6745are not reported either, since named notation is not allowed for them. 6746 6747 This rule can be specified once for each combination of <subrule>, 6748<category>, and <control_kind>. This way, it is possible to have a 6749number of positional associations considered a warning (search), and one 6750considered an error (check). Of course, this makes sense only if 6751<max_allowed> for search is greater than the one for check. It is also 6752possible to have different criteria for each category. 6753 6754 If no parameter is given, it is equivalent to 6755"'positional_associations (all, 0)'", i.e. all positional associations 6756are controlled. 6757 6758 Ex: 6759 -- All positional associations: 6760 check positional_associations; 6761 6762 -- All positional associations in aggregates: 6763 check positional_associations(all, 0, array_aggregate); 6764 check positional_associations(all, 0, record_aggregate); 6765 6766 -- All positional associations with more than 3 elements: 6767 search positional_associations (all, 3); 6768 6769 -- Positional associations in calls with more than 3 params of the same type 6770 search positional_associations (same_type, 3, call); 6771 6772 -- Positional associations in calls with more than 2 elements (except 6773 -- calls to any subprogram called Put) 6774 search positional_associations(all, 2, call, all put); 6775 67765.43.3 Tips 6777----------- 6778 6779There are two kinds of calls where the rule does not complain about 6780usage of positional association: infix operator calls (since requiring 6781named notation would not allow infix notation any more), and calls to 6782subprograms that are attributes (since named notation is not allowed for 6783these). 6784 6785 For the purpose of the "same_type" subrule, integer literals are 6786considered of the same type as any parameter of an integer type, and 6787similarly for other universal values. The reason is that this rule is 6788intended to avoid confusion between parameters, when strong typing would 6789not detect an inversion of parameters for example; such a case would 6790happen between parameters of a universal type. 6791 6792 For calls, another rule controls positional associations according to 6793the value of parameters rather than their number: *Note 6794Insufficient_Parameters::. 6795 6796