Next: Introduction
This is the AdaControl User Guide. It describes how to install and use AdaControl. Please refer to the AdaControl Programmer Manual to learn how to add new kinds of rules to AdaControl.
AdaControl is Copyright © 2005-2021 Eurocontrol/Adalog, except for some specific modules that are © 2006 Belgocontrol/Adalog, © 2006 CSEE/Adalog, © 2006 SAGEM/Adalog, or © 2015 Alstom/Adalog. AdaControl is free software; you can redistribute it and/or modify it under terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. This unit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License distributed with this program; see file COPYING. If not, write to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
As a special exception, if other files instantiate generics from this program, or if you link units from this program with other files to produce an executable, this does not by itself cause the resulting executable to be covered by the GNU General Public License. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU Public License.
This document is Copyright © 2005-2021 Eurocontrol/Adalog. This document may be copied, in whole or in part, in any form or by any means, as is or with alterations, provided that (1) alterations are clearly marked as alterations and (2) this copyright notice is included unmodified in any copy.
Next: Installation, Previous: Top, Up: Top
AdaControl is an Ada rules controller. It is used to control that Ada software meets the requirements of a number of parameterizable rules. It is not intended to supplement checks made by the compiler, but rather to search for particular violations of good-practice rules, or to check that some rules are obeyed project-wide. AdaControl can also be handy to make statistics about certain usages of language features, or simply to search for the occurrences of particular constructs; its scope is therefore not limited to enforcing programming rules, although it is of course one of its main goals.
AdaContol can also generate commands for suggested fixes to a number
of violations; its companion program adactl_fix can perform
these fixes automatically, or they can be fixed interactively from
GPS.
AdaControl is a commercial product of Adalog with professional grade support available. Getting support is highly recommended for industrial projects. Adacontrol can also be customized or extended to match your special needs, please refer to Support or contact Adalog at info@adalog.fr.
| • Features | ||
| • Support | ||
| • History | ||
| • References |
Next: Support, Previous: Introduction, Up: Introduction
AdaControl analyzes a set of Ada units, according to parameterizable controls. Controls can be given from the command line, from a file, or interactively. There is a wide range of controls available. Some are quite simple (although very useful):
Other rules are quite sophisticated:
and much, much more... See Rules reference for the complete
reference for all possible controls. The rules directory
contains a set of command files; especially, the file verif.aru
contains some commonly accepted rules. It is a good starting point for
devising your own set of rules.
AdaControl is very simple to use. It takes, as parameters, a list of units to process and a list of commands that define the controls to apply. The complete syntax of the commands is described in chapter Command language reference.
AdaControl produces messages to the standard output, unless
redirected. Several levels of messages are defined (i.e. error or found),
depending on the kind of the control (i.e. check or search).
Rules can be locally disabled for a part of the source code, and various options can be passed to the program.
Ex:
Given the following package:
package Pack is pragma Pure (Pack); ... end Pack;
The following command:
adactl -l "search pragmas (pure)" pack
produces the following result (displayed to standard output):
pack.ads:2:4: Found: PRAGMAS: use of pragma Pure
AdaControl integrates nicely in environments such as GPS (see Running AdaControl from GPS), AdaGide (see Running AdaControl from AdaGide), or emacs (see Report messages). In those environments, you can run AdaControl from menus or by just clicking on a button!
Next: History, Previous: Features, Up: Introduction
Adalog provides commercial support for AdaControl. Support includes the following benefits:
Adalog cannot correct problems whose origin is due to compiler bugs or defects in the implementation of ASIS (contact your compiler provider for support on these problems). However, Adalog will do its best effort to find workarounds for such problems.
In addition, Adalog can provide various services:
For pricing information about support contract and other services, please contact info@adalog.fr.
There is a Wiki for questions about AdaControl at
https://sourceforge.net/p/adacontrol/wiki/Home/. This is the
place to ask for information, make suggestions, or get help from the
community.
For general casual discussions, you can follow us on Twitter as @adacontrol_prog (sorry, the name @adacontrol was already used!)
For problem reports, please create a ticket into our BT system at
https://sourceforge.net/p/adacontrol/tickets/.
If you enjoy AdaControl, there are several things you can do to help us continue and improve this nice project.
And remember: developing AdaControl is an expensive effort (according to OpenHub’s COCOMO model, it is worth 22 man.year, 1.18M$ cost of development). We need support from our users to keep it running!
Next: References, Previous: Support, Up: Introduction
The development of AdaControl was initially funded by Eurocontrol (https://www.eurocontrol.int), which needed a tool to help in verifying the million+ lines of code that does Air Traffic Flow Management over Europe. Because it was felt that such a tool would benefit the community at-large, and that further improvements made by the community would benefit Eurocontrol, it was decided to release AdaControl as free software. Later, Eurocontrol, Belgocontrol, Alstom, Ansaldo (formerly CSEE-Transport), and SAGEM-DS sponsored the development of more rules.
The requirements for AdaControl were written by Philippe Waroquiers (Eurocontrol-Brussels), who also conducted extensive testing of AdaControl over the Eurocontrol software. The software was developped by Arnaud Lecanu and Jean-Pierre Rosen (Adalog). Rules, improvements, etc. were contributed by Pierre-Louis Escouflaire (Adalog), Alain Fontaine (ABF consulting), Richard Toy (Eurocontrol-Maastricht), Isidro Ilasa Veloso (GMV), and Quentin Dauprat (Adalog). AdaGide support and improvement of icons were contributed by Gautier de Montmollin. Emmanuel Masker (Alstom), Yannick Duchene and Pascal Pignard contributed to GPS integration.
See file HISTORY for a description of the various versions of
AdaControl, including enhancements of the current version over the
previous ones. Users of a previous version are warned that the rules
are not 100% upward-compatible: this is necessary to make the rules
more consistent and easier to use. However, the incompatibilities are
straightforward to fix and should affect only a very limited number of
files. See Non upward-compatible changes for details.
Previous: History, Up: Introduction
A number of papers have been published about AdaControl or its usage for various verification tasks:
Next: Program Usage, Previous: Introduction, Up: Top
Like any ASIS application, AdaControl uses an Ada compiler as its front-end analyzer (the so-called tree-generator). The tree-generator needs not be the same as the compiler you are using for your own compilations. Executable distributions of AdaControl are provided for the following combinations of operating systems and tree generators:
If you are using any other version, please use the source distribution of AdaControl and compile it as indicated below.
Another reason for using the source distribution of AdaControl is that the user may not be interested in all provided rules. It is very easy to remove some rules from AdaControl to increase its speed. See Customizing AdaControl.
| • Prerequisites | ||
| • Building and installing AdaControl from source | ||
| • Installing an executable distribution | ||
| • Installing support for AdaGide | ||
| • Installing support for GNATdashboard integration |
Next: Building and installing AdaControl from source, Previous: Installation, Up: Installation
AdaControl is supported only in conjunction with the Gnat compiler. For versions of Gnat up to GnatPro 20.2 and GnatCE 2019, the compiler can be used as the tree-generator, therefore you just need the compiler installed.
Starting from GnatPro 21.0, you’ll need to install AdaCore’s ASISTools package. It can be obtained from AdaCore’s “Download” page, click on the “Download archives (all versions)” link at the bottom of the page, then select the appropriate version of “ASIS tools”.
This package is installed by default in Gnat’s root directory. If you
choose to install it in a different location, you need to set the
environment variable ASISGCC to the path to the asis-gcc
executable which is part of the ASISTools installation. It is normally
of the form
<install-directory>/asis-gnsa/libexec/bin/asis-gcc. Alternatively,
you can pass the ASIS option --GCC= to AdaControl; See ASIS options.
Get in touch with Adalog at support@adalog.fr if you experience any difficulty.
Starting from GnatCE 2020, AdaCore has stopped distributing ASIS with Gnat CE (although it is still available to Pro users). Gnat CE users have several options to benefit from AdaControl:
ASISGCC as
<GnatCE2019-directory>/bin/gcc.
You can also write to AdaCore to express your dissatisfaction with a
commercial policy that deprives the community of a very useful
technology used by many tools. Follow us on Twitter as @AdaControl_prog.
Next: Installing an executable distribution, Previous: Prerequisites, Up: Installation
This section is only for the source distribution of AdaControl. If you downloaded an executable distribution, you may skip to the next section.
The following software must be installed in order to compile AdaControl from source:
As mentionned above, support of Gnat .gpr projects requires the
GNATColl component from AdaCore. If for some reason you don’t want to
include this component, it is possible to build AdaControl without
this support. To do so, go to the src directory and modify the
file implementation_options-project_file.ads as indicated. If
you don’t have GNATColl installed at all, you need also to remove the
line that says “with gnatcoll;” from the file
build.gpr.
Make sure that ASIS is installed for your generator. Run the installer
(adactl_src-setup.exe). This will automatically build and
install AdaControl, no other installation is necessary.
Simply go to the root directory of the distribution and type:
gprbuild build.gpr gprinstall -p build.gpr
You’re done!
NOTE: the “-p” option of gprinstall creates possibly missing directories. If you are installing over a previous version of AdaControl, you may want to add the “-f” option to allow the replacement of existing files.
If you want to uninstall AdaControl, just use:
gprinstall --uninstall adacontrol
It is also possible to build and install AdaControl with a regular Makefile, although it does little more than run the previous commands. This is mainly useful if you want to embed AdaControl into some distribution that uses Makefiles, or if you want to change the default compilation options (see comments in Makefile for details).
Go to the root directory of the distribution and type:
make build make install
It is also possible to delete object files and do other actions with this “Makefile”, run the following command to get more information:
make help
NOTE: Building AdaControl needs the “make” command provide with GNAT; it works both with WIN32 shell and UNIX shell.
Automatic install will place AdaControl’s files in standard locations, in your Gnat installation tree. You can skip this section unless you want different locations (for example, if GnatStudio is not installed in the Gnat tree).
All you need to run AdaControl is the executable named adactl
under Linux and MacOS or adactl.exe under Windows. In addition,
the adactl_fix (or adactl_fix.exe under Windows) utility
is necessary if you want to use the automatic fixing
capability. See Automatic fixing. Similarly, pfni (or pfni.exe
under Windows) is a convenient utility, required by the GPS
support. See pfni. Copy these executables (found in the root
directory of the distribution) to any convenient directory on your
path.
To also add AdaControl support to GnatStudio, copy the file
GPS/adacontrol.xml into the <GNAT_dir>/share/gprconfig
directory; copy all other files from the GPS directory into the
<GnatStudio_dir>/share/gnatstudio/plug-ins directory (if you
are using an old version from the time when GnatStudio was named GPS,
the directory is <GPS_dir>/share/gps/plug-ins). Copy also HTML
files from the doc directory into the
<GnatStudio_dir>/share/doc/gnatstudio/html directory (or
<GPS_dir>/share/doc/gps/html) to access AdaControl’s guides
from the "Help" menu of GPS.
Testing AdaControl needs a UNIX shell, so it works only with UNIX systems. However, it is possible to run the tests on a WIN32 system by using an UNIX-like shell for WIN32, such as those provided by CYGWIN or MSYS. To run the tests, enter the following commands:
cd test ./run.sh
All tests must report PASSED. If they don’t, it may be due to one of the following issues:
tfw_help reports “FAILED” because
it includes a check on the version of AdaControl, and the version
string refers to a different version of Gnat. The only difference (you
can see it by typing “d” when prompted for checking the differences)
should be the name of the compiler.
If there are some rules that you are not interested in, it is very easy to remove them from AdaControl:
src directory, edit the file
framework-plugs.adb. There is a with clause for each
rule (children of package Rules). Comment out the ones you
don’t want.
framework-plugs.adb. There will be error messages
about unknown procedure calls. Comment out the corresponding lines.
It is also possible to add new rules to AdaControl. If your favorite rules are not currently supported, you have several options:
Next: Installing support for AdaGide, Previous: Building and installing AdaControl from source, Up: Installation
If you downloaded the Windows installer executable version of
AdaControl, simply run adactl_exe-setup.exe. This will install
all the files in the recommended locations (as has been done with the
Windows installer source version), including GPS support if you have
GPS installed and/or AdaGide support if you have AdaGide installed.
Otherwise, go to the root directory of the installation and type:
gprinstall -p inst.gpr
This will install the executables and the GPS support in the standard locations (the Gnat directory). Add the “-f” option to gprinstall if you are installing over a previous installation of AdaControl. However, if you are using AdaGide, the support will have to be installed manually as explained below.
If you want to uninstall AdaControl, just use:
gprinstall --uninstall adacontrol
Next: Installing support for GNATdashboard integration, Previous: Installing an executable distribution, Up: Installation
To add AdaControl support to AdaGide, copy the file
AdaControl.tdf from the AdaGide directory of the
distribution into AdaGide’s root directory. Note that AdaControl
support requires AdaGide version 7.42 or above.
Previous: Installing support for AdaGide, Up: Installation
Integration into GNATdashboard is provided in a separate package that
you can download from the same source that you obtained AdaControl
from. It is provided as a .zip file that contains two files:
adacontrol-plugin-1.1r.jar and adacontrol.py.
Of course, the prerequisite is that you have a working installation of
GNATdashboard, including SonarQube and its sonnar-scanner
utility. Copy the first (.jar) file into the
<sonarqube-dir>/extensions/plugins/ directory. Copy the second
(.py) file into the <gnat-dir>/share/gnathub/extras/
directory.
Next: Command language reference, Previous: Installation, Up: Top
AdaControl is a command-line program, i.e. it is normally called directly from the system shell. Options are introduced by a “-” followed by a letter and can be grouped as usual. Some options take the following word on the command line as a value; such options must appear last in a group of options. Parameters are words on the command line that stand by themselves. Options and parameters can be given in any order.
The syntax for invoking AdaControl in regular mode is:
adactl [-deEirsTuvwx]
[-p <project file>] [-f [<command file>]] [-l <commands>]
[-F <format>] [-o [<output file>]] [-t <trace file>]
[-G [<fix level>]] [-S <statistics level>]
[-m <warning limit>] [-M <message limit>]
{<unit>[+|-<unit>]|[@]<file>} [-- <ASIS options>]
AdaControl can process all versions of Ada, up to Ada-2012. If you are using Ada-2005 (or Ada-2012) features, make sure that GNAT is set up for Ada-2005/2012 (this is the default for GNAT Community Edition). Due to technical reasons, the -gnat05 or -gnat12 option cannot be passed to the compiler in “compile on the fly” mode, but you can do any of the following:
pragma Ada_05; (or pragma Ada_12;)
pragma Ada_05 (or pragma Ada_12;) on top
of every compilation unit that uses Ada-2005/2012 features;
Note that if your program is pure Ada-95 and you are using a version
of GNAT where Ada-2005 or above is the default (especially GNAT
Community Edition), and in the rare cases where your program would not
compile in Ada-2005 mode (notably if you have a function that returns
a task type), you can force Ada-95 the same way by using
pragma Ada_95 instead.
Next: Return codes, Previous: Program Usage, Up: Program Usage
Next: Commands, Previous: Command line parameters and options, Up: Command line parameters and options
Units to be processed are given as parameters on the command
line. Note that they are Ada compilation unit names, not
file names: case is not significant, and there should be no
extension! Child units are allowed following normal Ada naming rules:
Parent.Child, but be aware that specifying a child unit will
automatically include its parent unit in the analysis. Subunits are
processed during the analysis of the including unit; there is
therefore no need to specify subunits explicitely. If you do specify a
subunit explicitly, it will result in the whole enclosing unit being
analyzed.
However, as a convenience to the user, units can be specified as file names, provided they follow the default GNAT naming convention. More precisely, if a parameter ends in “.ads” or “.adb”, the unit name is extracted from it (and all “-” in the name are substituted with “.”). File names can include a path; in this case, the path is automatically added to the list of directories searched (“-I” ASIS option). The file notation is convenient to process all units in a directory, as in the following example:
adactl -f my_rules.aru *.adb
In the unlikely case where you have a child unit called Ads or
Adb, use the “-u” option to force interpretation of all
parameters as unit names.
By default, both the specification and body of the unit are processed; however, it is possible to specify processing of the specification only by providing the “-s” option. If only file names are given, the “-s” option is assumed if all files are specifications (“.ads” files). It is not possible to specify processing of bodies only, since rules dealing with visibility would not work.
The “-r” option tells AdaControl to process (recursively) all user units that the specified units depend on (including parent units if the unit is a child unit or a subunit). Predefined Ada units and units belonging to the compiler’s run-time library are never processed.
Ex:
adactl -r -f my_rules.aru my_main
will process my_main and all units that my_main depends
on. If my_main is the main procedure, this means that the whole
program will be processed.
If both options “-r” and “-s” are given, then AdaControl will process all units given on the command line, plus (recursively) the specifications (but not the bodies) of all units that the given units depend on. In short, it will process the minimal transitive closure of all compilation units that are necessary to compile the units given on the command line.
It is possible to specify more than one unit (not file) to process in a parameter by separating the names with “+”. Conversely, it is possible to specify units that are not to be processed, separated by “-”. When a unit is subtracted from the unit list, it is never processed even if it is included via the recursive option, and all its child and separate units are also excluded. This is convenient to avoid processing reusable components, that are not part of a project. For example, if you want to run AdaControl on itself, you should use the following command:
adactl -f my_rules_file.aru -r adactl-asis-a4g-gnatcoll
This applies the rules from the file my_rules_files.aru to
AdaControl itself, but not to units that are part of ASIS (units
Asis, A4G, and their children) that would be found by
the “-r” (recursive) option otherwise.
Alternatively, it is possible to provide units indirectly with a parameter consisting of an “@” followed by the name of a file. This file must contain a list of unit names (not files), one on each line. Only the first “word” of the line is considered, i.e. everything after the first blank is ignored. This can be useful to annotate unit names. All units whose names are given in the file will be processed. In addition, some lines have a special meaning:
Ex:
adactl -f my_rules.aru @unit_file.txt
If no input units are specified on the command line, but a project file is given which specifies a units file, the units from the units file are processed. If the project file has no units file, but one or several main files are given, the main files are processed (in recursive mode if the recursive option is also given in the project file). See Project files.
Next: Output file, Previous: Input units, Up: Command line parameters and options
Commands specify which processing AdaControl should apply to units. See Command language reference for a detailed description of all commands.
Commands can be given directly on the command line with the “-l” option. A commands list must be quoted with “"”.
Ex:
adactl pack.ads proc.adb -l "check instantiations (My_Generic);"
It is possible to pass several commands separated by “;”, but as a convenience to the user, the last “;” may be omitted.
Commands can also be read from a file, whose name is given after the
“-f” option (the “.aru” extension is taken by default). As
a special case, if the file name is “-”, commands are read from the
standard input. This is intended to allow AdaControl to be pipelined
behind something that generates commands; if you want to type commands
directly to AdaControl, the interactive mode is more
appropriate. See Interactive mode.
Alternatively, AdaControl will consider a command file set as default in a .gpr project file, unless an explicit “-f” option is given.
Ex:
adactl -f my_rules.aru proc.adb
Note that the “-l” and “-f” options are not exclusive: if both are specified, the commands to be performed include those in the file (first) and then those given on the command line.
This applies also when there is no “-f” option, but a .gpr file is given which includes a default command file. If you need a project file, and don’t want its default command file to be considered, use “-f” without a <command file>.
Next: Output format, Previous: Commands, Up: Command line parameters and options
Messages produced by controls are output to the output file; by default, it is the standard output, but it can be changed by specifying the “-o” option. The output can be forced to the standard output by giving the “-o” option without a file name; this can be useful to override a “-o” option given in a project file. See Project files.
Ex:
adactl -f my_rules.aru -o my_output.txt proc.adb
If the output file exists, new messages are appended to it. This allows running AdaControl under several directories that make up the project, and gathering the results in a single file. However, if the “-w” option is given, AdaControl overwrites the output file if it exists.
All other messages, including syntax error messages, units processed (in verbose mode), and possible internal error mesages from AdaControl itself are output to the standard error file.
Next: Output limits, Previous: Output file, Up: Command line parameters and options
The “-F” option selects the output format. The option is followed by predefined identifiers that correspond to the most commonly used formats. It is also possible to define custom output formats with the “set format” command, see Set command.
The predefined identifiers are (case insensitive):
The format is the same as Gnat error messages. Especially useful when using an editor that recognizes Gnat messages.
CSV (Comma Separated Values) format, accepted by most spreadsheet programs. The CSVX variant uses a semi-colon instead of a comma to separate values (required by some locales -like French- that use the comma as a decimal separator).
Prints the whole source line of the control, followed by a mark pointing out the location of the error. This is the most useful format to read directly by humans.
No output at all. This is useful if you just want a count of errors or statistics, and may speed-up the analysis.
If an identifier ending in “_Long” or “_Short” is used, a “set Long_File_Name on” (respectively “set Long_File_Name off”) is performed in addition (i.e., the format of file names is set). For more details, see Set command.
By default, the output is in “Gnat” format, unless an output file is specified with a name whose extension is “.csv” (in any casing), in which case it defaults to “CSV”.
The “-F” option can also be followed by a character string that describes the output format. See Syntax of format strings. Since this string is passed on the command line, it must be quoted, and therefore it is recommended to use “~” as the string delimiter for AdaControl. See Parameters.
Ex:
-F "~%m (%f:%l:%c)~"
The “-G” option controls the generation, in the output file, of commands for fixing violations. It must be followed by “none” (the default), where no fixes information is generated, “check”, where fixes information is generated only for messages that use “check”, or “search” where fixes information is generated for all messages (i.e. “search” messages and above). Fixes information is never generated for “count”.
Next: Informational output, Previous: Output format, Up: Command line parameters and options
The “-m” and “-M” options are used to limit the output of AdaControl. These options are followed by an integer value that specifies the maximum number of error messages (“-m”) or warning and error messages (“-M”). If the value is omitted, a previous limitation (comming for example from a command file) is cancelled.
If the indicated number of messages is exceeded during a run, AdaControl stops immediately.
Next: Project files, Previous: Output limits, Up: Command line parameters and options
The “-S” option selects which statistics are output after each run. It must be followed by a value in the range 0..3. See Statistics for details on the various statistics levels.
The “-T” option prints a summary of timing at the end of each run. This indicates how long (in real-time seconds) was spent in processing each rule.
Next: Local disabling control, Previous: Informational output, Up: Command line parameters and options
Starting with version 1.18, AdaControl supports GNAT project files
(“.gpr”). The “-p” option is used to provide the name of a project
file. If this name is a relative name, it is searched for in the
current directory, then on the paths from the file whose name is given
by the environment variable GPR_PROJECT_PATH_FILE and then on
paths indicated by the environment variables GPR_PROJECT_PATH
and ADA_PROJECT_PATH. This is the same algorithm as used by the
various GNAT tools.
Ada units to analyze will be searched in all “source_dirs” specified in the project file or one of the projects it depends on (directly or indirectly). In addition, if the project file specifies a command file for AdaControl, this file will be considered, unless there is also an explicit “-f” option.
Similarly, if no units are given on the command line, AdaControl processes the units from the units file of the project file if any, or the main files from the project file.
More generally, any option not given on the command line is taken from the project file. Especially, units are processed recursively if the project file specifies the recursive option, the output is verbose if the project file specifies the verbose option, etc.
In short, if you specify AdaControl parameters in the project file, you only need to pass the “-p” option to it.
Ex:
adactl -f my_rules.aru -p proj.gpr proc.adb
Alternatively, an old emacs project file (the file with a “.adp” extension used by the Ada mode of Emacs and older versions of AdaControl) can also be specified with the “ -p” option. AdaControl will consider all the directories mentioned in “src_dir” lines from the project file.
If you have specified an output file in the project file, it will be used by default (like for any other option) if you run AdaControl from the command line; therefore, all messages will go to the output file. If you want to force output to the console, use the “-o” option without a file name.
Next: Verbose and debug mode, Previous: Project files, Up: Command line parameters and options
The “-i” option tells AdaControl to ignore disabling markers in Ada
source code (see Disabling controls); i.e. all controls will be
performed, regardless of the presence of disabling markers. This is
equivalent to the command “set ignore ON;”. Note that if you
have many messages, setting this option can speed-up AdaControl
considerably. It is therefore advisable to always set this option
when you know that there is no disabling marker in your source code.
The “-j” option tells AdaControl to invert the meaning of disabling
markers, i.e. only messages marked as disabled will be printed. This
is useful to check which messages have been disabled. This is
equivalent to the command “set ignore INVERTED;”.
Next: Treatment of warnings, Previous: Local disabling control, Up: Command line parameters and options
In the default mode, AdaControl displays only messages from triggered controls. It is possible to get more information with the verbose option (“-v”). In this mode, AdaControl displays a progress indicator and unit names as they are processed, and its global execution time when it finishes. Note that the progress indicator includes an indication of the run number if there are more than one “go” command.
The “-d” option enables debug mode. This mode provides more information in case of an internal program error, and is of little interest for the casual user, unless you want to report a problem. See In case of trouble.
In debug mode, AdaControl may also, in rare occasions (and only with some versions of GNAT), display ASIS “bug boxes”; this does not mean that something went wrong with the program, but simply that an ASIS failure was properly recovered by AdaControl.
Output of the messages printed by the “-d” option can be directed to a “trace” file (instead of being printed to the standard error file). This is done by the “-t” option, which must be followed by the file name. If the trace file exists, new messages are appended to it.
Next: Exit on error, Previous: Verbose and debug mode, Up: Command line parameters and options
The “-e” option tells AdaControl to treat warnings as errors, i.e. to report a return code of 1 even if only “search” controls were triggered. See Return codes. It does not change the messages however.
Conversely, the “-E” option tells AdaControl to not report warnings at all, i.e. only errors are reported. However, if you ask for statistics, the number of warning messages is still counted. See Report messages.
Next: ASIS options, Previous: Treatment of warnings, Up: Command line parameters and options
If an internal error is encountered during the processing of a unit, AdaControl will do its best effort to recover and to continue to process other units. However, if the “-x” option is given, AdaControl will stop on the first error encountered. This option is mainly useful if you want to debug AdaControl itself (or your own rules). See In case of trouble.
Ex:
adactl -x -f my_rules.aru proc.adb
Previous: Exit on error, Up: Command line parameters and options
Everything that appears on the command line after “--” will be treated as an ASIS “Associate” option, as described in the ASIS user manual.
Casual users don’t need to care about ASIS “Associate” options, except in two cases:
asis-gcc as
“--GCC=<path to asis-gcc>”.
It is possible to pass one or several “-I” options to ASIS, to provide other directories where sources can be found. The syntax is the same as the “-I” option for GNAT.
Other ASIS “Associate” options, like the “-Cx” and/or “-Fx” options, can be specified. Most users can ignore this feature; however, specifying these options can improve the processing time of big projects. See Optimizing Adacontrol.
In addition, every option after “-iargs” is passed as an ASIS “initialize” option. These options can be useful only if you are adding new rules to AdaControl. See the AdaControl Programmer’s Manual for details.
Next: Environment variable and default settings, Previous: Command line parameters and options, Up: Program Usage
In order to ease the automation of controlling programs with shell scripts, AdaControl returns various error codes depending on how successful it was. Values returned are:
Next: Fixing violations, Previous: Return codes, Up: Program Usage
If the environment variable “ADACTLINI” is set, its content is taken as a set of commands (separated by semi-colons) that are executed before any other command. Although any command can be specified, this is intended to allow changing default settings with “set” commands. See Set command.
For example, you can set ADACTLINI to “set long_file_name on” if you prefer having your messages with long file names rather than the (default) short format.
Next: Interactive mode, Previous: Environment variable and default settings, Up: Program Usage
If the “-G” option is given with “check” or “search”, AdaControl generates in the output file (in addition to the regular messages) special directives to fix the source that violated some rule. See Output format.
Not all rule provide automatic fixing, either because the rule is just intended to report on the presence of some construct, or because the fix needs manual inspection. When a rule does provide for automatic fixing, there is a “Fixes” section in its description that explains what can (or cannot) be fixed by the rule.
If the output file is loaded into GPS (automatically, or as a result file), messages for which there is a known fix will appear as usual, but with the “Fix” symbol (the little wrench icon) in the left margin. Clicking on the icon will perform the fix and remove the corresponding icon (just like fixable compilation errors).
Alternatively, there is an “Apply all fixes” entry in the AdaControl menu. This will apply all fixes, just as if you clicked on every “Fix” symbol. Note that the “Undo” command can be used to revert the effect of this command!
Note that by default, the generation of fixes is enabled under GPS.
An output file containing the directives can be processed by the
adactl_fix utility. The syntax is:
adactl_fix [-v] [-o <output-prefix>] <file>... adactl_fix -h
With the “-h” option, adactl_fix prints a brief help message
and exits, ignoring all other options and parameters.
Otherwise, adactl_fix reads the indicated <file>s (more than
one can be provided) and performs the corresponding fixes. The
modified files are printed on the standard output, which can be
redirected to a file for later splitting at an appropriate place with
gnatchop. Alternatively, if the “-o” option is given, each
modified file is output to a file whose name is obtained by prefixing
the <output-prefix> of the "-o" option to the original name of the
corresponding source file. The <output-prefix> can be any string, and
is not analyzed by Adactl_Fix. A prefix like "result/" will result in
all the output going to the directory "result", with the same name as
the original. Alternatively, a prefix like "new-" will result in all
output files being in the same directory, with a "new-" prepended to
the name. Adactl_Fix will overwrite any existing file with the same
name.
The “-v” (verbose) option prints the names of the fix files being processed and of the source files being fixed to the standard error file. In case of conflicts, it provides some more information about the origin of the conflict.
It is possible that several fixes modify the same place, or overlapping places. When using automatic fixing, if one of the fixes is the deletion of a zone of text that fully covers the other one, then the deletion is kept and the other one discarded. Otherwise, the first fix is kept and the other one is ignored; a message at the end of the run tells the user that some fixes were not performed, and that AdaControl should be run again.
When this happens, it is possible (although we expect it to be infrequent) that the modified code does not compile anymore and that some easy manual adjustments be necessary.
It is expected that this algorithm for resolving conflicts be improved in the future. Suggestions and examples welcome!
When using interactive fixing, all fixes are kept; just click on the various “fix” icons, and check that the code is transformed appropriately.
Automatic fixing is a powerful feature of AdaControl, but like any tool that transforms the source it requires some care. Automatic fixing makes sense when there are many violations, and these violations would be easy but tedious to fix by hand. A typical use case is when you apply new rules to an existing software, and discover that the casing rules have not been obeyed: fixing the casing of thousands of identifiers is a long and uninteresting job... Therefore, the automatic fixing tool has been designed under the assumption that it will be used “one-shot”, not as day-to-day use.
The automatic fixing should therefore be used as follows:
On the other hand, interactive fixing is fully under user control. It is possible to check (and possibly undo) any modification. But of course, since it is a manual operation, it becomes tedious when there are many changes to perform.
As a rule of thumb, perform automatic fixing, one rule at a time, for the controls that often result in a big number of violations, and where the fix is both obvious and riskless (typically: incorrect casing of identifiers or keywords). Use interactive fixing for more subtile controls where it is more appropriate to check the result of the substitution.
Caveat: fixing a violation can create another violation! Typically, if the fix adds some text (like changing a positional association to a named one), it can then exceed the maximum allowed line length. Hence fixing violations is necessarily an iterative process.
And of course, the best advice is: fix violations as early as possible. Run AdaControl each time you modify a module. This is the best way to save the effort!
If you have specified a fix level in the project file, it will be used by default (like for any other option) if you run AdaControl from the command line; therefore, fixes will be generated, which might be undesirable for console output. To disable the generation of fixes, use the “-G” option without value (same as “-G none”).
Attention of users designing safety critical applications (DOD-178B/C level A, EN-50128 SIL4) is drawn to the fact that the automatic fixing is relevant to TQL1-4, instead of TQL5 as AdaControl normally is.
AdaControl has not been subject to the formal verifications required by TQL1-4 tools; therefore it is up to the user to check that the applied fixes maintain the integrity of the software.
Next: Other execution modes, Previous: Fixing violations, Up: Program Usage
The “-I” option tells AdaControl to operate interactively. In this mode, commands specified with “-l” or “-f” options are first processed, then AdaControl prompts for commands on the terminal. Note that the “quit” command (see Quit command) is used to terminate AdaControl.
The syntax of commands run interactively is exactly the same as the one used for files; especially, each command must be terminated with a “;”. Note that the prompt (“Command:”) becomes “.......:” when AdaControl requires more input because a command is not completely given, and especially if you forget the final “;”.
As with files, it is possible to give several commands on a single line in interactive mode. If a command contains syntax errors, all “go” commands (see Go command) on the same line are temporarily disabled. Other commands that do not have errors are normally processed however.
The interactive mode is useful when you want to do some analysis of your code, but don’t know beforehand what you want to control. Since the ASIS context is open only once when the program is loaded, queries will be much faster than running AdaControl entirely with a new query given in a “-l” option each time. It is also useful to experiment with AdaControl, and to check interactively commands before putting them into a file.
Next: Running AdaControl from GPS, Previous: Interactive mode, Up: Program Usage
In addition to normal usage, AdaControl features special options to ease its use; no Ada unit is analyzed when using these options.
| • Getting help | ||
| • Checking commands syntax | ||
| • Generating a units list |
Next: Checking commands syntax, Previous: Other execution modes, Up: Other execution modes
The “-h” option provides help about Adacontrol usage. If the “-h” option is given, no other option is analyzed and no further processing happens.
Syntax:
adactl -h [<keyword> | <rule name> | variables ["<pattern>"] ...]
<keyword> ::= all | commands | license | list |
options | rules | version
The “-h” option without parameter displays a help message about usage of the AdaControl program, the various options, and the rule names.
Otherwise, the “-h” must be followed by one or several keywords or rule names (case irrelevant); its effect is:
Ex:
adactl -h pragmas Unnecessary_Use_Clause adactl -h all adactl -h version license adactl -h stat
Note in the last example that “stat” is not the name of a rule; it is therefore interpreted as a pattern, and help will be displayed for all rules that include the string “stat” in their name. This can be very convenient to retrieve the name of a rule if you don’t remember exactly how it is spelled.
Next: Generating a units list, Previous: Getting help, Up: Other execution modes
The “-C” option is used to check syntax of commands without executing any control.
Syntax:
adactl -C [-dv] [-f <command file>] [-l <rules list>]
In this mode, AdaControl simply checks the syntax of the commands provided with the “-l” option, or of the commands provided in the file named by the “-f” option (at least one of these options must be provided). No other processing will happen.
AdaControl will exit with a return code of 0 if the syntax is correct, and 2 if any errors are found. A confirming message that no errors were found is output if the “-v” option is given.
This option is especially useful when you have modified a command file, before trying it on many units. The way AdaControl works, it must open the ASIS context (a lengthy operation) before analyzing the rules. This option can therefore save a lot of time if the command file contains errors.
Previous: Checking commands syntax, Up: Other execution modes
The “-D” options produces a list of units that can be reused as an indirect file in later runs.
Syntax:
adactl -D [-rsvw] [-o <output file>] [-p <project file>]
{<unit>[+|-<unit>]|[@]<file>} [-- <ASIS options>]
In this mode, AdaControl outputs the list of units that would be processed. It is especially useful when used with the “-r” option and given the main unit name, since it will then generate the whole dependencies list (hence the name “D”), i.e. the list of units that are part of the program. However, if -D is used with -s, the list includes only transitive dependencies from the specifications of required units (but not from their bodies). This is the list of all units required to compile the given units.
The list can be directed to a file with the “-o” option (if the file exists, it won’t be overwritten unless the “-w” option is specified). This file can then be used in an indirect list of units. See Input units. Note that it is more efficient to create the list of units once and then use the indirect file than to specify all applicable units or use the “-r” option each time AdaControl is run.
If you use the “-Drs” option to generate the minimum set of required units to compile the given unit, note that some units may still be missing when the compiler requires the presence of a body due to inlining of subprograms or generic instantiations. These units depend on the compiler and cannot be computed from the text of the program alone.
Next: Running AdaControl from AdaGide, Previous: Other execution modes, Up: Program Usage
AdaControl integrates nicely into GPS, making it even easier to use. It can be launched from menu commands, and parameters can be set like any other GPS project parameters. When run from within GPS, AdaControl will automatically retrieve all needed directories from the current GPS project.
After running AdaControl, the “locations” panel will open, and you can retrieve the locations of errors from there, just like with a regular compilation. Errors will be marked in red in the source, warning will be marked orange, and you will have corresponding marks showing the places of errors and warnings in the speedbar. Note that AdaControl errors appear under the “AdaControl” category, but if there were compilation errors, they will appear under the “Compilation” category. Final counts from “count” control kinds will appear under the “Counts summary” category, and statistics under the “Statistics” category.
| • The AdaControl menu and buttons | ||
| • Contextual menu | ||
| • AdaControl switches | ||
| • AdaControl preferences | ||
| • AdaControl language | ||
| • AdaControl help | ||
| • Caveat |
Next: Contextual menu, Previous: Running AdaControl from GPS, Up: Running AdaControl from GPS
AdaControl adds an “AdaControl” menu to GPS, with several submenus:
There are also two buttons representing Lady Ada in a magnifier glass in the toolbar, one with a red question mark in the background. These buttons launch AdaControl, by default on the file currently being edited; however, you can change this behaviour from the preferences to control either files from a list, or all files from the project. The button without the question mark uses rules from the current rules file, while the one with the question mark asks for the control to apply interactively.
Here are some tips about using the “interactive” menus (or the button with the question mark):
Next: AdaControl switches, Previous: The AdaControl menu and buttons, Up: Running AdaControl from GPS
AdaControl adds two entries to the contextual menus (right click) of
Ada files. They call the pfni utility on the current
entity. See pfni. The entry “Print full name” displays the full
name of the entity in simple form, while the entry “Print full name
(with overloading)” ) prints it with overloading information. If the
name refers to an entity which is initialized (or to a parameter with
a default value), the initial value is printed. If the entity is a
discrete type, its range is printed. If the entity is an array type,
the ranges of its indices are printed.
This is convenient to find how to name entities in rule files. See Specifying an Ada entity name. It is also convenient to find where an entity is declared, and which of several overloaded entities is being referred to.
This is also convenient to find the actual value of a constant from anywhere in the program text, since the printed value is completely evaluated if it is a (static) expression.
Next: AdaControl preferences, Previous: Contextual menu, Up: Running AdaControl from GPS
The tab “switches” from the “Project/Edit Project Properties” menu includes a page for AdaControl, which allows you to set various parameters. Since the GPS interface analyzes the output of AdaControl, you should not set options directly in the bottom window of this page (the one that displays the actual options passed to AdaControl).
This section controls the definition of various files used by AdaControl.
This section offers options that control how units are processed.
This section controls the debugging options of AdaControl.
This section offers options that control where and how the output of AdaControl is displayed.
This section controls the ASIS parameters passed to AdaControl. The content of the input field “ASIS options” is used in place of the standard (“-CA -FM”) one.
Casual users don’t need to change the default ASIS options. For more details, see ASIS options.
Next: AdaControl language, Previous: AdaControl switches, Up: Running AdaControl from GPS
There is an entry for AdaControl in the “edit/preferences” menu:
Next: AdaControl help, Previous: AdaControl preferences, Up: Running AdaControl from GPS
If you check “AdaControl” in the “Languages” tab of the project
properties, GPS will recognize files with extension .aru as
AdaControl command files, and provide appropriate colorization. Remember
to check also the corresponding “no compiler” checkbox to avoid
spurious messages from GPS.
Next: Caveat, Previous: AdaControl language, Up: Running AdaControl from GPS
The AdaControl User Manual (this manual) and the AdaControl Programmer Manual are available from the "Help/AdaControl" menu of GPS.
The "Help on rule" entry displays the list of all rules; if you click on one of them, you get help for the particular rule. Depending on the setting of the “Help on rule” preference (see above), it opens a pop-up that displays the rule(s) purpose and the syntax of its parameters, or opens the user guide at the appropriate location.
The “About” entry displays a popup with AdaControl’s version number and license condition.
Previous: AdaControl help, Up: Running AdaControl from GPS
GPS may crash when the output of a command is too big (i.e. hundreds of messages with AdaControl). If this happens, use the “preferences” menu to limit the number of messages.
Next: Integrating AdaControl into GNATdashboard, Previous: Running AdaControl from GPS, Up: Program Usage
If you want to use AdaControl from AdaGide, make sure you have copied
the necessary file into the required place. See Installing support for AdaGide. Note that AdaGide does not have all the parameterization
facilities of sophisticated environments like GPS, but all AdaControl
options, like the name of the command file or the output format, can
easily be changed by editing the tool description file
AdaControl.tdf.
AdaGide now features several AdaControl commands from the “tool” menu:
verif.aru.
Next: Helpful utilities, Previous: Running AdaControl from AdaGide, Up: Program Usage
Once GNATdashboard support is installed (see Installing support for GNATdashboard integration), AdaControl is usable like any other
tool that comes with GNATdashboard. The name of the plug-in is
“adacontrol”. It can be given either on the command line of
gnathub or in the “Plugins” attribute of the “Dashboard”
package of a project file.
Extra options for AdaControl can be given using the
--targs:adacontrol option of GNAThub. However, the simplest way
to give fundamental options is to give a units file and the command
file in the project file: in the absence of explicit parameters on the
command line, these will be taken by default.
AdaControl installs a non-default profile called “AdaControl way” that contains all AdaControl rules. Use it to activate the rules you need. You can also make it inherit from “GNATdashboard way” if you want to use AdaControl with other GNAT tools.
Ex:
Assuming all necessary AdaControl options are set in the project file, you can run AdaControl as:
gnathub -P <project-file>
If there are other tools defined in the project file and you just want to run AdaControl:
gnathub -P <project-file> --plugins=adacontrol
To provide options to AdaControl (here: run AdaControl with a given rules file):
gnathub -P <project-file> --plugins=adacontrol --targs:adacontrol
-f special.aru
Next: Optimizing Adacontrol, Previous: Integrating AdaControl into GNATdashboard, Up: Program Usage
This section describe utilities that are handy to use in conjunction with AdaControl.
| • pfni | ||
| • adactl_fix | ||
| • makepat.sed | ||
| • unrepr.sed |
Next: adactl_fix, Previous: Helpful utilities, Up: Helpful utilities
The convention used to refer to entities (as described in Specifying an Ada entity name) is very powerful, but it may be difficult to spell out correctly the name of some entities, especially when using the overloaded syntax.
pfni (which stands for Print Full Name Image) can be used
to get the correct spelling for any Ada entity. The syntax of
pfni is:
pfni [-sofdq] [-p <project-file>] <unit>[:<span>]
[-- <ASIS options>]
<span> ::= <line_number>
| [<first_line>]-[<last_line>]
| <line_number>:<column_number>
or
pfni -h
If called with the “-h” option, pfni prints a help message
and exits.
Otherwise, pfni prints the full name image of all identifiers
declared in the indicated unit, unless there is a “-f” (full)
option, in which case it prints the full name image of all identifiers
(i.e. including those that are used, but not declared, in the
unit). The image is printed without overloading information, unless
the “-o” option is given.
In addition, pfni prints the initial value of variables if
there is one, the range of discrete types, and the range of the
indices of array types.
The <unit> is given either as an Ada unit, or as a file name, provided the extension is “.ads” or “.adb” (as in AdaControl). If a span is given, only identifiers within the span are printed. In the first form, the span includes only the indicated line; in the second form, the span includes all lines from <first_line> to <last_line> (if omitted, they are taken as the first and last line of the file, respectively). In the third form, the span includes only the place at the specified <line_number> and <column_number>.
Normally, the source line corresponding to the names is printed above the names. The “-q” (quiet) option suppresses this.
If the “-s” option is given (or the unit is a file name with a “.ads” extension), the specification of the unit is processed, otherwise the body is processed. The “-p” option specifies the name of a project file (“.gpr” or “.adp”), and the “-d” option is the debug mode, as for AdaControl itself. ASIS options can be passed, like for AdaControl, after a “--” (but -FS is the default). See ASIS options.
As a side usage of pfni, if you are calling a subprogram that
has several overloadings and you are not sure which one is called, use
pfni with the “-o” option on that line: the program will tell
you the full name and profile of the called subprogram.
Next: makepat.sed, Previous: pfni, Up: Helpful utilities
adactl_fix is a utility that applies automatically the fixes
generated by AdaControl. See Fixing violations for details.
Next: unrepr.sed, Previous: adactl_fix, Up: Helpful utilities
This file (provided in the “src” directory) is a sed script that transforms a text file into a set of correponding regular expressions. It is useful to generate model header files. See Header_Comments.
Previous: makepat.sed, Up: Helpful utilities
This file (provided in the “src” directory) is a sed script that comments out all representation clauses. It is typically useful if you use a different compiler that accepts representation clauses not supported by GNAT.
Typically, you would copy all your sources in a different directory, copy “unrepr.sed” in that directory, then run:
sed -i -f unrepr.sed *.ads *.adb
You can now run AdaControl on the patched files. Of course, you won’t be able to check rules related to representation clauses any more...
Note that the script adds “--UNREPR ” to all representation clauses. Its effect can thus easily be undone with the following commad:
sed -i -e "s/--UNREPR //" *.ads *.adb
Next: In case of trouble, Previous: Helpful utilities, Up: Program Usage
There are many factors that may influence dramatically the speed of AdaControl when processing many units. For example, on our canonical test (same controls, same units), the extreme points for execution time were 111s. vs 13s.! Unfortunately, this seems to depend on a number of parameters that are beyond AdaControl’s control, like the relative speed of the CPU to the speed of the hard-disk, or the caching strategy of the file system.
This section will give some hints that may help you increase the speed of AdaControl, but it will not change the output of the program; you don’t really need to read it if you just use AdaControl occasionnally. This section is concerned only with the GNAT implementation of ASIS; other implementations work differently.
Bear in mind that the best strategy depends heavily on how your program is organized, and on the particular OS and hardware you are using. Therefore, no general rule can be given, you’ll have to experiment yourself. Hint: if you specify the “-v” option to AdaControl, it will print in the end the elapsed time for running the tests; this is very helpful to make timing comparisons.
Note: all options described in this section are ASIS options, i.e. they must appear last on the command line, after a “--”.
| • Tree files and the ASIS context | ||
| • Generating tree files manually | ||
| • Choosing an appropriate combination of options |
Next: Generating tree files manually, Previous: Optimizing Adacontrol, Up: Optimizing Adacontrol
Since AdaControl is an ASIS application, it is useful to explain here how ASIS works. ASIS (and therefore AdaControl) works on a set of units constituting a “context”. Any reference to an Ada entity which is not in the context (nor automatically added, see below) will be ignored; especially, if you specify to AdaControl the name of a unit which is not included in the current context, the unit will simply not be processed.
ASIS works by exploring tree files (same name as the corresponding Ada unit, with a “.adt” extension), which are “predigested” views of the corresponding Ada units. By default, the tree files are generated automatically when needed, and kept after each run, so that subsequent runs do not have to recreate them.
A context in ASIS-for-Gnat is a set of tree files. Which trees are part of the context is defined by the “-C” option:
The “-F” option specifies what to do if the program tries to access an Ada unit which is not part of the context:
Note that “-FT” is the only allowed mode, and must be specified, with the “-C1” and “-CN” options.
The default combination used by AdaControl is “-CA -FM”. A consequence of this is that the context is established by first loading all available tree files before starting the analysis, even those that are not necessary. Since tree files are often big and long to load, if you want to check a single unit and have remaining trees from a previous run, it is often more efficient to delete all “.adt” files first.
More generally, given the current speed of CPUs and the not-so-fast access time of disks, it may happen that recomputing the trees instead of loading them from disk might be faster. Only experiencing will tell you the best procedure to follow.
Next: Choosing an appropriate combination of options, Previous: Tree files and the ASIS context, Up: Optimizing Adacontrol
It is also possible to generate the tree files manually before running AdaControl. Although this mode of operation is less practical, it is recommended by AdaCore for any ASIS tool that deals with many compilation units. Some reasons why you might want to generate the tree files manually are:
Trees are generated by a tree generator program. Up to GnatPro 20.1 and GnatCE 2019, the tree generator was part of the regular compiler; more recent versions provide it as a separate program (which is actually a restricted version of the compiler, with the same options). To make it easier, running AdaControl with the “-h generator” option will print the complete path to the generator to be used.
To generate tree files manually, simply recompile your project with the tree generator program, adding the “-gnatct” option. Of course, you will need all other options needed by your project (like the “-P” option if you are using GNAT project files).
Tree files may be copied into a different directory if you don’t want your current directory to be cluttered by them. In this case, use the “-T” ASIS option to indicate the directory where the tree files are located.
If you chose to generate the tree files manually, you may want to specify the “-FT” ASIS option (see above) to prevent from accidental automatic recompilation.
Previous: Generating tree files manually, Up: Optimizing Adacontrol
In order to optimize the use of AdaControl, it is important to remember that reading tree files is a time-consuming operation. On the other hand, a single tree file contains not only information for the corresponding unit, but also for the specifications of all units that the given unit depends on. Moreover, our measures showed that reading an existing tree file may be slower than compiling the corresponding unit on-the-fly (but once again, YMMV).
Here are some hints to help you find the most efficient combination of options.
adactl -f rules_file.aru example -- -FT -C1 example.adt
provided the tree file already exists.
Previous: Optimizing Adacontrol, Up: Program Usage
If you encounter a problem while using AdaControl, you are very welcome to report it through our bug tracking system (under Windows, you can click on “Report problem” in the AdaControl Start menu). Please include the exact control and the unit that caused the problem, as well as the captured output of the program (with “-dx” option).
This happens if you are running GnatPro 21.0 and above, and either you have not installed the ASISTools package, or have it installed in a non-standard location. See Prerequisites.
If AdaControl seems to be frozen, first make sure that it is not
simply slow (some rules may require quite a lot of time on big
units). Check for example if the size of the result file is
growing. If it appears that AdaControl is really stuck, you can
recompile it in interruptible mode (see the comments in file
framework-interrupt.adb for details). Then, if you hit Ctrl-C
in debug mode (“-d” option), AdaControl aborts with a message
telling the currently active rule and module.
Note that this interruptible mode may imply a penalty in execution time, that’s why it is not enabled by default.
Like any sophisticated piece of software, AdaControl may fail when encountering some special case of construct. ASIS may also fail occasionnally; actually, we discovered several ASIS bugs during the development of AdaControl. These were reported to ACT, and have been corrected in the wavefront version of GNAT - but you may be using an earlier version. In this case, try to upgrade to a newer version of ASIS. If an AdaControl or ASIS problem is not yet solved, AdaControl is designed in such a way that an occasionnal bug won’t prevent you from using it.
If AdaControl detects an unexpected exception during the processing of a unit (an ASIS error or an internal error), it will abandon the unit, clean up everything, and go on processing the remaining units. This way, an error due to a special case in a unit will not affect the processing of other units. AdaControl will return a Status of 10 in this case.
However, if it is run with the “-x” option (eXit on error), it will stop immediately, and no further processing will happen.
If you don’t want the garbage from a failing rule to pollute your report, you may chose to disable the rule for the unit that has a problem. See Inhibit command.
Next: Rules reference, Previous: Program Usage, Up: Top
AdaControl is about controlling rules. Rules are built in AdaControl; each rule has a name, and may require parameters. For the complete description of each rule, see Rules reference.
To run AdaControl, you need to define which rules you want to apply to your Ada units, what are the parameters, etc. In addition, you may want to define various things, like the file where the results should go, the output format, etc.
AdaControl defines a small command language which is used to describe how you want to process your units. Commands can be specified either on the command line or in a file, that we call here a rules file. Commands can also be given interactively; See Interactive mode.
| • General | ||
| • Controls | ||
| • Other commands | ||
| • Example of commands |
Next: Controls, Previous: Command language reference, Up: Command language reference
The command language is not case-sensitive, i.e. the case of the keywords, rule names, and parameters is not significant. The layout of commands is free (i.e. a command can extend over several lines, and spaces are freely allowed between syntactic elements).
Comments are allowed in and between commands. Comments begin with a “#” or a “--”, and extend to the end of the line.
Since wide characters are allowed in Ada programs, AdaControl accepts wide characters in commands as well. With GNAT, the encoding scheme is Hex ESC encoding (see the GNAT User-Guide/Reference-Manual). This is the prefered method, since few people require wide characters in programs anyway, and that keeping the default bracket encoding would not conveniently allow brackets for regular expressions, like those used by some rules. See Syntax of regular expressions.
If a syntax error is encountered in a command, an appropriate error message is output, and analysis of the command file continues in order to output all errors, but no analysis of user code will be performed.
Next: Other commands, Previous: General, Up: Command language reference
A control command is a command that declares one (or several) controls. A control defines how a rule is applied to Ada units. The syntax of a control command is as follows:
<control_command> ::= [<label> ":"] <control> {"," <control>} ";"
<control> ::= <ctrl_kind> <Rule_Name> [<parameters>]
<parameters> ::= "(" [<modifiers>] <value>
{"," [<modifiers>] <value>} ")"
<ctrl_kind> ::= "check"|"search"|"count"
Each control consists of a <ctrl_kind> followed by a rule name, and (optionally) parameters. Some parameters may be preceded by modifiers (such as “not” or “case_sensitive”). The meaning of the rule parameters and modifiers depends on the rule.
There are three control kinds: “check”, “search”, and “count”.
“Check” is intended to search for rules that must be obeyed in your programs. Normally, if a “Check” control fails, you should fix the program. “Search” is intended to report some situations, but you should consider what to do on a case-by-case basis. Roughly, use “check” when you consider that the failure of the control is an error, and “search” when you consider it as a warning. AdaControl will exit with a status of 1 if any “Check” control is triggered, and a status of 0 if only “Search” controls were triggered (or no control was triggered at all). Each time a “Check” or “Search” control is triggered, a message is issued to the standard output (unless redirected). The format of the message can be selected by means of the “-F” command line option, or the “set format” command. See Report messages.
“Count” works like “Search”, but instead of printing a message for each control which is triggered, it simply counts occurrences and prints a summary at the end of the run. There is a separate count for each control label (or if no label is given, the rule name is taken instead); if you give the same label to different controls, this allows you to accumulate the counts.
If present, the label gives a name to the control(s); it will be
printed whenever each control is activated, and can be used to disable
the control(s). See Disabling controls. If no label is present,
the rule name is printed instead. The label must have the syntax of an
Ada identifier, or else the label must be included within double
quotes ("), in which case it can contain any character.
Here are some examples of commands:
check unnecessary_use_clause;
All_Imports: search pragmas (Import);
"Why do you need that?": check entities (Unchecked_Conversion,
all 'Address);
Specifying several controls with the same label is a shorthand which is equivalent to specifying the same label for several controls. It is handy when the label is long, and/or to stress that several controls are part of the same programming rule. For example:
"Check why this obsolete stuff is still used": check entities (obsolete_unit_1), -- Note comma here! check instantiations (some_obsolete_generic);
| • Parameters | ||
| • Report messages | ||
| • Statistics | ||
| • Disabling controls | ||
| • Multiple controls |
Next: Report messages, Previous: Controls, Up: Controls
Most rules accept parameters. Parameters can be:
A numerical value is given with the syntax of an Ada integer or real literal (underscores and exponents are allowed as in Ada). Based literals are supported for integer values; if somebody can justify a need for supporting them for reals, we’ll be happy to add this feature later...
A character string is given within double quotes “"”. As usual, quotes appearing within the string are doubled. The tilde character (“~”) can be used as a replacement delimiter, but the same character must be used at both ends of the string. The latter has been chosen as a character not used by the various shells, and can be useful to pass quoted strings from parameters on the command line (unfortunately, we could not use the percent (“%”) sign, because it plays a special role in DOS/Windows).
An Ada entity name is the full name (prefixed with the names of all units that include it) of something declared in a program. It can be followed by overloading information, in order to uniquely identify the Ada entity. If an Ada entity is overloaded and no overloading information is provided, the rule is applied to all (overloaded) Ada entities that match the name. Alternatively, it can be “all” followed by a simple name, in wich case it applies to all entities with that name. See Specifying an Ada entity name for the full description of the syntax. Here are some examples of entity names:
Ada.Text_IO.Put -- All Put defined in Ada.Text_IO
Ada.Text_IO.Put{Standard.Character} -- The Put on Character
all Put -- All Put
Standard.Integer'Image -- The 'Image function on Integer
all 'Image -- All 'Image functions
Next: Statistics, Previous: Parameters, Up: Controls
A report message (except for the final report of “count”) comprises the following elements:
The formatting of the report message depends on the format option, which can be selected with the “-F” command-line option or the “set format” command.
If the format is “Gnat” (the default), “Gnat_Short”, or “Gnat_Long”, items are separated by ’:’; this is the same format as the one used by GNAT error messages. Editors (like Emacs or GPS) that recognize this format allow you to go directly to the place of the message by clicking on it. In order to avoid too long messages, only the label appears, unless there is none, in which case it is replaced with the rule name.
If the format is “CSV”, “CSV_Short”, or “CSV_Long”, items are separated by ’,’ and surrounded by double quotes. This is the “Comma Separated Values” format, which can be read by any known spreadsheet program. However, some locales (that use the coma as a decimal separator) require a semi-colon (’;’) instead of a coma to separate values; therefore, the formats “CSVX”, “CSVX_Short”, and CSVX_Long do the same thing, but with semi-colons as separators. Both the label (replaced by an empty column if there is none) and the rule name appear. Note that when an output file is created in one of the “CSV” formats, a title line is issued as the first line, following normal CSV convention.
If the format is “Source”, “Source_Short” or “Source_Long”, the offending source line is output, and the message is output behind it, with a “!” pointing to the exact location of the problem.
If the format is “None”, no error message is output at all. This is useful when only the return code of running AdaControl is desired (just to check if a program is OK or not). Note that this does not prevent the output of statistics, since these are under control of the “-S” option or the “set statistics” command. In this case, statistics are output in CSVX format, since asking for statistics with a “none” format is mainly useful for analysing the statistics with a spreadsheet program.
It is also possible to get the messages in any custom defined format by setting appropriate variables. See Syntax of format strings
By default, the file name in the message is just the simple name of the file. The “_Long” form of the format forces the file name to include the full path of the source file. This can make it easier to compare the results of controlling units from various directories. Conversely, if the “_Short” form of the format option is used, the file name is forced to the simple name (in case it was set to the long form before).
Next: Disabling controls, Previous: Report messages, Up: Controls
After each run (see Go command), statistics may be output, depending on the statistics level which is set with the “-S” option or the “set statistics” command. The meaning of the various levels is as follows:
Next: Multiple controls, Previous: Statistics, Up: Controls
It is possible to disable controls on parts of the source code by
placing markers in the source code. A marker is an Ada comment, where
the comment mark (--) is immediately followed by the special
tag “##” (by default).
There are two kinds of markers: block markers and line markers. Both kinds specify a list of controls to disable/re-enable. A list of controls is a list of rule names (to disable/re-enable all controls on the indicated rule(s)) or control labels (to disable/re-enable all controls with that label), separated by spaces. Alternatively, the list of controls can be the word “all” to disable/re-enable all controls.
In a “--##” line, everything appearing after another
“##” tag (by default) is ignored. This allows the insertion
of a comment explaining why the control is disabled at that point.
Both tags can be changed with the “set” command. See Set command.
A control is disabled from a “rule off” marker that applies to it until a “rule on” marker that applies to it. If there is no appropriate “rule on” marker, the control is disabled up to the end of file.
Syntax:
--## rule off <control_list> Ada code block --## rule on <control_list>
Ex:
--## rule off rule1 rule2 ## Authorized by QA ref 1234 I := I + 1; Proc (I); --## rule on rule2
The “Rule_File_Off” command can be used to start units whose file name matches a given pattern in the “disabled” state for some or all rules. See Rule_File_Off command.
A control is disabled only for the line where a marker that applies to it appears.
Syntax:
Ada code line --## rule line off <rule_list>
Ex:
I := I + 1; --## rule line off rule3 rule_label_1
Conversely, it is possible to re-enable a control for just the current line in a block where it is disabled:
Syntax:
Ada code line --## rule line on <rule_list>
Ex:
--## rule off rule1 rule2 ... I := I + 1; --## rule line on rule2
Since the disabling is based on special comments, there is a conflict with the rule “header_comments” which is based on the content of comments. Line disabling is not possible with this rule, and block disabling needs special care. See Header_Comments.
Previous: Disabling controls, Up: Controls
Most rules can be used in more than one control (with different parameters). There is no difference between a single or a multiple configuration rule use: outputs, efficiency, etc. are the same.
The following command files produce an identical configuration:
Search Pragmas (Pure, Elaborate_All);
and
Search Pragmas (Pure); Search Pragmas (Elaborate_All);
However, the second form can be used to give different labels. Consider:
Search Pragmas (Pure); No_Elaborate: Search Pragmas (Elaborate_All);
The messages for pragma Pure will contain “PRAGMAS”, while
those for Elaborate_All will contain “No_Elaborate”. If a
disabling comment mentions pragmas, it will disable both controls,
but a disabling comment that mentions No_Elaborate will disable
only the second one.
Next: Example of commands, Previous: Controls, Up: Command language reference
In addition to controls, AdaControl recognizes a number of commands. Although these commands are especially useful when using the interactive mode (see Interactive mode), they can be used in command files as well.
| • Go command | ||
| • Quit command | ||
| • Message command | ||
| • Help command | ||
| • Clear command | ||
| • Set command | ||
| • Source command | ||
| • Rule_File_Off command | ||
| • Inhibit command |
Next: Quit command, Previous: Other commands, Up: Other commands
This command starts processing of the controls that have been specified.
Syntax:
go;
Controls are not reset after a “go” command; for example, the following program:
search entities (pack1); go; search entities (pack2); go;
will first output all usages of Pack1, then all usages of both
Pack1 and Pack2. See Clear command to reset
controls.
If not in interactive mode, a “go” command is automatically added at the end, therefore it is not required in command files.
Next: Message command, Previous: Go command, Up: Other commands
This command terminates AdaControl.
Syntax:
quit;
If given in a file, all subsequent commands will be ignored. This command is really useful only in interactive mode. See Interactive mode.
Next: Help command, Previous: Quit command, Up: Other commands
This command prints a message on the output file.
Syntax:
message ["<any string>"] [pause];
The length of the message is limited to 250 characters; if no message is given, it defaults to the empty string. If the word “pause” (case irrelevant) is specified after the message (if any), AdaControl will wait for the user to press the Return key before proceeding.
Note that the message is syntactically a string, and must therefore be quoted (double quotes).
Next: Clear command, Previous: Message command, Up: Other commands
This command prints various informations about the rules and AdaControl itself.
Syntax:
Help [<help_item> {,<help_item>}]
<Help_Item> ::=<keyword> | <rule name> | variables ["<pattern>"]
<keyword> ::= all | commands | license | list | options |
rules | version
Without any argument, this command prints a summary of all commands and rule names. If given one or more keywords or rule names, it prints the corresponding help message. See Getting help for the details.
Next: Set command, Previous: Help command, Up: Other commands
This command command clears (i.e. removes) controls that have been previously given.
Syntax:
Clear all | <rule name>{,<rule name>} ;
The command clears all controls given for the indicated rules, or for
all rules if the all keyword is given. Rule variables
(see Set command) associated to cleared rules are returned to
their default values. For example, the following program:
search entities (pack1); go; clear all; search entities (pack2); go;
will first output all usages of Pack1, then all usages of
Pack2. Without the “clear all” command, the second “go”
would output all usages of Pack1 together with all usages of
Pack2.
Next: Source command, Previous: Clear command, Up: Other commands
This command sets various parameters of AdaControl.
Syntax:
set <switch> On|Off;
<switch> ::= Debug | Exit_On_Error | Long_File_Name |
Verbose | Warning | Warning_As_Error
set Check_Key|Search_Key "<value>";
set Count_Format "<format_string>";
set Count_Format_Header "<format_string>";
set Fixes_Gen Check | Search | None;
set Format <format_name> | "<format_string>";
<format_name> ::= Gnat | Gnat_Short | Gnat_Long |
CSV | CSV_Short | CSV_Long |
CSVX | CSVX_Short | CSVX_Long |
Source | Source_short | Source_Long |
None
set Format_Header "<format string>";
set Ignore On | Off | Inverted;
set Max_Errors [min|max] [<value>];
set Max_Messages [min|max] [<value>];
set Output|New_Output <output file>;
set Statistics [min|max] <level>;
set Tag1|Tag2 "<value>";
set Timing On | Off | Global
set Trace <trace file>;
set <Rule_Name>.<Variable> [min|max] <Value>
When a parameter has an integer value, it can be preceded by the keywords “min” or “max”. If present, it indicates that the parameter should be set to at least (respectively at most) the indicated value, i.e. if the current value of the parameter is greater (respectively smaller) than the given value, it is not changed. This can be especially useful in rule files that are sourced from other rules files, where a value for the parameter has been previously set.
-- Set statistics to level 2, unless a higher level is already set set statistics min 2;
The “set <switch>” command activates (“on”) or deactivates (“off”) options. “Debug” corresponds to the “-d” option, “Exit_On_Error” to the “-x” option, “Ignore” to the “-i” option, “Verbose” to the “-v” option, “Warning” to the “-E” option, “Warning_As_Error” to the “-e” option, and “Long_File_Name” to a predefined format that ends in “_Long”. See Verbose and debug mode, Exit on error, Treatment of warnings, Output format, and Local disabling control for details.
The “set check_key” command defines a string which is used in place of “Error” in messages issued by a “check” control. Similarly, the “set search_key” command defines a string which is used in place of “Found” in messages issued by a “search” control. This can be useful when AdaControl is used, for example, to detect places where manual inspection is required; having the word “Error” in the message could be misleading to the persons in charge of the review. Note however that if you set these keys, the GPS interface will not be able to recognize properly the messages.
The “set fixes_gen” command controls the generation of fixes indications, like the “-G” option; see Output format for details.
The “set format” command selects the output format for the messages. The value is either one of the possible identifiers for the “-F” option, or a string value for a custom format; see Report messages for details, or Syntax of format strings for the specification of a custom format.
The “set format_header” defines the format of the header of the report, which is output only once on top of the messages. It is also set automatically when using one of the identifiers with “set format”.
The “set count_format” and “set count_format_header” do the same things, but for the count reports which is issued at the end of the run.
The “set ignore” command governs handling of disabled messages (see Disabling controls). In default mode (“Off”), disabled messages are not printed. When set to “on”, all messages are printed, including those that are disabled. Setting this option can result in considerable speed-up of the printing of messages. When set to “Inverted”, only disabled messages are printed. This is useful to check which messages have been disabled.
The “set max_errors” and “set max_messages” limit the output of AdaControl, like the “-m” and “-M” options; see Output limits for details. If no <value> is given after the command name, the corresponding limitation is removed.
The “set output” and “set new_output” commands redirect the output
of subsequent controls to the indicated file. If the string
console (case irrelevant) is given as the <output file>, output
is redirected to the console.
The “set statistics” command sets the statistics level, like the “-S” option; see Report messages for details.
The “set tag1|tag2” command changes the tags used to disable (or
enable) rules. “Tag1” is the string that appears immediately after
the comment indicator (--), and “tag2” is the tag that
terminates the special comment. Note that these tags must be given as
strings (in quotes) and that case is relevant. See Disabling controls for details.
The “set trace” command redirects the trace messages of the
“-d” option to the indicated file. If the string console
(case irrelevant) is given as the <trace file>, trace messages are
redirected to the console. As with the “-t” option, if the file
exists, output is appended to it.
The “set timing” command activates (“on”) or deactivates (“off”) the printing of the time spent in each rule after each “go” command. If set to “global” instead of “on”, the timings are accumulated over all “go” commands, and output when the program terminates.
Some rules may also have user-settable global variables that affect their behaviour; the last form of the “set” command allows changing their value. The variable name is of the form of a qualified name (i.e. “rule.var”), and the value depends on the variable. The description of the variables (if any) and appropriate values is given for each rule.
Next: Rule_File_Off command, Previous: Set command, Up: Other commands
This command inputs commands from another file.
Syntax:
Source <input file>;
Commands are read and executed from the indicated file, then control is returned to the place after the “source” command. There is no restriction on the content of the sourced file; especially, it may itself include other “source” commands.
If <input file> is a relative file path, it is taken relatively to the
file where the “source” command is given. Especially, if no path is
specified, the sourced file will be taken from the same directory as
the sourcing file (irrespectively of where the command is being run
from). If the file is not found there, it is searched on the path given
by the environment variable ADACTL_PATH.
The default extension is .aru, i.e. if <input file> is not
found as given, AdaControl will retry the same name with .aru
appended. It is a syntax error if the file is not found either.
If the string console (case irrelevant) is given as the <input
file>, commands are read from the console until a “quit” command is
given. This command is of course useful only from files, and allows to
pass temporarily control to the user in interactive mode.
Next: Inhibit command, Previous: Source command, Up: Other commands
This command changes the initial disabled state to “off” for files that match a given pattern. See Disabling controls.
Syntax:
Rule_file_off "<pattern>" all | <rule name> {, <rule name>}
Messages from files whose (full path) name matches the given <pattern>
are initially disabled, like if a “--##rule off” comment had been
given before the first line of the file. The pattern is given using
the full Regexp syntax, not the file pattern matching of the
system. see Syntax of regular expressions for details.
If “all” is given, messages for all rules are disabled, otherwise messages are disabled only for the given rule(s).
Example:
-- Disable all messages from units located in the -- "external_components" directory: rule_file_off "/external_components/" all -- Disable rules expressions and statements for bodies of unit -- Compo and children (in Gnat file notation): rule_file_off "compo(-.*)*\.adb$" expressions, statements
Unlike the regular “--##rule off” comment, it is not possible to
disable a control according to its label, only rule names can be
given.
This command works on file names, not on logical Ada units.
Rules can be re-enabled if the file contains a matching “--##rule on”
comment.
Previous: Rule_File_Off command, Up: Other commands
This command prevents execution of certain controls on particular units.
Syntax:
Inhibit <rule name>|all ([all] <unit> {,[all] <unit>});
Controls refering to the given rule (or all rules if “all” is specified in place of a rule name) for the indicated unit(s) are not performed. In addition, if “all” is specified in front of the unit name, the unit will not be accessed at all, even from rules that follow call graphs, and could thus access this unit while analyzing other units.
There are several reasons why you might want to inhibit a control of a rule for certain units:
The “all” option for a unit is intended for the last case, to prevent ASIS bugs from spoiling any unit that calls something from an offending unit.
This command prevents the unit from being analyzed, and it is not possible to “uninhibit” it, unlike the “Rule_File_Off” command (see Rule_File_Off command) that simply turns off messages. Note also that the “Rule_File_Off” command works on file name patterns while the “inhibit” command works on Ada units.
Previous: Other commands, Up: Command language reference
Below is an example of a file with multiple commands:
message "Searching Unchecked_Conversion"; search entitities (ada.unchecked_conversion); set output uc_usage.txt; go; clear all; message "Searching 'Address"; search entities (all 'Address); set output address_usage.txt; go;
This file will output all usages of Ada.Unchecked_Conversion
into the file uc_usage.txt, then output all usages of the
'Address attribute into the file
address_usage.txt. Messages are output to tell the user about
what’s happenning.
Next: Examples of using AdaControl for common programming rules, Previous: Command language reference, Up: Top
This chapter describes each rule currently provided by
AdaControl. Note that the rules directory of the distribution
contains a file named verif.aru that contains an example of a
set of rules appropriate to check on almost any software.
A general limitation applies to all rules. AdaControl is a static checking tool, and therefore cannot check usages that depend on run-time values. For example, it is not possible to check rules applying to an entity when this entity is aliased and accessed through an access value, or rules applying to subprogram calls when the call is a dispatching call.
Starting with version 1.22, AdaControl performs some data flow tracing that allows it to check conditions that are provably always True/False although not static as defined in the reference manual. When the description of a rule talks about something being static, it really means statically provable. If a condition needs to be legalistically static, we use the term RM_Static.
Next: Actual_Parameters, Previous: Rules reference, Up: Rules reference
This rule controls functions that may not terminate normally, i.e. where
Program_Error could be raised due to reaching the end of the
function without encountering a return statement.
<control_kind> abnormal_function_return;
The rule controls that the sequence of statements of each function body, as well as each of its exception handlers, ends with:
return statement (including extended return statements)
raise statement (or equivalently, a call to
Ada.Exceptions.Raise_Exception or
Ada.Exceptions.Reraise_Occurrence);
pragma No_Return or
has a No_Return aspect;
if statement that includes an else path, and
where the last statement of every path is one of these;
case statement where the last statement of every path is
one of these.
loop statement (not for or
while) without any exit or goto
statement transfering control outside of the loop.
This is a sufficient (but of course not necessary) condition to ensure
that no function raises Program_Error due to reaching the end
of its statements without encountering a return.
This rule can be specified only once.
Ex:
check abnormal_function_return;
This rule checks that a function always returns correctly, but does not
prevent multiple return statements in functions. If you want
to ensure that there is exactly one return statement in functions,
and that this statement is always the last one, use this rule together with
the rule statements(function_return).
See Statements.
It is possible to exit from an extended return statement with an
exit or goto statement. If this happens, the
return statement is not considered a proper return statement, and an
appropriate message is issued.
Next: Allocators, Previous: Abnormal_Function_Return, Up: Rules reference
This rule checks properties of actuals provided to calls or instantiations.
<control_kind> actual_parameters (<subrule>, <place>, <formal>
{, <actual>});
<subrule>::= default_used | default_not_used | default_positional |
entity
<place> ::= <entity> | calls | instantiations
<formal> ::= <formal name> | all
<actual> ::= [all] <entity>
The first parameter is a subrule keyword. All subrules check properties of an actual value of a call or instantiation. The called (or instantiated) entity is given by <place>, which is either an explicit entity specification, “calls” if all calls are controlled, or “instantiations” if all instantiations are controlled. The check applies to parameters whose name is <formal>, or to all parameters if <formal> is “all”.
As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name. On the other hand, <formal> is the simple name of the formal parameter.
Other parameters (<actual>...) are only for the subrule “entity”.
What is being checked depends on the subrule:
This rule can be specified only once for each combination of the parameters.
Ex:
-- Check calls to P where the default is used for parameter X: check actual_parameters (default_used, P, X); -- Check calls to P where the default is not used for parameter Y: check actual_parameters (default_not_used, P, Y); -- Check all calls where positional notation is used -- for any defaulted parameter: search actual_parameters (default_positional, calls, all); -- Check that variable V in package Pack is not used -- as a parameter Item to some Put: check actual_parameters (entity, all Put, Item, Pack.V); -- Check that no instance of Unchecked_Conversion is used directly as -- a parameter to a call (trying to get around strong typing?) check actual_parameters (entity, calls, all, Ada.Unchecked_Conversion);
If the <place> is a generic subprogram, it is also possible to give a formal parameter (a parameter of the subprogram, not a generic parameter) as the <formal name>; in this case, all instantiations of the indicated generic subprogram will be controlled for the use of the indicated parameter.
Next: Array_Declarations, Previous: Actual_Parameters, Up: Rules reference
This rule controls the use of allocators (i.e. dynamic memory allocation).
<control_kind> allocators [(<target> {, <target>})];
<target> ::= [anonymous | inconsistent | not] [<category>|<entity>]
If one or several <entity> or <category> are given, only allocators whose allocated type matches the <entity>, or whose type belongs to the indicated <category>, are controlled; otherwise all allocators are controlled. As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name.
This rule traverses derivations and privacy (i.e. it will control allocators whose ultimate type belongs to the indicated category). See Definition of type categories.
This rule is especially useful for finding memory leaks, since it tells all the places where dynamic allocation occurs.
If a parameter is preceded by the word “not”, allocators for the corresponding type or category are not controlled (i.e. they are always allowed). If a control includes only “not” parameters, an implicit check for all allocators is assumed.
If a parameter is preceded by the word “anonymous”, only allocators whose expected type is an anonymous access type are controlled.
If a parameter is preceded by the word “inconsistent”, only
allocators whose allocator subtype (the name after “new”)
is not the same as the designated subtype (from the access type
declaration) are controlled. However an allocator is not considered
inconsistent when the designated subtype imposes no special
constraint:
T'Base).
Note that if the access type includes a constraint like in the following example:
type Acc is access integer range 1..10;
all allocators will necessarilly be inconsistent, since there is no way to repeat the constraint at the place of the allocator.
“Inconsistent” can be given alone, in which case all inconsistent allocators are controlled.
Ex:
search allocators (standard.string); check allocators (T'Class); check allocators (array); check allocators (Inconsistent standard.Integer); check allocators (Inconsistent); -- all task allocators, except when the type is called "special": check allocators (task, not all Special);
The type given as an <entity> in the rule must be a first named subtype, and the rule will also find allocators that use a subtype of this type. If the type is declared within a generic package, the rule will control all corresponding types from instantiations.
The type mentionned in the rule is the one following the
new keyword, which is not necessarily the same as the
expected type in presence of implicit conversions like this:
type T is tagged ...; type Class_Access is access T'Class; X : Class_Access; begin X := new T;
This allocator will be found for type T, not for type T'Class.
The reason for the “inconsistent” modifier is that inconsistent allocators may cost a double check. Given:
type Acc is access Positive; V : Acc; begin V := new Natural'(...);
The compiler will first check the constraint for Natural, then the constraint for Positive. To avoid confusion, it is better to always use the same subtype for the allocator as used in the access type declaration.
The reason for the “anonymous” modifier is that allocators of an anonymous type (especially access parameters) create a terrible mess in accessibility rules, and are better avoided.
In some (rare) cases involving anonymous access types as array or record components, ASIS provides no way to determine the target type of the (anonymous) acccess type. Inconsistent allocators will thus not be controlled. Such cases are detected by the rule “uncheckable”. See Uncheckable.
Next: Aspects, Previous: Allocators, Up: Rules reference
This rule controls properties of arrays, by enforcing a consistent value or range of values for the lower or upper bound, or by limiting the possible size. It can also control various aspects of the component type of the array.
<control_kind> array_declarations (first, <value> | <bounds>);
<control_kind> array_declarations (last, <value> | <bounds>);
<control_kind> array_declarations (dimensions, <value> | <bounds>);
<control_kind> array_declarations ([all] length, <bounds>);
<control_kind> array_declarations (component, <type> {,<repr_cond>});
<control_kind> array_declarations (index, <type> | <>
{,<type> | <>});
<bounds> ::= min|max <value> [, min|max <value> ]
<type> ::= <entity>|<category>
<repr_cond> ::= [not] pack | size | component_size
This rule controls properties of the index or component of an array type. The checks are therefore performed on array definitions, i.e. on array (sub)type declarations and single array declarations. However, the “length” subrule can be checked on any array variable, see below.
The first parameter is a subrule keyword:
search array_declarations (first, 1); check array_declarations (first, min -1, max 1);
will be silent if the lower bound of an array is 1, it will issue a warning if it is in the range -1 .. 1, and an error otherwise.
search array_declarations (Dimensions, 1); check array_declarations (Dimensions, min 2, max 3);
will be silent for one-dimensional arrays, it will issue a warning for 2- and 3-dimensional arrays, and an error otherwise.
If the “all” modifier is specified, all object declarations of an array type are controlled, even if the declaration does not include an explicit range constraint. This is useful if you want to assess all variables that contain more than a certain number of elements. For example:
type Tab is array (Min..Max) of Compo; -- Always checked subtype Str is String (Min..Max); -- Always checked V1 : String (Min..Max); -- Always checked V2 : Str; -- Checked only with "all"
This subrule traverses derivations, but not privacy (the category “private” can be given, to check arrays whose components are of a private type). See Definition of type categories.
If one or several <repr_cond> are specified, the rule controls only arrays to which all the corresponding representation items apply:
This subrule traverses derivations, but obviously, only “()”, “range”, and “mod” categories can be given since other categories (including “private”) cannot be used as indexes. See Definition of type categories.
The number of <entity> given determines the dimensionality of the controlled arrays. If a “<>” is given in place of an entity, it means that any type matches at that position.
This rule can be specified several times for the “component” and “index” subrules. For other subrules, it can be specified at most once for each subrule and for each of “check”, “search” and “count”. It is thus possible for each subrule to have a value considered a warning, and a value considered an error.
Ex:
-- All arrays should start at 1: check array_declarations (first, 1); -- No arrray of more than 100 elements: check array_declarations (length, max 100); -- No empty array: check array_declarations (length, min 1); -- Arrays whose component type is private: check array_declarations (component, private); -- Packed arrays of Character check array_declarations (component, Standard.Character, pack); -- Packed arrays of record without size clause check array_declarations (component, record, packed, not size); -- One-dimensional arrays indexed by Integer check array_declarations (index, standard.integer); -- Three dimensional arrays whose second index is an enumeration check array_declarations (index, <>, (), <>);
The subrule Max_Length ignores index constraints that are not
static. Non static index constraints can be controlled with the rule
Non_Static (Index_Constraint). See Non_Static.
Requiring the same upper bound for all arrays is not very useful, but:
check array_declarations (last, min 1);
can be used to check that no array has a negative or zero upper bound.
The subrule “index” controls a precise pattern of types used as indices. To control the use of a type as an index at any position and irrespectively of the number of indices of the array, use the rule “type_usage”. See Type_Usage.
Next: Assignments, Previous: Array_Declarations, Up: Rules reference
This rule controls aspect specifications (new feature in Ada 2012), either
all of them, specific ones, or those whose value is implicitely True.
<control_kind> aspects [(<aspect key> {, <aspect key>})];
<aspect_key> ::= all | implicit_true | <aspect mark>
Without parameters, controls all aspect specifications. Otherwise, controls only the aspect specifications corresponding to the given aspect marks. If “all” is given together with explicit aspect marks, it controls aspects not given explicitely.
If “implicit_true” is given, it controls aspect specifications
without an association (i.e. boolean aspects given without an explicit
association that take implicitely the value True).
Ex:
search aspects; DBC: check aspects (Pre, Post, Pre'Class, Post'Class); Explicit_Required: check aspects (implicit_true);
Next: Barrier_Expressions, Previous: Aspects, Up: Rules reference
This rule controls various issues related to the assignment statement: assignments to an object of a given type, assignments that involve array sliding, assignments that cause duplication of access values, redundant assignments to the same variable, or groups of assignments that are replaceable by aggregate assignment.
<control_kind> assignments (type, [component] [ancestor] <entity>);
<control_kind> assignments (sliding);
<control_kind> assignments ([[not] controlled] access_duplication
{, [not] <target>});
<control_kind> assignments (repeated);
<control_kind> assignments (groupable, <filter> {,<filter>});
<control_kind> assignments ([[not] trivial] possible_target_name
[, <max length>]);
<target> ::= <entity> | <category> | function | procedure
<filter> ::= given <min_val> | missing <max_val> | ratio <min_val> |
total <max_val>
The first parameter is a subrule keyword:
This form can be given only once without “component” and once with “component” for each type.
null value and allocators
(new) are not controlled. In other words, this rule
spots places where you start having more than one way to access a
variable.
If the modifier “controlled” is given, only access types that are subcomponents (directly or indirectly) of a controlled type are controlled, while if “not controlled” is given, only those that are not subcomponents of a controlled type are controlled. No modifier is equivalent to giving both “controlled” and “not controlled”.
If one or several <target> without not are given, the control
applies only to access types whose target type matches the given
<entity>, or belongs to the given <category>. Conversely, if the
<target> is preceded by not, it means that the corresponding
<entity> or <category> is not controlled. As usual, the whole syntax
for entities is allowed for <entity>. See Specifying an Ada entity name.
This subrule traverses derivations, but not privacy (the category “private” can be given, to check access types whose target is of a private type). See Definition of type categories. In addition, “function” and “procedure” can be given to specify access types that designate functions or procedures.
This subrule can be given at most twice for each <target>, once for “controlled” and once for “not controlled”.
Note that the two subrules above are checked for initialization of variables and constants, as well as for regular assignments.
Other subrules control properties of groups of assignment statements. A group is made of consecutive assignments, without any other intervening kind of statements (except null statements).
If several filters are given, the rule is triggered if all conditions are met (“and” logic). Note however that this rule can be given several times, thus achieving “or” logic.
The rule is not triggered on an object if a subcomponent of that object is of a limited or class-wide type, since global assignment would not be allowed in that case.
For other structured objects, a subcomponent is counted as assigned if it has been assigned in full, or if it should have been assigned in full (in other words: if the rule is triggered on those subcomponents as well) - recursively, of course.
If <max length> is specified with “trivial”, only identifiers whose length is greater are controlled; if it is specified with “not trivial”, only names with more components (i.e qualifications and indexings) are controlled. <max length> is not allowed with no modifiers.
This subrule can be given only once for each of “trivial” and “not trivial”.
Ex:
-- Check assignments to objects of type Address:
check Assignments (type, System.Address);
-- Check assignments to components of an object of a type derived from
-- Stream_Element_Array
check Assignments (type,
component ancestor Ada.Streams.Stream_Element_Array);
-- Warn for assignments involving array sliding:
search Assignments (sliding);
-- Check multiple assignments to the same variable
check Assignments (repeated);
-- Warn if a at least 3 fields are given and at most
-- two fields are missing, or if 80% of the fields are given:
search assignments (groupable, given 3, missing 2);
search assignments (groupable, ratio 80);
-- Find all non trivial possible uses of "@"
search assignments (not trivial possible_target_name);
-- Find all trivial possible uses of "@" where the identifier
-- has more than 3 characters
search assignments (trivial possible_target_name, 3);
The following subrule generates fixes:
The “sliding” subrule is not intended to prevent all cases of slidings (the dynamic ones are uncheckable), it is rather an indication of “obvious” cases that could be avoided.
The “access_duplication” subrule is especially handy to track remaining duplication of access values after they have been Unchecked_Deallocated through one of the variables. The “not controlled” modifier is intended to avoid too many false positives when you use controlled types to manage pointers. It may also be useful to check all access duplications, but consider that those that are part of a controlled type deserve only a warning:
check assignments (not controlled access_duplication); search assignments ( controlled access_duplication);
Note that for the “groupable” subrule, it is possible to give 1 for the “given” criterion; in this case, any assignment to parts of a structured variable will be reported, only global assignment is allowed.
“possible_target_name” generates fixes, thus allowing easy use of “@” when moving to Ada 202X.
As usual, AdaControl can control only static aspects of assignments. Therefore, it cannot control assignments whose target is not statically known (like dynamic indexing of arrays). Slices are always considered dynamic (the cases where it would be useful did not seem worth the additional complexity).
For the “sliding” subrule, if the assigned expression is a multidimensional aggregate, only the first dimension is checked for sliding, other dimensions are ignored. This is not considered an important issue, since in any case the rule can detect only static cases, and the handling of sliding in multi-dimensional array aggregates is extremely touchy (see RM 4.3.3 for details).
For the “groupable” subrule, if the number of subcomponents is not statically determinable (dynamic arrays, discriminated records), only the “given” criterion can be met.
Next: Case_Statement, Previous: Assignments, Up: Rules reference
Although the language allows any expression as the barrier of a protected entry, it is generally better to use only “simple” expressions. This rule controls the kind of constructs allowed in barrier expressions.
<control_kind> Barrier_Expressions ([<allowable> {, <allowable>}]);
<allowable> ::= <entity> | <keyword>
<keyword> ::=
allocation | any_component | any_variable |
arithmetic_operator | array_aggregate | comparison_operator |
conversion | dereference | indexing |
function_attribute | local_function | logical_operator |
record_aggregate | value_attribute
Without parameters, the only elements allowed in barriers are references to boolean components of the protected element and litterals (this corresponds to what is allowed for the Ravenscar profile). Parameters specify other constructs that are allowed:
Standard.Boolean.
"+", "**", etc.).
"=", ">", in, etc.).
'Pred, 'Image, etc.).
and, or else, etc.).
'First, 'Terminated, etc.).
This rule can be given only once for each of “check”, “search” and “count”.
Ex:
search barrier_expressions;
check barrier_expressions (logical_operator, comparison_operator,
any_component,
Pack.Global_State);
The goal of the “Simple_Barrier” restriction from the Ravenscar profile is to ensure that evaluation of barriers never raise exceptions. Even simple things like a qualified expression can raise exceptions, but in practice more than the restriction of the Ravenscar profile can be “reasonably” allowed.
Note that the various “operator” keywords allow only the use of predefined operators. If a user defined operator should be allowed, provide it explicitely as an <entity>. There is no way to allow any function call, since this would boil down to allowing pretty much anything, but you can of course specify explicitely functions that can be called.
You can provide this rule both for “check” and “search”, but of course it makes sense only if the set of allowed features for “search” is a superset of those allowed for “check”. This way, the use of certain features can be interpreted only as a warning.
Next: Characters, Previous: Barrier_Expressions, Up: Rules reference
This rule controls various metrics related to the case
statement. It is intended for cases where it is desired to limit the
complexity of case statements.
<control_kind> Case_Statement ([<category>] <subrule>, <bound>
[, <bound>]);
<subrule> ::= others_span | paths | range_span | values |
values_if_others
<bound> ::= min | max <value>
The first parameter is a subrule keyword:
when others case alternatives.
when branches).
case selector.
case statements with a when others
alternative.
If the <subrule> is preceded by a <category>, it applies only to
case statements whose selecting expression belongs to the
indicated category, otherwise the subrule applies to all
categories. Obviously, only categories “()”, “range” and “mod”
can be given.
This rule traverses derivations; privacy is irrelevant, since the
selecting expression of a case statement has to be visibly
discrete. See Definition of type categories.
The second (and optionnally third) parameter give the minimum and/or maximum allowed values (i.e. the rule will control values outside the indicated interval). If not specified, the minimum value is defaulted to 0 and the maximum value to infinity.
This rule can be specified at most once for each subrule/category combination and for each of “check”, “search” and “count”. It is thus possible for each subrule/category to have a value considered a warning, and a value considered an error.
Ex:
check Case_Statement (others_span, min 1); search Case_Statement (others_span, min 5); check Case_Statement (values, max 10); check Case_Statement (() paths, min 3, max 30); check Case_Statement (range paths, min 3, max 100); check Case_Statement (mod paths, min 3, max 100);
To control that no range is used as a choice in a case
statement:
check case_statement (range_span, max 0);
To control “when others” that
cover no value at all:
check case_statement (others_span, min 1);
If some characteristic of the case statement depend on a
generic formal type, it is not possible to control some of the
features statically. Such cases are detected by the rule
“uncheckable”. See Uncheckable.
If the subtype of the selecting expression of the case
statement, or a subtype in one of its a choice lists, has applicable
static predicates, AdaControl is not able to control the features that
depend on the number of values of the subtype. Such cases are detected
by the rule “uncheckable”. See Uncheckable. We hope to be able to
remove this limitation in the future, but the problem is quite
difficult...
Next: Comments, Previous: Case_Statement, Up: Rules reference
This rule makes sure that the program text does not use “undesirable” characters.
<control_kind> characters [(<subrule> {, <subrule>})];
<subrule> ::= control | not_iso_646 | trailing_space | wide
The rule controls the occurrence in the source file of characters belonging to the classe(s) defined by the subrules. Without parameters, all classes are controlled. The classes are defined as follows:
Standard.Character.
This rule can be given only once for each class of characters.
Ex:
check characters (control, trailing_space); search characters (not_iso_646);
The following subrules generate fixes:
With the “wide” subrule, the error message may seem to not always appear at the right place; this depends on the encoding scheme used. For example, if your source contains (using bracket encoding):
S : Wide_String := "["1041"]["1042"]";
it will appear to AdaControl as a string containing two characters, and therefore the error message for the second wide character will point at two characters after the opening quote of the string.
This rule controls only the characters in the source file; other means
of having characters in the corresponding classes (like using the
'Val attribute) are not controlled.
Next: Declarations, Previous: Characters, Up: Rules reference
This rule controls comments that must, or must not, appear in certain cases.
<control_kind> comments (pattern, "<pattern>" {, "<pattern>"});
<control_kind> comments (position, <value> | <bounds>);
<control_kind> comments (terminating {, "<pattern>" | begin | end});
<control_kind> comments (unnamed_begin, <kind> {, <kind>});
<control_kind> comments (unnamed_end_record {, <value>});
<bounds> ::= min|max <value> [, min|max <value> ]
<kind> ::= [<condition>] [min <value>] <unit_kind>
<condition> ::= always | declaration | program_unit
<unit_kind> ::= all | procedure | function | entry | package | task
The first parameter is a subrule keyword:
--”
and spaces following it. Patterns are given using the full Regexp
syntax. see Syntax of regular expressions for details. Pattern
matching is always case insensitive.
This subrule is especially useful to find lines with comments like “TBSL” (To Be Supplied Later) or “fixme”, which are often used to mark places where something should be done before releasing the program.
search comments (position, 1); check comments (position, min 1, max 6);
will be silent for comments that start in column 1, it will issue a warning for comments that start at columns 2 to 6, and an error otherwise.
begin are allowed (not reported);
similarly, if “end” is specified, comments appearing on a line that
contains only an end are allowed. Otherwise, the other
parameters are patterns that specify forms of comments that are
allowed. Patterns are given using the full Regexp syntax.
see Syntax of regular expressions for details. Pattern matching is
always case insensitive.
begin of various constructs that
do not have a comment that repeats the name of the program unit
associated to the begin. The unit name must be the first word
of the comment (after any number of spaces). Some extra information can
be provided after the name, provided it is separated from the name by
a space or a comma.
The <condition> keyword determines circumstances where the comment is required:
If “min <value>” is specified, it tells the minimum number of lines
in the statement part that follows begin for the control
to apply, i.e. the comment is not required if the statement part has
less lines than the indicated value.
The <unit_kind> keyword detemines the kind of program unit to which the rule applies (“all” stands for all kinds). This subrule can be given only once of each kind of program unit.
end record of a record
type declaration (including tagged types and type extensions) that
does not have a comment that repeats the name of the record type. The
type name must be the first word of the comment (after any number of
spaces). Some extra information can be provided after the name,
provided it is separated from the name by a space or a comma.
If a <value> is given as the second parameter, it indicates the maximum size in lines of record type declarations where the comment may be omitted. If <value> is omitted or is 0, all record type declarations are controlled.
This subrule can be given only once for each of check, search, and count. This way, it is possible to have a number of lines where the omission of the comment is considered a warning (search), and one considered an error (check). Of course, this makes sense only if the number of lines for search is less than the one for check.
Ex:
check comments (pattern, "TBSL"); -- Report places where rules are disabled: search comments (pattern, "##.* off"); -- End of line comments are not allowed, except for the -- comment that repeats the name of a procedure on the "begin" -- line, and special AdaControl comments check comments (terminating, begin, "^ *##"); -- Named begin required for packages unless they have no -- declaration, and subprograms if they have nested units check comments (unnamed_begin, declaration package); check comments (unnamed_begin, program_unit procedure); check comments (unnamed_begin, program_unit function); -- End record must be named if the declaration is more than 10 lines check comments (unnamed_end_record, 10);
The following subrules generate fixes:
begin if it has no comment, or replaces an existing
comment.
end record if it has no comment, or replaces an existing
comment.
Remember that a Regexp matches if the pattern matches any part of the identifier. Use “^” and “$” to match the beginning (resp. end) of the comment, or both.
For “unnamed_begin”, the <condition> defines cases where the comment is optional; however if a comment is present in an optional case, it has to be the name of the corresponding unit. Similarly for “unnamed_end_record”, the comment is optional if the number of lines in the declaration is less than <value>; however if a comment is present, it has to be the name of the corresponding type.
“unnamed_end_record” does not control null record definitions
(i.e. “is null”) since there is no end record in
that case (anyway, these declarations are so short that it would make
little sense to require a naming comment).
For “unnamed_begin” and “unnamed_end_record”, the fix replaces an existing comment on the ground that it is likely that the wrong comment is actually the old name of an entity that has been renamed.
This rule does not support wide characters outside the basic Latin-1 set.
Next: Dependencies, Previous: Comments, Up: Rules reference
This rule controls usage of various kinds of declarations, possibly only those occurring at specified locations.
<control_kind> declarations (<subrule> {, <subrule>});
<subrule> ::= {[not] <location>} [ignore "<pattern>"] <declaration_kw>
<location> ::= all | block | library | local | own |
private | public | in_generic | task_body
<declaration_kw> ::=
any_declaration |
abstract_function | abstract_operator |
abstract_procedure | abstract_type |
access_all_type | access_constant_type |
access_constrained_array_type | access_def_discriminated_type |
access_formal_type | access_language_type |
access_nondef_discriminated_type | access_protected_type |
access_subprogram_type | access_task_type |
access_type | access_unconstrained_array_type |
access_unknown_discriminated_type | aliased_array_component |
aliased_constant | aliased_protected_component |
aliased_record_component | aliased_variable |
anonymous_access_component | anonymous_access_constant |
anonymous_access_discriminant | anonymous_access_parameter |
anonymous_access_variable | anonymous_subtype_allocator |
anonymous_subtype_case | anonymous_subtype_declaration |
anonymous_subtype_for | anonymous_subtype_indexing |
array | array_type |
binary_modular_type | box_defaulted_formal_function |
box_defaulted_formal_procedure | character_literal |
child_unit | class_wide_constant |
class_wide_variable | constant |
constrained_array_constant | constrained_array_type |
constrained_array_variable | constructor |
controlled_type | decimal_fixed_type |
defaulted_discriminant | defaulted_generic_parameter |
defaulted_parameter | deferred_constant |
derived_type | discriminant |
empty_private_part | empty_visible_part |
entry | enumeration_type |
equality_operator | exception |
expression_function | extension |
fixed_type | float_type |
formal_function | formal_package |
formal_procedure | formal_type |
function | function_instantiation |
generic | generic_function |
generic_package | generic_procedure |
handlers | in_out_generic_parameter |
in_out_parameter | incomplete_type |
initialized_protected_component | initialized_record_component |
initialized_variable | instantiation |
integer_type | interface_type |
limited_private_type | modular_type |
multiple_names | multiple_protected_entries |
name_defaulted_formal_function | name_defaulted_formal_procedure |
named_number | no_spec_function |
no_spec_procedure | non_binary_modular_type |
non_joint_ce_ne_handler | non_limited_private_type |
non_ravenscar_task | null_defaulted_formal_procedure |
null_extension | null_ordinary_record_type |
null_procedure | null_procedure_body |
null_procedure_declaration | null_tagged_type |
operator | ordinary_fixed_type |
ordinary_fixed_type_no_small | ordinary_fixed_type_with_small |
ordinary_record_type | ordinary_record_variable |
out_parameter | package |
package_instantiation | package_statements |
predefined_operator | private_extension |
procedure | procedure_instantiation |
protected | protected_discriminant |
protected_entry | protected_type |
protected_variable | record_type |
relay_function | relay_package |
relay_procedure | scalar_variable |
self_calling_function | self_calling_procedure |
separate | signed_type |
single_array | single_protected |
single_task | subtype |
tagged_incomplete_type | tagged_private_type |
tagged_type | tagged_variable |
task | task_discriminant |
task_entry | task_type |
task_variable | type |
unconstrained_array_constant | unconstrained_array_type |
unconstrained_array_variable | unconstrained_subtype |
uninitialized_protected_component | uninitialized_record_component |
uninitialized_variable | unknown_discriminant |
variable | variant_part
The <location_kw> restricts the places where the occurrence of the declaration is controlled. If it is preceded by “not”, the declaration is controlled except at this location. Several <location_kw> can be given, in which case the declaration is controlled at places where all the keywords apply. If there is no <location_kw>, it is assumed to be “all”.
If “ignore "<pattern>"” is specified, declarations whose full name matches the <pattern> are not controlled. The full name is the fully qualified name (including the enclosing packages, etc...). The <pattern> is a regular expression. See Syntax of regular expressions. See example below.
all: puts no special restriction to the location. This keyword
can be specified for readability purposes, and if specified must
appear alone (not with other <location_kw>), and “not” is not
allowed.
block: only declarations appearing in block statements are controlled.
library: only library level declarations are controlled.
local: only local declarations are controlled (i.e. only declarations
appearing in (generic) packages, possibly nested, are allowed).
own: only declarations that are local to a (generic) package body
are controlled.
public: only declarations appearing in the visible part of
(generic) packages are controlled.
private: only declarations appearing directly in a private
part are controlled.
in_generic: only declarations appearing directly or indirectly in a generic
specification or body are controlled.
task_body: only declarations appearing directly in a task body
are controlled. Note that it would not make sense to have a
<location_kw> for task specifications, since only entries can
appear there, and they cannot appear anywhere else.
The <declaration_kw> specifies what kind of declaration to control:
any_declaration controls all declarations. This is of course not
intended to forbid all declarations in a program (!), but
counting all declarations can be quite useful.
abstract_function, abstract_operator, and
abstract_procedure control the declarations of abstract
functions, abstract operators, and abstract procedures, respectively.
abstract_type controls the declaration of non-formal abstract
types.
access_type controls all access type declarations, while
access_subprogram_type, access_protected_type, and
access_task_type control only access to procedures or
functions, access to protected types, or access to task types,
respectively. Similarly, access_constrained_array_type and
access_unconstrained_array_type control access to constrained
or unconstrained array types, access_def_discriminated_type,
access_nondef_discriminated_type, and
access_unknown_discriminated_type control access to types with
discriminants with default values, without default values, and unknown
discriminants, respectively. access_formal_type controls access
to (generic) formal types, access_all_type control generalized
access to variables types (aka "access all T", and
access_constant_type control generalized access to constants
types (aka "access constant T"). access_language_type
controls access to language defined private types.
aliased_variable and aliased_constant control the
declarations of aliased variables or constants, respectively.
aliased_array_component controls the declaration of arrays
(array types or single arrays) whose components are declared aliased.
aliased_record_component and aliased_protected_component
control the declarations of aliased record (respectively protected)
components.
anonymous_access_component controls array and record components
that are of an anonymous access type (but not discriminants, which are
controlled by anonymous_access_discriminant). Similarly,
anonymous_access_constant and anonymous_access_variable
control constants and variables that are of an anonymous access type
(including generic formal in and in out
parameters, respectively). anonymous_access_parameter controls
subprogram parameters that are of an anonymous access type, the only
ones that existed in Ada 95. Note that to avoid unnecessary messages,
if a subprogram has an explicit specification, the message for
anonymous_access_parameter is given on the specification and
not repeated on the body.
anonymous_subtype_declaration controls the declarations of
anonymous subtypes and ranges that are part of some other
declaration. Similarly, anonymous_subtype_allocator,
anonymous_subtype_case, anonymous_subtype_for, and
anonymous_subtype_indexing control anonymous subtype
declarations and ranges that are part of allocators, case
statements (ranges in the when path), for loop
statements, and indexing of slices or array aggregates, respectively.
array controls all array definitions (array types and single
arrays), while array_type controls only array types and
single_array controls only single arrays (objects of an
anonymous array type). constrained_array_type controls only
constrained array types, while unconstrained_array_type
controls only unconstrained array
types. constrained_array_variable controls variable
declarations where the given (or anonymous) array type is constrained,
while unconstrained_array variable controls variable
declarations where the given (or anonymous) array type is
unconstrained (and the constraint is provided by the initial value).
constrained_array_constant and
unconstrained_array_constant do the same with constants instead
of variables.
character_literal controls the declaration of new character
literals, i.e. character literals defined as part of the values of an
enumeration type.
child_unit controls the declaration of all child units.
constant controls all constants, while
class_wide_constant control the declaration of constants of a
class-wide type, and deferred_constant controls the declaration
of deferred constants.
constructor controls the declaration of a primitive function
of a tagged type acting as a constructor, i.e. a function that returns
the tagged type and without any parameter of that type.
controlled_type controls the declaration of controlled types,
i.e. descendants of Ada.Finalization.Controlled or
Ada.Finalization.Limited_Controlled. Note that this includes
also private types that are not visibly controlled.
defaulted_parameter controls subprogram or entry (in)
parameters that provide a default value, while
defaulted_generic_parameter controls generic formal objects
that provide a default value.
derived_type controls regular derived types, but not type
extensions (derivations of tagged types). These are controlled by
extension and private_extension.
discriminant controls all declarations of types with
discriminants, while protected_discriminant and
task_discriminant control only discriminants of protected types
and task types, respectively. defaulted_discriminants controls
only discriminants where default values are
provided. unknown_discriminants controls only unknown
discriminants (AKA “(<>)” discriminants).
empty_private_part controls package specification with an empty
private part, i.e. where the word private appears, but the
private part contains no declaration (even if it contains pragmas).
empty_visible_part controls package specifications that contain
no declaration in the visible part (before the word private
if any), even if it contains pragmas.
enumeration_type controls the declaration of enumeration types.
exception controls exception declarations.
expression_function controls declaration of expression functions, while
function controls all “regular” function declarations.
extension controls type extensions, i.e. derivations from a tagged type
with a with record extension part.
fixed_type controls all declarations of fixed point types while
ordinary_fixed_type controls only ordinary (binary) fixed point
types, ordinary_fixed_type_no_small controls ordinary fixed
point type without a representation clause for 'SMALL,
ordinary_fixed_type_with_small controls ordinary fixed point
type with an explicit representation clause for 'SMALL, and
decimal_fixed_type controls only decimal fixed point types
(those can never have a representation clause for 'SMALL).
float_type controls declarations of floating point types.
formal_function, formal_package,
formal_procedure, and formal_type control all generic
formal functions, packages, procedures, and types,
respectively. box_defaulted_formal_function,
box_defaulted_formal_procedure, name_defaulted_formal_function,
name_defaulted_formal_procedure, and
null_defaulted_formal_procedure control generic formal
functions and procedures with a box default, a name default, and a
null default, respectively.
generic_function, generic_package,
generic_procedure control generic function (respectively
package, procedure) declarations.
handlers controls the presence of exception handlers in any
handled sequence of statements.
in_out_parameter and out_parameter control subprogram
and entry parameters of modes in out and
out (respectively), while in_out_generic_parameter
and out_generic_parameter do the same for generic formal
parameters. Note that to avoid unnecessary messages, if a subprogram
has an explicit specification, the message is given on the
specification and not repeated on the body.
incomplete_type controls (regular) incomplete type
declarations, while tagged_incomplete_type controls tagged
incomplete type declarations (Ada 2005).
initialized_variable controls variable declarations that
include an initialization expression, unless they are of a class-wide
type since initialization is required in that case.
instantiation controls all instantiations, while
function_instantiation, package_instantiation,
procedure_instantiation control function (respectively package,
procedure) instantiations.
integer_type controls all declarations of integer types, while
signed_type controls only signed integer types, and
modular_type controls only modular types (both kinds);
binary_modular_type controls only modular types whose modulus
is a power of 2, and non_binary_modular_type controls only
modular types whose modulus is not a power of 2.
initialized_record_component and
initialized_protected_component control the declaration of
record (respectively protected) component that include a default
initialization, while uninitialized_record_component and
uninitialized_protected_component control the declaration of record
(respectively protected) component that do not include a default
initialization, unless they are of a limited type since initialization would
not be allowed in that case.
limited_private_type controls limited private type
declarations, while non_limited_private_type controls regular
(non limited) private type declarations. tagged_private_type
controls tagged private type declarations.
multiple_names controls declarations where more than one
defining identifier is given in the same declaration.
multiple_protected_entries controls protected definitions (from
protected types or single protected objects) that have more than one
entry declaration. Note that a protected definition with a single
entry family declaration is counted as a single entry declaration.
named_number controls declarations of named numbers,
i.e. untyped constants.
no_spec_function and no_spec_procedure control function
and procedure bodies respectively, including body stubs (but not
proper bodies since the control is on the stub), that do not have an
explicit specification.
non_joint_CE_NE_handler controls exception handlers whose
choices include Constraint_Error or Numeric_Error, but
not both. This is intended for legacy Ada 83 code that required to
always handle these exceptions together; it makes little sense for
Ada95 or Ada2005 code (and to be honnest, this subrule is provided
because Gnatcheck has it).
null_extension controls record extensions (derived tagged
types) that contain no new elements. Similarly,
null_ordinary_record_type and null_tagged_type control
ordinary records and tagged types that contain no elements. Note that
the record definitions may be plain “null
record” definitions, or full record definitions that
contain only null components. However, a definition is not considered
null if it contains a variant part.
null_procedure_body controls procedure declarations whose
sequence of statements contain only null statements (or
blocks without declarations and containing only null
statements). null_procedure_declaration controls Ada2005 null
procedure declarations (i.e., “procedure P is
null;”). null_procedure controls both.
operator controls the definition of operators (things like
"+"); note that the message is given on the specification if
there is an explicit specification, on the body
otherwise. equality_operator controls only equality operators
("=" and "/=") and predefined_operator controls
only operator definitions that overload a predefined operator (like
"+" on a numeric type, for example).
package_statements controls the presence of elaboration
statements in the bodies of packages (or generic packages).
private_extension controls private extensions, i.e. derivations
from a tagged type with a with private extension part.
record_type controls all record type declarations (tagged or
not), while ordinary_record_type controls only non-tagged
record types, and tagged_type controls only tagged record types.
interface_type controls interface type declarations.
relay_function controls functions whose statement part includes
only a single return statement whose expression is another
function call; similarly, relay_procedure controls procedures
whose statement part includes only a call to another procedure, and
relay_package controls packages whose visible part includes
only the declaration of another package (regular package,
instantiation of a generic package, or renaming of package).
self_calling_function controls functions whose body contains
only a single (simple) return statement, and the return
expression is a (recursive) call to the same function. Similarly,
self_calling_procedure controls procedures whose body contains
only a single statement which is a (recursive) call to the same
procedure. Note that this corresponds to bodies automatically
generated by gnatstub.
subtype controls all explicit subtype declarations (i.e. not
all anonymous subtypes that appear at various places in the
language), while unconstrained_subtype controls only the
subtype declarations that do not include a constraint.
task controls task type declarations as well as single tasks
declarations while single_task and task_type control
only single task declarations or task type declarations respectively
(and similarly for protected). non_ravenscar_task controls
all task type and task object declarations from a unit to which no
pragma Profile (Ravenscar) applies.
type controls all type (but not subtype) declarations.
uninitialized_variable controls variable declarations that
do not include an initialization expression. Depending on the value of
the rule variable “Limited_Initialization” (see below), variables of
a limited type, or only variables of a task or protected type, are not
reported, since initialization would not be allowed in that case.
variable controls all variable declarations.
scalar_variable controls the declarations of variables of a
scalar type (integer, enumeration, float, fixed).
ordinary_record_variable controls declarations of variables of
an untagged record type. tagged_variable controls declarations
of variables of a tagged type (including class-wide ones), while
class_wide_variable controls only the declarations of variables
of a class-wide type. task_variable and
protected_variable control task and protected objects
(respectively), whether given with a named or anonymous type.
variant_part controls variant parts in record defintions.
Ex:
-- No task, no exception: search declarations (task, exception); -- Don't declare subprograms or packages inside a block: check declarations (block procedure, block function, block package); -- No task in the public part of a package: check declarations (public task); -- Generics allowed only as top-level units check declarations (not library generic); -- No variable in package spec except those declared in package Globals check declarations (public ignore "^globals." variable);
The rule provides a variable to adjust the handling of limited types for the subrule “uninitialized_variable”. Initialization of variables of a limited type was not permitted until Ada 2005.
| Variable | Values | Effect |
| Limited_Initialization | off (default) | Uninitialized variables of a limited type are never reported. |
| on | Uninitialized variables of a limited type are are reported like non-limited variables, unless they are of a task or protected type, since no initialization would be allowed in that case. |
Certain keywords are not exclusive, and it may be the case that several keywords apply to the same declaration; in this case, they are all reported. For example, if you specify:
check declarations (record_type, tagged_type);
tagged types will be reported both as “record_type” and “tagged_type”.
Note that “function” does not control expression functions; specify “expression_function” also if you want both controlled at the same time.
There is no subrule for checking functions whose result type is from
an anonymous access type; these are controlled by the rule
return_type (anonymous_access). See Return_Type.
Some of the keyword do not seem very useful; it would be strange to have a programming rule that prevents all type declarations... But bear in mind that the <location_kw> can be used to restrict the check to certain locations; moreover, AdaControl can be used not only for checking, but also for searching; finding all type declarations in a set of units can make sense. As another example, “search declarations (own variable);” will find all variables declared directly in package bodies.
Some modifiers do not make sense with certain declarations; for example, a “private out_parameter” is impossible (a parameter occurs in a subprogram declaration, not directly in a private part). This is not a problem as far as the rule is concerned, but don’t expect to find any...
Generally, discriminants are considered components of record
types. However, discriminants of an anonymous access type (so-called
access discriminants) play such a special role in the language that
they deserved their own control
(anonymous_access_discriminant).
Private types are normally followed in determining the kind of access type (i.e., an access to a private type will be controlled according to the full declaration). However, this is not done for an access type that designates a private type defined in a language defined unit (since the full type depends on the implementation); these are controlled as “access_language_type” instead. Of course, language defined visible types are controlled normally.
In some rare cases, AdaControl may not be able to evaluate the modulus of a modular type definition, thus preventing correct operation of “binary_modular_type” and “non_binary_modular_type” subrules. Such cases are detected by the rule “uncheckable”. See Uncheckable.
Next: Derivations, Previous: Declarations, Up: Rules reference
This rule controls dependencies of units (i.e. with
clauses, parents, child units...), either according to a set of
allowed/forbidden units, or by count.
<control_kind> dependencies (others, <unit> {,<unit>});
<control_kind> dependencies (with, <unit> {,<unit>});
<control_kind> dependencies (public_child | private_child);
<control_kind> dependencies (<counter>, <bound> [, <bound>]);
<counter> ::= raw | direct | parent
<bound> ::= min | max <value>
The first parameter is a subrule keyword:
Note that for these two rules, renamings are followed: if you give the basic name of a unit, it will be identified even if used with other names. Similarly, if you give the name of a generic, all of its instantiations will also be controlled.
Other subrules control that the number of various dependencies is whithin a specified range. The second (and optionnally third) parameter give the minimum and/or maximum allowed values (i.e. the rule will control values outside the indicated interval). If not specified, the minimum value is defaulted to 0 and the maximum value to infinity.
with clauses. Redundant with clauses are
counted, and a child unit counts for one.
with
clauses, it is counted only once, but if a child unit is mentionned,
all parents of this child unit are added to the count.
Ex:
check dependencies (others, Ada.Text_IO); check dependencies (raw, max 15); -- child units should not be nested more than 5 levels: check dependencies (parent, max 5); -- units that depend on nothing: search dependencies (direct, min 1); -- units that depend on their public children: check dependencies (public_child);
If you give a name that’s already a renaming to the “others” or “with” subrules, the rule will only apply to this name, not to what has been renamed. Therefore:
-- Allow only Ada.Text_IO: check dependencies (others, Ada.Text_IO); -- But not if the plain name Text_IO is used: check dependencies (with, Text_IO);
The notion of public or private for the rules “public_child” or “private_child” refer to the real unit, which is not necessarily the name used in the with clause, if for example you have a private library renaming of a public unit.
There is a slight overlap between this rule and the rule
“entities’. But “entities” will find all uses of an entity (not
necessarily a compilation unit), while “dependencies” will control
occurrences only of compilation units, and only in with
clauses. See Entities.
In certain contexts, only a set of the Ada predefined units is
allowed. For example, it can be useful to forbid units defined in
special needs annexes. The rules directory of Adacontrol
contains files with “Dependencies” rules that forbid the use of
various predefined Ada units. Comment out the lines for the units that
you want to allow. You can then simply “source” these files from
your own command file (or copy the content) if you want to disallow these
units. See command files provided with AdaControl.
Next: Directly_Accessed_Globals, Previous: Dependencies, Up: Rules reference
This rule controls various properties of the declaration and primitive operations of derived types.
<control_kind> derivations (from, <entity>|<category>
{, <entity>|<category>})
<control_kind> derivations (max_parents, <value>)
<control_kind> derivations (max_depth, {<type kind>} <value>)
<control_kind> derivations (indicator
[, overriding | not_overriding]
[, tagged | untagged]
[, declaration ]
[, body_required | body_forbidden])
<type kind> ::= tagged | untagged | task | protected
The first parameter is a subrule keyword:
If <entity> is a type name, it controls types that are derived (directly or indirectly) from the given type (including interfaces), or one of its subtypes; however, if it is a subtype name, only types that are derived (directly or indirectly) from the given subtype are controlled. If <entity> is the name of a compilation unit, it controls types that are derived (directly or indirectly) from any type (or subtype) declared inside the given unit. As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name.
If a <category> is given, it controls derived types whose parent type belongs to the corresponding category. This rule traverses derivations, but not privacy (the category “private” can be given, to check types derived from a private type). See Definition of type categories.
It may be the case that several controls apply to a given parent type. In this case, only one message is issued, that corresponds to the most specific control according to the following priority order:
If a category also applies to the parent type, a separate message is always issued.
Ex:
check derivations (from, Standard.Integer); -- Types derived from Integer search derivations (from, standard); -- Types derived from a type in Standard, except Standard.Integer -- (caught above) search derivations (from, range, mod); -- Types derived from an integer type (signed or modular)
This subrule can be given once for each of check, search, and count. This way, it is possible to have a number of parents considered a warning (search), and one considered an error (check). Of course, this makes sense only if the number for search is less than the one for check.
Ex:
-- error if more than 5 parents: check derivations (max_parents, 5); -- warning if more than 3 parents search derivations (max_parents, 3);
If one or several <type kind> “tagged”, “untagged”, “task”, or “protected” is given the rule applies only to derivations of tagged, untagged, task, or protected types respectively. Without modifiers, the rule applies to all forms of derived types.
Types declared in generics are normally checked, and are also checked in instantiations. The derivation depth in an instantiation may be greater than the one of its generic counterpart.
This subrule can be given only once for each combination of “check”, “search”,“count”, and “tagged”, ”untagged”, ”task”, ”protected”. This way, it is possible to have a depth considered a warning (search), and one considered an error (check). Of course, this makes sense only if the number for search is less than the one for check.
Ex:
-- error if any derivation depth greater than 5 check derivations (max_depth, 5); -- warning if derivation depth of tagged types greater than 3 search derivations (max_depth, tagged 3);
If “overriding” or “not_overriding” is given, the rule controls only the corresponding indicator. Otherwise, both are controlled.
If “tagged” or “untagged” is given, the rule controls only operations that involve a tagged type (respectively no tagged type). Otherwise, both are controlled.
If “declaration” is given, the rule applies only to subprogram specifications and subprogram bodies acting as specification (when there is no explicit specification).
If “body_required” is given, the indicators are required also on subprogram bodies, while if “body_forbidden” is given, the rule controls that indicators are not given on bodies (except for those acting as specification). If none of these are given, indicators on bodies are not controlled.
In the absence of “declaration”, “body_required”, and “body_forbidden”, only declarations are controlled.
Ex:
check derivations (indicator); -- all defaults, controls all types, declaration only check derivations (indicator, tagged, declaration); search derivations (indicator, tagged, body_forbidden); -- Error if no indicator on a subprogram declaration -- for a tagged type -- Warning if indicator also given on the corresponding body check derivations (indicator, overriding); search derivations (indicator, not_overriding); -- Error if no overriding indicator -- Warning if no not overriding indicator
This subrule can be given only once for each combination of the parameters.
The following subrule generates fixes:
Since categories are checked only for the parent type, the control
“check derivations (from, interface);” controls only the case
where the parent type is an interface. To check all types that
implement any interface, add the control “check derivations
(max_parents, 1);", since progenitors are necessarily interfaces.
Normally, an overriding indicator is given on a specification. It is allowed on a body for the cases where the body acts as a declaration. Hence, it makes sense to forbid an overriding indicator on a (true) body. On the other hand, some can prefer having specification and body being the same. That’s why both “body_required” and “body_forbidden” can be specified.
The issue of silently overriding an inherited subprogram is really an issue with tagged types and the effect on dynamic dispatching; it is much less of an issue for untagged types, therefore it makes sense to apply the rule only to tagged types to avoid to many violations for regular types.
Due to a weakness in the ASIS standard, the presence or absence of indicators on entries that implement operations of an interface are not checked.
Next: Duplicate_Initialization_Calls, Previous: Derivations, Up: Rules reference
This rule checks that global variables in package bodies are accessed only through dedicated subprograms. Especially, it can be used to prevent race conditions in multi-tasking programs.
<control_kind> directly_accessed_globals [(<kind> {,<kind>})];
<kind> ::= plain | accept | protected
The rule controls global variables declared directly in (generic)
package bodies that are accessed outside of dedicated callable
entities (i.e. procedure or function, possibly protected, protected
entries, and accept statements).
This rule can be specified only once. The parameters indicate which
kinds of callable entity are allowed: “plain” for non-protected
subprograms, “protected” for protected subprograms, and “accept”
for accept statements). Without parameters, all forms are
allowed.
More precisely, the rule ensures that the global variables are read from a single callable entity, and written by a single callable entity. Note that the same callable entity can read and write a variable, but in this case no other callable entity is allowed to read or write the variable.
accept statements used to read/write the variables must
both be part of the same single task object, which must be declared at
the same level as the variable itself (i.e. not nested); they are not
allowed to be declared in a task type, since if there are several
task objects of the same type, mutual exclusion would not be enforced.
In short, this rule enforces that all global variables are accessed by dedicated access subprograms, and that only those subprograms access the variables directly. If given with the keyword “protected” and/or “accept”, it enforces that global variables are accessed only by dedicated protected subprograms or tasks, ensuring that no race condition is possible.
Ex:
check directly_accessed_globals
Note that this rule controls global variables from package bodies, not those from the specification. This is intended, since it makes little sense to declare a variable in a specification, and then require it not to be accessed directly, but through provided subprograms. Obviously, in this case the variable should be moved to the body.
Note that AdaControl can check that no variable is declared in a package specification with the following rule:
check usage (variable, from_spec);
see Usage for details.
AdaControl cannot check entities accessed through dynamic names (dynamic renaming, access on aliased variables). Use of such constructs is detected by the rule “uncheckable”. See Uncheckable.
Due to a weakness in the ASIS standard, it is not possible to know the mode (in, out) of variables used as parameters of dispatching calls. Such variables are considered to be read and written at the point of the call, therefore possibly creating false positives (which is safer than false negatives). Use of such constructs is detected by the rule “uncheckable”. See Uncheckable.
Next: Entities, Previous: Directly_Accessed_Globals, Up: Rules reference
This rule checks that some procedures (notably initialization procedures) are not called several times in identical conditions.
<control_kind> duplicate_initialization_calls (<entity> {, <entity>});
This rule controls calls to initialization procedures that are duplicated. The <entity> parameters are the initialization procedures to be controlled. As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name.
More precisely, the initialization procedures must follow one of these patterns:
in parameters. All actual parameters
used in calls are static, and not two calls have the same values for
all parameters.
out parameter (and no
in out parameter). Not two calls refer the same actual variable
for the out parameter.
The rule controls any violation of these patterns. If a procedure passed as parameter does not have a profile that corresponds to one of the above patterns, it is an error.
Ex:
check duplicate_initialization_calls (pack.init_proc);
If a variable passed as an out parameter is not statically
determinable, it is not controlled by the rule. Such a case is
detected by the rule “uncheckable”. See Uncheckable.
Next: Entity_Inside_Exception, Previous: Duplicate_Initialization_Calls, Up: Rules reference
This rule is used to control usage of Ada entities, i.e. any declared element (type, variables, packages, etc).
<control_kind> entities ({[not] <location>} [instance] <entity>
{, {[not] <location>} [instance] <entity>});
<location> ::= block | library | local | nested | own |
private | public | in_generic | task_body
This rule controls all uses of the indicated entities,or only those that appear within the specified locations. As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name.
When present, the <location_kw> restricts the places where the entity is controlled. If it is preceded by “not”, the entity is controlled except at this location. Several <location_kw> can be given, in which case the entity is controlled at places where all the keywords apply.
block: the entity appears in a block statement.
library: the entity appears at library level.
local: the entity appears in a local scope (i.e. not in
(generic) packages, possibly nested)
own: the entity appers in a (generic) package body.
public: the entity appears in the visible part of a
(generic) package.
private: the entity appears directly in a private
part.
in_generic: the entity appears directly or indirectly in a generic
specification or body.
task_body: the entity appears directly in a task body.
If the given entity is a generic unit or an
entity declared inside a generic unit, all corresponding uses in all
instances will be reported. Uses of the generic entity itself will also
be reported normally, unless the keyword instance is given.
Note that this rules reports on the use of the entity, not the name: if an entity has been renamed, it will be found under its various names.
Ex:
search entities (Debug.Trace); check entities (Ada.Text_IO.Float_IO.Put); check entities (instance Ada.Unchecked_Conversion);
The second line will report on any use of a Put from any
instantiation of Float_IO. The third one will report only
on uses of instances of Ada.Unchecked_Conversion.
This rule is safer than cross-references if you want to check where certain entities are used, since it follows renamings but does not report on homonyms of the intended entity.
This rule can also be used to check for all occurrences of certain
attributes with the “all <Attribute>” syntax. For example,
the following will report on any usage of 'Unchecked_Access:
check entities (all 'Unchecked_Access);
If you want to make sure that certain compilation units are not used,
it is preferable to use the rule “Depencies (with,...)” rather than
“Entities”, because “Entities” will control all uses of the unit,
while “Dependencies” will control only those in with
clauses (which is of course sufficient).
In certain contexts, it can be useful to forbid certain entities, like
those from Standard, System, or entities defined in
special needs annexes packages. The rules directory of
Adacontrol contains files with “Dependencies” and “Entities” rules
that forbid the use of various predefined Ada elements. Comment out
the lines for the elements that you want to allow. You can then
simply “source” these files from your own command file (or copy the
content) if you want to disallow these elements. See command files provided with AdaControl.
GNAT defines Unchecked_Conversion and
Unchecked_Deallocation as separate entities, rather than
renamings of Ada.Unchecked_Conversion and
Ada.Unchecked_Deallocation. As a consequence, it is necessary
to specify explicitely both forms if you want to make sure that the
corresponding generics are not used.
Next: Exception_Propagation, Previous: Entities, Up: Rules reference
This rule controls entities that appear within exception handlers.
<control_kind> entity_inside_exception (<spec> {, <spec>});
<spec> ::= [not] <entity> | calls | entry_calls
This rule controls exception handlers that contain references to one or several Ada entities specified as parameters. If the keyword “calls” is given, it stands for all subprogram and entry calls. If the keyword “entry_calls” is given, it stands for all entry calls (task or protected). If an <entity> (or “calls” or “entry_calls”) is preceded by the keyword “not”, it is not included in the list of controlled entities (i.e. the entity is allowed in the exception handler). This allows to make exceptions to a more general specification of an entity, or to allow calls to well-defined procedures if the keyword “calls” is given.
Ex:
-- No Put_Line in exception handlers:
check entity_inside_exception (ada.text_io.put_line);
-- No entry calls in exception handlers:
check entity_inside_exception (entry_calls);
-- No calls allowed, except to the Report_Exception procedure:
check entity_inside_exception (calls, not Reports.Report_Exception);
-- No Put allowed, except the one on Strings:
check entity_inside_exception (all Put,
not Ada.Text_IO.Put{Standard.String});
Next: Expressions, Previous: Entity_Inside_Exception, Up: Rules reference
This rule controls that certain program units are guaranteed to never propagate exceptions, or that local exceptions cannot propagate out of their scope.
<control_kind> exception_propagation
(local_exception);
<control_kind> exception_propagation
([<level>,] interface, <convention> {, <convention> });
<control_kind> exception_propagation
([<level>,] parameter, <entity> {, <entity>});
<control_kind> exception_propagation
([<level>,] task);
<control_kind> exception_propagation
(<level>, declaration);
The “local_exception” subrule controls a design pattern that ensures
that a local exception cannot propagate outside the scope where it is
declared. If an exception is declared within a block, a subprogram
body, an entry body, or a task body, then this body must have either a
handler for this exception or for others; this handler must
not reraise the exception; and no handler is allowed to raise
explicitely the exception. The subrule controls explicit
raise statements and calls to Raise_Exception and
Reraise_Occurrence, but it does not control exceptions raised
as a consequence of calling other subprograms.
The other subrules control subprograms, tasks, or all declarations that can propagate exceptions, while being used in contexts where it is desirable to ensure that no exception can be propagated.
A subprogram or task is considered as not propagating if:
when others” choice
raise statement, nor any
call to Ada.Exception.Raise_Exception or
Ada.Exception.Reraise_Occurrence.
A declaration is considered propagating if it includes elements that could propagate exceptions. This is impossible to assess fully using only static analysis, therefore the <level> parameter determines how pessimistic (or optimistic) AdaControl is in determining the possibility of exceptions. Possible values of the <level> parameter, and their effect, are:
These subrules serve several purposes:
Interface or Export pragma applies (with the given
convention(s)), and reports on those that can propagate
exceptions.
Since it is dangerous to call an Ada subprogram that can propagate exceptions from a language that has no exception (and especially C), any such subprogram should have a “catch-all” exception handler.
'Access or
'Address attribute that appears as part of an actual value for
the indicated formal. Similarly, the indicated formal can also be the
name of a formal procedure or function of a generic. In this case, the
rule will report on any subprogram that can propagate exceptions and
is used as an actual in an instantiation for the given formal.
Many systems (typically windowing systems) use call-back subprograms. Although the native interface is generally hidden behind an Ada binding, the call-back subprograms will eventually be called from another language, and like for the “interface” subrule, any such subprogram should have a “catch-all” exception handler.
Since tasks die silently if an exception is propagated out of their body, it is generally desirable to ensure that every task has an exception handler that (at least) reports that the task is being completed due to an exception.
It is sometimes desirable to make sure that no declaration raises an exception, ever.
Ex:
-- Make sure that C-compatible subprograms don't propagate exceptions: check exception_propagation (interface, C); -- Parameter CB of of procedure Pack.Register is used as a call-back -- Make sure that not procedure passed to it can propagate exceptions. check exception_propagation (parameter, Pack.Register.CB); -- Make sure that tasks do not die silently due to unhandled exception: check exception_propagation (task); -- Make sure that no exception is raised by elaboration of declarations: check exception_propagation (2, declaration);
The first example will report on any subprogram to which a
pragma Interface (C,...) applies that can propagate
exceptions.
If Proc is a procedure that can propagate exceptions, the
second example will report on every call like:
Pack.Register (CB => Proc'Access);
The third example will report on any task that can terminate silently due to an unhandled exception.
The fourth example will report on any declaration that makes use of function calls or variables.
Note that the registration procedure for a call-back can be designated by an access type, but in this case, use the name of the formal for the access type. For example, given:
package Pack is type Acc_Proc is access procedure; type Acc_Reg is access procedure (CB : Acc_Proc); ... Ptr : Acc_Reg := ...;
You can give a rule such as:
check exception_propagation (parameter, Pack.Acc_Reg.CB);
All procedures registered by a call to Pack.Ptr.all will be considered.
The declaration of a for loop parameter is not checked by this rule. In other words, the rule “check exception_propagation (2, declaration)” will not issue a message for:
for I in Positive range 1 .. X loop ...
although formally the declaration of I could raise Constraint_Error if X is negative. We consider that for the casual user, Constraint_Error appears to be raised by the for loop statement.
An exception may be raised in a subprogram considered as not propagating by this rule, if an exception handler calls a subprogram that propagates an exception.
The rule will not consider subprograms whose body is missing, or that are not statically known (i.e. if a subprogram is registered through a dereference of a pointer to subprogram), like in the following example:
Pack.Register (CB => Pointer.all'Access);
Due to a weakness of the ASIS standard, references to subprograms that appear in dispatching calls are not considered. This limitation will be removed as soon as we find a way to work around this problem, but the issue is quite difficult!
These last two cases are detected by the rule “uncheckable”. See Uncheckable.
Next: Generic_Aliasing, Previous: Exception_Propagation, Up: Rules reference
This rule controls usage of various kinds of expressions.
<control_kind> expressions (<subrule> {, <subrule>});
<subrule> ::= {<category>} <expression_kw>
<expression_kw> ::=
and | and_array |
and_binary | and_boolean |
and_then | array_aggregate |
array_named_others | array_non_static_range |
array_others | array_partial_others |
array_positional_others | array_range |
case | complex_parameter |
dispatching_function_call | downward_conversion |
dynamic_function_call | explicit_dereference |
extendable_aggregate | extension_aggregate |
fixed_multiplying_op | for_all |
for_some | function_call |
if | if_elsif |
if_no_else | implicit_dereference |
in | inconsistent_attribute_dimension |
inherited_function_call | mixed_operators |
not | not_in |
or | or_array |
or_binary | or_boolean |
or_else | parameter_view_conversion |
prefixed_operator | real_equality |
record_aggregate | record_others |
record_partial_others | redispatching_function_call |
slice | static_membership |
target_name | trivial_target_name |
type_conversion | unconverted_fixed_multiplying_op |
underived_conversion | universal_range |
unqualified_aggregate | upward_conversion |
xor | xor_array |
xor_binary | xor_boolean
This rule controls usage of certain forms of expressions. The rule can be specified at most once for each subrule (i.e. subrules that accept categories can be specified once for each combination of categories and expression keyword).
Categories are used by certain subrules to further refine the control. They define categories of types to which they apply. All such subrules traverses derivations, but not privacy (the category “private” can be given, to check private types). See Definition of type categories.
The subrules define the kind of expression being controlled:
not, and, or, xor, and_then,
or_else, in, and not_in control usage of the
corresponding logical operator (or short circuit form, or membership
test).
and_array, or_array, and xor_array do the same,
but only for operators whose result type is an array type.
and_binary, or_binary, and xor_binary do the same,
but only for operators whose result type is a modular type.
and_boolean, or_boolean, and xor_boolean do the same,
but only for operators whose result type is Standard.Boolean.
array_aggregate and record_aggregate control array and
record aggregates, respectively, while unqualified_aggregate
controls aggregates (both arrays and records) that do not appear
directly within a qualified expression. extension_aggregate
controls extension aggregates, while extendable_aggregate
controls aggregates that are not extension aggregates, but whose
type is a non-root tagged type, or are extension aggregates whose ancestor part
is not their immediate parent (such aggregates could be written as
extension aggregates).
array_others and record_others control the occurrence of
a others => association in array and record
aggregates, respectively.
array_partial_others and record_partial_others do the
same, but only if there are other associations in addition to the
others => in the aggregate. array_named_others and
array_positional_others do the same, but only for named
(respectively positional) array aggregates.
array_range controls array aggregates that include a range
(i.e. an association like A .. B =>).
array_non_static_range does the same, but only if (at least)
one of the bounds is not static.
case controls case expressions (introduced in Ada 2012).
complex_parameter controls complex expressions used as actual
parameters in subprogram (or entry) calls. A complex expression is any
expression that includes a function call (including operators). This
rule is not applied to the parameters of operators, since otherwise
it would forbid any expression with more than a single operator.
explicit_dereference controls explicit dereferences of access
values (i.e. with an explicit .all).
fixed_multiplying_op controls calls to predefined fixed-point
multiplication and division (regular fixed-point or decimal-fixed
point). unconverted_fixed_multiplying_op does the same, but
only when both operands are objects (not literals) of a fixed_point
type (not Integer); this is when type conversion is required by Ada
83.
for_all and for_some control the two forms of
quantifiers introduced by Ada 2012.
if controls all if expressions (introduced in Ada 2012),
while if_elsif only controls those that have an elsif part,
and if_no_else only controls those that have no else part.
implicit_dereference controls implicit dereferences of access
values (i.e. when the .all is omitted).
inconsistent_attribute_dimension controls when no dimension is
explicitely given for a 'First, 'Last, 'Range or
'Length attribute and the attribute applies to a
multi-dimensional array, or conversely, when an explicit dimension is
given, but the attribute applies to a one-dimensional array.
function_call controls all calls to functions, including user
defined operators, but not predefined operators (including the latter
would generate too much noise). dispatching_function_call does
the same, but only for dispatching calls while
redispatching_function_call does the same, but only for
dispatching calls that are (directly or indirectly) inside a primitive
operation of a tagged type. dynamic_function_call does the
same, but only for calls through
pointers. inherited_function_call controls calls to functions
that have been inherited by a derived type and not redefined.
For all *_function_call subrules, a <category> (only one) can be
specified. In this case, only calls whose result type belongs to the
<category> are controlled. In addition, the amount of information
displayed can be selected with the rule variable “Called_Info” (see
below).
mixed_operators controls expressions that involve several
different operators, without parentheses. In a sense, it extends the
language rule that forbids mixing and and or in
logical expressions to all other operators. Note that for the purpose
of this subrule, membership tests (in, not in)
and short circuit forms (and then, or else) are
considered operators.
This subrule controls only binary operators, except for one
case: expressions of the form -A mod B are controlled, since
this is equivalent to -(A mod B), which is different from
(-A) mod B as a casual reading would understand. Requiring
parentheses for other cases of unary operator would not change the
meaning and be bad for readability.
prefixed_operator controls calls to operators that use prefixed
notation (i.e. "+"(A, B)).
A <category> (only one) can be specified. In this case, only calls whose result type belongs to the <category> are controlled.
real_equality controls usage of predefined exact equality or
inequality (“=” or “/=”) between real (floating point or fixed
point) values.
slice controls usage of array slices.
static_membership controls membership tests (in and
not in) where the expression on the left is statically
known to belong to the range (or subtype) on the right, and is
therefore always True (or false for not in).
target_name controls occurrences of the (Ada202X) symbol of
assignment target name (AKA “@”), while trivial_target_name
controls only those where the target of the assignment is a simple
identifier (and where the use of “@” doesn’t bring much).
type_conversion controls all (sub)type conversions, while
underived_conversion controls conversions between types that do
not belong to the same derivation
family. downward_conversion and upward_conversion
control conversions between types that belong to the same family,
converting away from the root or toward the root,
respectively. parameter_view_conversion controls conversions
that appear as out or in out actual parameters.
One or two categories can be specified; if one <category> is specified, only conversions whose result type belong to that <category> are controlled. If two categories are specified, only conversions whose souce type belongs to the first <category> and whose target type belongs to the second <category> are controlled. A “<>” can be specified as the target type to check all conversions from a given type to any other type.
universal_range controls discrete ranges that are a part of an
index constraint, constrained array definition, or for-loop parameter
specification (but not type or subtype defintions), and whose bounds
are both of type universal_integer.
Ex:
search expressions (real_equality, slice); check expressions (mixed_operators); -- Find logical operators that could be replaced by short-circuits: check expressions (and_boolean, or_boolean); -- Find all conversions between integer and floating point types search expression (range digits type_conversion); -- Find all conversions from a fixed point type: search expressions (delta <> type_conversion); -- Find all view conversions between array types: search expressions (array parameter_view_conversions); -- Find all "structural" conversions between arrays search expressions (array underived_conversion); -- Some think that downward conversions of tagged types are evil: check expressions (tagged downward_conversion);
The following subrule generates fixes:
The rule provides a variable to specify the amount of information displayed with the various *_function_calls subrules.
| Variable | Values | Effect |
| Called_Info | none (default) | No extra information. |
| compact | display the name of the called function. | |
| detailed | display the name of the called function with overloading information. | |
| root_detailed | display the name of the root called function (i.e. the original function if the called function is a renaming) with overloading information. |
The real_equality subrule does not control calls to an equality
operator that has been defined by the user; actually, it would make
little sense to write a function and then forbid its use! However, if
control of calls to such a function is desired, it can be easily
accomplished by using the entities rule. See Entities.
This rule does not check the use of allocators (new), use
the rule Allocators instead. See Allocators.
“inherited_function_call” controls only function calls. For procedure calls, see rule Statements.
Specifying array_partial_others is the same as specifying both
array_named_others and array_positional_others. It is
retained for compatibility, and also for symetry with
record_partial_others.
Per language rules, underived conversions are allowed only between numeric types, and between structurally equivalent array types.
“static_membership” is handy for finding a common misuse of membership tests, where the user assigns an external value (obtained with Unchecked_Conversion for example) to a variable, then checks that the variable belongs to its subtype to make sure the value is valid. Such a check can be optimized away by the compiler; the ’Valid attribute should be used instead.
“static_membership” does not control the complex membership tests with several choices that are possible with Ada 2012.
Next: Global_References, Previous: Expressions, Up: Rules reference
This rule controls instantiations where the same actual is given to more than one formal.
<control_kind> generic_aliasing [(<subrule> {, <subrule>})];
<subrule> ::= [<condition>] <target>
<condition> ::= unlikely | possible | certain
<target> ::= all | variable | type | subprogram | package
This rule identifies instantiations where the same variable, type, subprogram, or package is given several times (to different formal parameters). Such aliasing of variables is dangerous, since it can induce subtile bugs. Other elements are less dangerous, although often questionable (depending on the generic).
The <target> parameter indicates for which elements aliasing is controlled; “all” stands for all kinds of elements.
There are many cases where aliasing cannot be determined statically. The optional parameter specifies how aggressively the rule will check for possible aliasings (see Parameter_Aliasing for a more detailed description of these modifiers). Possible values are (case irrelevant):
Without any parameter, the rule is the same as “certain all”. The rule can be specified only once for each combination of <condition> and <target>.
Ex:
check generic_aliasing (certain variable); search generic_aliasing (possible variable, type, subprogram, package);
Due to a limitation of ASIS for Gnat, AdaControl might not be able to
differentiate predefined operators of different types, and may thus
give false positives if a generic is instantiated with, for example,
two different functions that are actually "+" on Integer and
"+" on Float. This possibility of false positives is detected
by the rule “uncheckable”. See Uncheckable.
Next: Header_Comments, Previous: Generic_Aliasing, Up: Rules reference
This rule controls accesses to global elements that may be subject to race conditions, or otherwise shared.
<control_kind> global_references (<subrule> {, <root>});
<subrule> ::= all | read | written | multiple | multiple_non_atomic
<root> ::= <entity> | function | procedure | task | protected
This rule controls access to global variables from several entities
(the roots). The <entity> must be subprograms, task types,
single task objects, protected types, or single protected objects. As
usual, the whole syntax for entities is allowed for <entity>.
See Specifying an Ada entity name. The special keywords
function, procedure, task, and protected
are used to refer to all functions, procedures, tasks, and protected
entities, respectively.
The <subrule> determines the kind of references that are controlled:
atomic
or atomic_components and written from at most one of the
indicated entities are not reported. Note that this latter case
corresponds to a safe reader/writer use of atomic variables.
This rule follows the call graph, and therefore finds references from subprogram and protected calls made (directly or indirectly) from the indicated entities. However, calls to subprograms from the Ada standard library are not followed.
Ex:
-- Find global variables used by P1 or P2: search global_references (all, P1, P2); -- Find global variables modified by functions: check global_references (written, function); -- Find possible race conditions: check global_references (multiple, task, protected);
This rule can be given several times, and conflicts (with
multiple) are reported on a per-rule basis, i.e. given:
check global_references (multiple, P1, P2); check global_references (multiple, P1, P3);
the first rule will report on global variables shared between P1 and P2, and the second rule will report on global variables shared between P1 and P3.
The notion of “global” is relative, i.e. it designates every variable whose scope encloses (strictly) the indicated entities. This means that a same reference may or may not be global, depending on the indicated entity. Consider:
procedure Outer is
Inner_V : Integer;
procedure Inner_P is
begin
Inner_V := 1;
end Inner_P;
begin
Inner_P;
end Outer;
The rule
check global_references (all, outer);
will not report any global reference, while the rule
check global_references (all, outer.inner_p);
will report a reference to Inner_V. This is as it should be,
since there is no race condition if several tasks call Outer,
while there is a risk if several tasks (declared inside Outer)
call Inner_P.
Specifying:
check global_references (all, function);
will report on any function that access variables outside of their scope, i.e. all functions that have potential side effects. On the other hand, this check must follow the whole call graph for any function encountered, and can therefore be quite costly in execution time.
Calls through pointers to subprograms and dispatching calls are unknown statically; they are assumed to not access any global. Such calls are detected by the rule “uncheckable”. See Uncheckable.
Next: Improper_Initialization, Previous: Global_References, Up: Rules reference
This rule controls that every compilation unit starts with a standardized comment.
<control_kind> header_comments (minimum, <comment lines>); <control_kind> header_comments (model, "<file name>");
The first parameter is a subrule keyword:
'{', the line must have the following syntax:
{<min>,[<max>]}
where <min> and <max> specify the minimum and maximum number of occurrences of the pattern in the line that follows this one. <min> must be at least 0, and <max> must be at least 1, and be equal or greater than <min>. If <max> is omitted, it means that the line may occur any number of times.
As a convenience, if the first character of a line is a '*'
it means that the next line is a pattern that can occur any number of
times (same as {0,}). If the first character is a
'+', it means that the next line is a pattern that must occur
at least once (same as {1,}). If the first character is a
'?', it means that the next line is an optional pattern (same
as {0,1}).
Note that the repetition lines all start with a special character
which is not allowed at the start of a regular expression; there is
therefore no ambiguity. Everything after the special character (or the
closing '}') is ignored, and can be used to provide comments.
This rule can be given at most once with “minimum” for each of “check”, “search”, and “count”. The rule can be given only once with “model” (but it can be given together with one or more “minimum” rules).
Ex:
check header_comments (minimum, 10); search header_comments (model, "header.pat"); count header_comments (minimum, 20);
This makes an error for every unit that starts with less than 10
comment lines, and a warning for units that do not follow the pattern
contained in the file header.pat. A count of units that start
with less than 20 comment lines is reported.
Example of a pattern file:
{1,3} 1 to 3 occurrences of next line
^--$
^-- Author: .+$
^-- Date: \d{2}/\d{2}/\\d{4}$
Remember that the lines of the file are regular expressions; every
character that is specially interpreted (like “+”, “*”, etc.) must
be quoted with “\” if it must appear textually. To ease the process
of generating the model file, the directory source contains a
script file for sed named makepat.sed; if you run this script
on a file that contains a standard header, it will produce a pattern
file where each line starts with “^”, ends with “$”, and every
special character is quoted with “\”.
When the model contains an indication of repeated lines (“*”), the repetition is not “greedy”, i.e. matching will stop as soon as what follows the repetition matches. This is very useful to check header comments that have sections, but where you don’t want to impose a precise content to each section. Imagine for example that the structure is:
the following pattern will work as expected:
^-- HISTORY$ * ^-- ^-- AUTHORS * ^--
Since the “model” subrule analyzes the content of comments, there is a conflict with the disabling mechanism of AdaControl that uses special comments. See Disabling controls.
Specifically, line disabling is not possible at all. Block disabling is possible, provided the disabling line is allowed by the pattern. In short, if you want to be able to disable this rule, the first lines of the model file should be:
? --##
i.e. allow an optional block disabling comment as the first line of the file. Note that there is no need to re-enable this rule, since it is checked only at the start of a compilation unit.
Next: Instantiations, Previous: Header_Comments, Up: Rules reference
This rule enforces a coding pattern that ensures that variables and
out parameters are properly initialized befor use.
<control_kind> improper_initialization [(<subrule> {,<subrule>})]
<subrule> ::= {<extra>} <target>
<extra> ::= access | limited | package | return
<target> ::= out_parameter | variable | initialized_variable
This rule controls variables and/or out parameters that are
not “properly” initialized, i.e. those that are not “safely”
initialized, those that have a useless initialization in their
declaration, and those where the value is known to be used before
having been assigned. The notion of variable includes the return
object of an extended return statement (Ada 2005+).
A variable (or out parameter) is considered safely
initialized if there is an initialization expression in its
declaration, or if it is given a value in the first statements of the
corresponding body, before any “non-trivial” statement. The goal is
not to perform a complete data-flow analysis, but rather to follow a
design pattern where all variables are initialized before entering the
“active” part of the algorithm. This makes it easier to ensure that
variables are properly initialized.
“Trivial” statements are:
null statements;
if and case statements, unless they contain a
nested non-trivial statement.
The <target> parameters determines what is to be checked:
out_parameter controls that out parameters are
safely initialized before the first non-trivial statement, and before
every (trivial) return statement. Note that out
parameters are not checked before raise statements,
since the language does not guarantee that out parameters
are transmitted back in the case of exceptions.
variable controls that local variables are safely initialized
before the first non-trivial statement. If the <extra> modifier
return is specified, only return objects of extended return
statements are controlled.
initialized_variable controls variables that are safely
initialized before the first non-trivial statement, but also have an
explicit (and therefore useless) explicit initialization in their
declaration. If the modifier return is specified, only return
objects of extended return statements are controlled.
In all cases, variables used in trivial statements before being initialized are reported.
A variable is considered initialized if it is the target of an
assignment statement, or if it is used as an actual for an
out (but not in out) parameter of a procedure
call. Variables assigned in if or case
statements must receive a value in all paths to be considered
initialized after the statement. Note that the variable must be
assigned to globally, i.e. assigning to some elements of an array, or
some fields of a record, does not count as an initialization of the
variable.
Some variables are not controlled, unless the corresponding <extra> modifier is given:
This rule can be given only once for each value of <target>. Without parameters, it is equivalent to giving all, without any <extra>.
Ex:
check improper_initialization (out_parameter); check improper_initialization (access limited variable); search improper_initialization (initialized_variable);
variable and initialized_variable control also return
objects from extended return statements, since it would be strange to
guarantee safe initialization of local variables and not return
objects. On the other hand, the design pattern enforced by this rule
may seem to limitative for regular variables, but it might be
desirable to enforce it for return objects; hence the possibility to
limit the rule to return objects by specifying the return
modifier.
Due to a weakness of the ASIS standard, dispatching calls and calls to
procedures that are attributes are not considered for the
initialization of variables. Note that for attributes, only
'Read and 'Input have an out parameter.
In the rare case where a variable is initialized by a dispatching call or an attribute call, this limitation will result in a false positive. Such a case is detected by the rule “uncheckable”. See Uncheckable. It is then easy to disable the rule for this variable. See Disabling controls.
The rule analyzes only initializations and uses that are directly in the unit, not those from nested units, since these are in the general case not statically checkable.
There are other cases where an object is automatically initialized by
the declaration, like controlled types that have redefined the
Initialize procedure, records where all components have a
default initialization, etc. The rule does not consider these as
automatically initialized, as it does for access types. Maybe later...
Next: Insufficient_Parameters, Previous: Improper_Initialization, Up: Rules reference
This rule controls all instantiations of a generic, or only instantiations that are made with specific values of the parameters, including when the parameter has been already specified in a previous instantiation. Control can be restricted to instantiations in specified places.
<control_kind> instantiations (<generic_spec>);
<generic_spec> ::= {[not] <location_kw>} <entity> {, <formal_spec>}
<formal_spec> ::= <entity> | <category> | =
<location_kw> ::= all | block | library | local | nested |
own | private | public | in_generic | task_body
The rule controls instantiations of the specified <entity>. As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name.
The <location_kw> restricts the places where the occurrence of the instantiation is controlled. If it is preceded by “not”, the instantiation is controlled except at this location. Several <location_kw> can be given, in which case the instantiation is controlled at places where all the keywords apply. If there is no <location_kw>, it is assumed to be “all”.
all: puts no special restriction to the location. This keyword
can be specified for readability purposes, and if specified must
appear alone (not with other <location_kw>), and “not” is not
allowed.
block: only instantiations appearing in block statements are
controlled.
library: only library level instantiations are controlled.
local: only local instantiations are controlled (i.e. only
instantiations appearing in (generic) packages, possibly nested, are
allowed).
own: only instantiations that are local to a (generic) package
body are controlled.
public: only declarations appearing in the visible part of
(generic) packages are controlled.
private: only instantiations appearing directly in a private
part are controlled.
in_generic: only instantiations appearing directly or indirectly in a generic
specification or body are controlled.
task_body: only instantiations appearing directly in a task
body are controlled. Note that it would not make sense to have a
<location_kw> for task specifications, since instantiations are
not allowed there.
An instantiation matches if it appears at a specified location (if any) and either:
This subrule does not traverse derivations and privacy (the categories
“new” and “private” can be given, to check instantiantions with a
derived or a private type). A box (<>) can be given and
matches any actual parameter (i.e. it stands for any
value). See Definition of type categories.
In addition, an equal sign (=) matches if there has been
already an instantiation with the same value for this parameter
(i.e. it matches the second time it is encountered).
Formal in parameters cannot be given as <entity>, since the
actual can be any expression; therefore, the rule should specify a box
(<>) or equal (=) at the place of such parameters.
Ex:
-- Check all instantiations of Unchecked_Deallocation: search instantiations (ada.unchecked_deallocation); -- Check all instantiations of Unchecked_Conversion from or to String: check instantiations (ada.unchecked_conversion, standard.string); check instantiations (ada.unchecked_conversion, <>, standard.string); -- Check all instantiations of Unchecked_Conversion from address -- to an integer type: check instantiations (ada.unchecked_conversion, system.address, range); -- Check that Unchecked_Conversion is instantiated only once -- for any pair of arguments: check instantiations (ada.unchecked_conversion, =, =); -- No instantiation of Unchecked_Conversion on private types -- (Are these guys cheating with privacy?) check instantiations (ada.unchecked_conversion, private);
The rule provides a variable to choose whether a type name given as a parameter should match only itself or all of its subtypes.
| Variable | Values | Effect |
| Type_Matches_Subtype | off | A type names matches only itself. |
| on (default) | A type name matches itself and all of its subtypes. |
The various forms of <formal_spec> make the rule quite powerful. For example:
-- Not two instantiations of Gen with the same first parameter: check instantiations (Gen, =); -- Not two instantiations of Gen with same first and third parameters: check instantiations (Gen, =, <>, =); -- Not two instantiations of Gen with the same first parameter if the -- second parameter is Pack.Proc: check instantiations (Gen, =, Pack.Proc); -- Not two instantiations of Gen with the same first parameter if the -- second parameter is any procedure named Proc: check instantiations (Gen, =, all Proc);
Note that by default, a generic actual wich is a type matches all its subtypes. Therefore,
check instantiations (ada.unchecked_deallocation (standard.natural));
will find only instantiations that use Natural, while:
check instantiations (ada.unchecked_deallocation (standard.integer));
will find instantiations that use either Integer,
Positive, or Natural. If this is not desired, set the
“Type_Matches_Subtype” rule variable to “Off”.
Since the actual corresponding to a formal in
parameter can be any dynamic expression, if an equal sign (=)
is provided for such a parameter, only cases where it can be proven
statically that the value is identical to a previous one will be
reported.
GNAT defines Unchecked_Conversion and
Unchecked_Deallocation as separate entities, rather than
renamings of Ada.Unchecked_Conversion and
Ada.Unchecked_Deallocation. As a consequence, it is necessary
to specify explicitely both forms if you want to make sure that the
corresponding generics are not instantiated.
Next: Known_Exceptions, Previous: Instantiations, Up: Rules reference
This rule controls calls to subprograms and entries where the values of parameters does not provide sufficient information to the reader to correctly identify the parameter’s purpose.
<control_kind> insufficient_parameters (<max_allowed> {, <entity>});
<max_allowed> is the maximum number of allowed “insufficient” parameters (can be 0). The <entity> parameters designate enumeration types whose values should be included in the check. As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name.
An actual parameter is deemed "insufficient" if it is given in
positional (as opposed to named) notation, it is an expression whose
primaries are all numeric literals, or enumeration literals belonging
to one of the types passed as parameters to the rule
(Standard.Boolean for example).
This rule can be given once for each of check, search, and count. This way, it is possible to have a level considered a warning (search), and one considered an error (check).
Ex:
search Insufficient_Parameters (1, Standard.Boolean); check Insufficient_Parameters (2, Standard.Boolean);
This rule does not apply to operators that use infix notation, nor to calls to subprograms that are attributes, since named notation is not allowed for these.
This rule controls the use of positional parameters according to their
values; it is also possible to control the use of positional
parameters according to the number of parameters with the rule
positional_associations. See Positional_Associations.
Note also that this rules applies only to calls, while
positional_associations applies to all forms of associations.
Next: Local_Access, Previous: Insufficient_Parameters, Up: Rules reference
This rule controls a number of cases where it can be determined that a construct is certain to raise an exception.
<control_kind> known_exceptions [(<subrule> {,<subrule>})];
<subrule> ::= access | assignment | discriminant | index |
raise_expression | zero_divide
The parameters are subrule keywords:
null.
raise expressions that
appear anywhere else than as the right expression of a short-circuit
test (and then and or else), as a dependent
expression of an if expression or a case
expression, or as the expression of an expression function (the later
being assumed to be a function that raises the exception on purpose).
"/" operators where the right operand is
statically known to be zero.
Without parameters, all kinds of known exceptions are controlled.
This rule can be given at most once for each subrule.
Ex:
check Known_Exceptions (Assignment, Zero_Divide); search Known_Exceptions (raise_expression);
The following subrule generates fixes:
raise
expression appears as the right expression of an and or
or operator, the operator is changed to the corresponding
short-circuit operation (and then or or else,
respectively).
The error message indicates the failing value and the expected bound
(for the “assignment” and “index” subrules), or the failing
discriminant name (for the “discriminant” subrule). Note that if the
value is from an enumerated type (including character types), the
value given is the integer position value (i.e. the 'Pos).
A raise expression should not be evaluated unconditionally,
it is rather to be used as a default in cases where other conditions
are not met (and especially in pre/post conditions). The subrule is
especially useful to catch pre/post conditions of the form
“... or raise Constraint_Error” instead of
“... or else raise Constraint_Error”.
Next: Local_Hiding, Previous: Known_Exceptions, Up: Rules reference
This rule controls the taking of access values (through the 'Access,
'Unchecked_Access, or the GNAT specific 'Unrestricted_Access
attributes) of local (i.e. non global) entities.
<control_kind> local_access [(<subrule> {,<subrule>})];
<subrule> ::= constant | variable | procedure | function |
protected_procedure | protected_function
Without parameters, the rule controls all entities given as prefixes
of 'Access, 'Unchecked_Access, or
'Unrestricted_Access attributes and reports on those that are
not global, i.e. not defined in (possibly nested) library packages.
If parameters are specified, only entities belonging to the corresponding categories are controlled.
Ex:
Dangerous_Objects: check local_access (Constant, Variable);
In Ada 95, accessibility rules make sure that taking the
'Access of an entity cannot create dangling pointers, but this
check can be circumvented by using 'Unchecked_Access (but not
on subprograms), or in GNAT, by using
'Unrestricted_Access. Moreover, Ada 2005 generalized anonymous
access types create more cases where accessibility levels are
dynamically checked.
Taking an access value on a global entity is never a risk, but every use of access values designating local entities has a potential of a failing dynamic accessibility check or even of a dangling pointer. This rule is helpful in finding the places that need careful inspection - or for disallowing taking accesses on anything but global entities.
Next: Max_Blank_Lines, Previous: Local_Access, Up: Rules reference
This rule controls declarations that hide an outer declaration with the same name.
<control_kind> local_hiding [(<subrule> {,"<allowed pattern>"})];
<subrule> ::= {<exception>} strict | overloading
<exception> ::= not_operator | not_enumeration |
not_identical_renaming | not_different_families
The first parameter is a subrule keyword:
Without parameters, the rule defaults to “strict”.
Modifiers are used to exclude some controls (i.e. to allow the corresponding hiding):
"+"”).
If one or more <allowed pattern> are given, hiding (or overloading) of identifiers that match one of the patterns are not reported. The whole syntax for regular expressions is allowed for the pattern, but the matching is always case insensitive. See Syntax of regular expressions.
This rule can be given only once for “strict” and once for “overloading”.
Ex:
Hiding: check local_hiding (strict); Overloading: search local_hiding (not_operator overloading);
The rule provides a variable to adjust the verbosity of messages for the subrule “overloading” when it encounters a construct that overloads several other constructs.
| Variable | Values | Effect |
| Overloading_Report | compact | Issue a single message mentionning how many constructs are overloaded, and a pointer to the last one. |
| detailed (default) | Issue a message for each overloaded construct. |
If you have a naming convention like having all tagged types named
“instance” (with a meaningful name for the enclosing package), and
if in addition your package structure follows the inheritance
hierarchy (i.e. a descendent class is in a child package), then all
“instance” will hide each other - but this is of course
intended. Specifying “^instance$” as an allowed pattern will
prevent error messages for these declarations.
Note that the name is given between “^” and
“$”. Otherwise, following normal regexp syntax, any
identifier containing “instance” would be allowed.
A confusion between names belonging to different “families” (as defined here) always leads to a compilation error; it may be acceptable to allow local hiding of names belonging to different families, since there is no risk involved.
Next: Max_Call_Depth, Previous: Local_Hiding, Up: Rules reference
This rule controls excessive spacing in the program text.
<control_kind> max_blank_lines (<max allowed blank lines>);
This rule controls the occurrence of more than the indicated number of consecutive blank lines (empty lines, or lines that contain only spaces). This rule can be given once for each of check, search, and count. This way, it is possible to have a number of blank lines considered a warning (search), and one considered an error (check). Of course, this makes sense only if the number for search is less than the one for check.
Ex:
search max_blank_lines (2); check max_blank_lines (5);
This rule generates fixes:
Next: Max_Expression_Items, Previous: Max_Blank_Lines, Up: Rules reference
This rule controls the maximum depth of subprograms (or entry) calls.
<control_kind> max_call_depth (<allowed depth> | finite {, <entity>});
Roughly speaking, the call depth is the number of frames that are stacked by a call: if you call a subprogram that calls another subprogram that calls nothing, then the call depth is 2. Note that a call to a task entry (not a protected entry) has always a depth of 1, since the accept body that corresponds to the entry is executed on a different stack.
The value of the first parameter is the maximum allowed depth, i.e. the rule will trigger if the call depth is strictly greater than the indicated value. A call to a (directly or indirectly) recursive procedure is considered of infinite depth, and will be therefore signaled (with an appropriate message) for any value of <allowed depth>. Alternatively, the keyword “finite” can be given in place of the <allowed depth>: in this case, only calls to recursive subprograms will be signalled.
If entity names are given after the first parameter, they are interpreted as callable entities that are not to be analyzed, and assumed of depth 0 (not calling anything else). As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name. This can be useful, for example, when a subprogram appears to be recursive (but is not, due to the algorithm), to prevent all those who call it to be flagged as having infinite call depth.
This rule can be given once for each of check, search, and count. This way, it is possible to have a call depth considered a warning (search), and one considered an error (check). Of course, this makes sense only if the number for search is less than the one for check.
Ex:
search max_call_depth (9); check max_call_depth (finite);
The rule provides a variable to specify how to handle expression functions (Ada 2012).
| Variable | Values | Effect |
| Count_Expr_Fun_Calls | off | Calls to expression functions are assumed to be inlined and do not add an extra depth level. |
| on (default) | Calls to expression functions are counted like regular calls. |
It is possible to give the value 0 for <allowed depth>. Of course, it would not make sense to forbid all subprogram calls in an Ada program, but this can be useful for inspection purposes, since every call will be reported, and the message indicates the depth of the call.
If the message says that the call depth “is N”, it is exactly N. If the message says that the call depth is “at least N”, it means that the call chain includes a call to a subprogram whose depth is unknown (see “Limitations” below); “N” is the call depth if this subprogram does not call anything else. Of course, the rule issues a message if this minimal value is greater than the maximum allowed value.
There is only one set of entities that are forced to depth 0; therefore, if the control is given several times, each with various <entity>, all controls will use the union of all entities given.
Calls to subprograms that are attributes are assumed to have a depth of 1. Calls to predefined operators are assumed to be in-lined (i.e. a depth of 0).
Calls through pointers to subprograms and dispatching calls are unknown statically; in addition, some subprograms may not have a body available for analysis, like imported subprograms, or possibly subprograms from the standard library; they are all assumed to have a depth of 1. Such calls are detected by the rule “uncheckable”. See Uncheckable.
Next: Max_Line_Length, Previous: Max_Call_Depth, Up: Rules reference
This rule controls expressions that have too many elements and are therefore too complex.
<control_kind> max_expression_items (<max_allowed_primaries>);
This rule controls the complexity of expression, as defined by the number of primaries (i.e. simple elements connected by operators, including short circuit operations). The indicated value is the maximum allowed value, i.e. the rule will trigger if that value is exceeded.
More precisely, for the purpose of evaluating the complexity of an
expression, every simple element counts for 1. A parenthesized
expression is not counted (it is counted for the value of the
expression within the parentheses). True (not operators) function
calls, aggregates, if and case expressions,
predicates (for all, for some), etc. are counted
for 1, but every subexpression within them is rechecked.
This rule can be given once for each of check, search, and count. This way, it is possible to have a complexity considered a warning (search), and one considered an error (check). Of course, this makes sense only if the complexity for search is less than the one for check.
Ex:
search max_expression_items (10); check max_expression_items (20);
Next: Max_Nesting, Previous: Max_Expression_Items, Up: Rules reference
This rule controls that no line exceeds a given length.
<control_kind> max_line_length (<max allowed length>);
This rule controls the maximum length of source lines. This rule can be given once for each of check, search, and count. This way, it is possible to have a length considered a warning (search), and one considered an error (check). Of course, this makes sense only if the length for search is less than the one for check.
Ex:
search max_line_length (80); check max_line_length (120);
Next: Max_Primitives, Previous: Max_Line_Length, Up: Rules reference
This rule controls excessive nesting of declarations.
<control_kind> max_nesting ([<subrule>,] <max allowed depth>); <subrule> ::= all | generic | separate | task
The first parameter is a subrule keyword:
loop, case) is not
considered.
Without parameters, the rule defaults to “all”. This rule can be given once for each subrule and each of check, search, and count. This way, it is possible to have a level considered a warning (search), and one considered an error (check). Of course, this makes sense only if the level for search is less than the one for check.
Note that the value given is the maximum allowed nesting; f.e. if the value given for “generic” is 1, it means that a generic inside a generic is allowed, but not more.
Ex:
search max_nesting (5); check max_nesting (all, 7); check max_nesting (generic, 1); check max_nesting (separate, 0); -- Do not allow separate in separate check max_nesting (task, 0); -- Do not allow a task in another task
Next: Max_Size, Previous: Max_Nesting, Up: Rules reference
This rule controls the number of primitive operations of a type.
<control_kind> max_primitives (<subrule>, [<target>] <value>); <subrule> ::= visible | total <target> ::= tagged | untagged
The first parameter is a subrule:
If “tagged” is given before <value>, <value> applies only to tagged types, including tasks and protected types that implement interfaces. If “untagged” is given before <value>, <value> applies only to regular (untagged) types. If no modifier is given, <value> applies to both.
This rule can be given once for each subrule, each <target>, and each of check, search, and count. This way, it is possible to have a level considered a warning (search), and one considered an error (check). Of course, this makes sense only if the level for search is less than the one for check.
Note that the value given is the maximum allowed primitives.
Ex:
count max_primitives (total, 2); search max_primitives (visible, 3); check max_primitives (visible, tagged 5); check max_primitives (visible, untagged 4);
Next: Max_Statement_Nesting, Previous: Max_Primitives, Up: Rules reference
This rule controls the maximum size, in source lines of code, of various statements and declarations.
<control_kind> max_size (<subrule>, <max allowed lines>);
<subrule> ::= accept | block | case | case_branch |
if | if_branch | loop | simple_block |
unnamed_block | unnamed_loop |
package_spec | package_body | procedure_body |
function_body | protected_spec | protected_body |
entry_body | task_spec | task_body |
unit
The first parameter is a subrule keyword:
declare part
if (respectively case)
statement.
For each kind of element, the indicated value is the maximum allowed
size of the full element; however, for branches (“if_branch” and
“case_branch”) it is the maximum size of the sequence of statements
in the branch (i.e., the line that contains the elsif is
not counted as part of an “if_branch”).
This rule can be given once for each of check, search, and count for each kind of element. This way, it is possible to have a level considered a warning (search), and one considered an error (check). Of course, this makes sense only if the number of lines for search is less than the one for check.
Ex:
check Max_Size (if_branch, 30); search Max_Size (if_branch, 50); check Max_Size (unnamed_loop, 20);
Note that “procedure_body” and “function_body” apply to protected subprograms as well as regular ones, and that there is no subrule for the length of the declaration of subprograms. Such fine specifications didn’t seem useful, but could be added if someone expresses a need for it.
Next: Movable_Accept_Statements, Previous: Max_Size, Up: Rules reference
This rule controls the nesting of compound statements.
<control_kind> max_statement_nesting (<subrule>, <max allowed depth>); <subrule> ::= block | case | if | loop | all
The first parameter is a subrule keyword:
if within a loop within an if counts
only 2 for the “if” keyword.
if within a loop within an if
counts for 3.
This rule can be given once for each of check, search, and count, and for each of the subrules. This way, it is possible to have a level considered a warning (search), and one considered an error(check). Of course, this makes sense only if the level for search is less than the one for check.
Ex:
check max_statement_nesting (loop, 3); search max_statement_nesting (all, 5);
Next: Naming_Convention, Previous: Max_Statement_Nesting, Up: Rules reference
This rule controls statements that are inside accept statements and could safely be moved outside.
<control_kind> movable_accept_statements (certain|possible {, <entity>})
Since it is good practice to block a client for the shortest time possible, any action that does not depend on the accept parameters should not be part of an accept statement.
Statements that involve synchronisation (delay statements, accept or entry calls...) are not movable. Statements (including compound statements) that reference the parameters of the enclosing accept are not movable. In addition, statements that use one of the <entity> given as parameters are never considered movable. As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name. Note that if a generic entity, or an entity declared in a generic package, is given, all statements that use the corresponding instantiated entity are considered not movable.
If the first parameter of the rule is certain, only statements
after the last non-movable statement are reported. If the first
parameter is possible, a simple data flow analysis is
performed, and every statement that does not reference a variable that
appears to depend (directly or indirectly) on a parameter is also
reported.
Ex:
check movable_accept_statements (possible, Log.Report_Rendezvous);
The list of <entity> given to the rule can be, for example, procedures whose execution must be part of the accept statement for logical reasons. They can also be global variables, when the rendezvous is intended to prevent concurrent access to these variables.
Next: No_Operator_Usage, Previous: Movable_Accept_Statements, Up: Rules reference
This rule controls the form of identifiers to make sure that they follow the project’s naming conventions. Different naming conventions can be specified, depending on the kind of Ada entity that the name is refering to.
<control_kind> naming_convention
([root] [others] {<location>} [<type_spec>] <filter_kind>,
[case_sensitive|case_insensitive] [not] "<pattern>" |
file "<pattern_file>"
{, ...});
<location> ::= global | local | unit
<type_spec> ::= <entity> | {<category>}
<filter_kind> ::= All |
Type |
Discrete_Type |
Enumeration_Type |
Integer_Type |
Signed_Integer_Type |
Modular_Integer_Type |
Floating_Point_Type |
Fixed_Point_Type |
Binary_Fixed_Point_Type |
Decimal_Fixed_Point_Type |
Array_Type |
Record_Type |
Regular_Record_Type |
Tagged_Type |
Interface_Type |
Class_Type |
Access_Type |
Access_To_Regular_Type |
Access_To_Tagged_Type |
Access_To_Class_Type |
Access_To_SP_Type |
Access_To_Task_Type |
Access_To_Protected_Type |
Private_Type |
Private_Extension |
Generic_Formal_Type |
Variable |
Regular_Variable |
Field |
Discriminant |
Record_Field |
Protected_Field |
Procedure_Formal_Out |
Procedure_Formal_In_Out |
Generic_Formal_In_Out |
Constant |
Regular_Constant |
Regular_Static_Constant |
Regular_Nonstatic_Constant |
Named_Number |
Integer_Number |
Real_Number |
Enumeration |
Sp_Formal_In |
Generic_Formal_In |
Loop_Control |
Occurrence_Name |
Entry_Index |
Label |
Stmt_Name |
Loop_Name |
Block_Name |
Subprogram |
Procedure |
Regular_Procedure |
Protected_Procedure |
Generic_Formal_Procedure |
Function |
Regular_Function |
Protected_Function |
Generic_Formal_Function |
Entry |
Task_Entry |
Protected_Entry |
Package |
Regular_Package |
Generic_Formal_Package |
Task |
Task_Type |
Task_Object |
Protected |
Protected_Type |
Protected_Object |
Exception |
Generic |
Generic_Package |
Generic_Sp |
Generic_Procedure |
Generic_Function |
Renaming |
Object_Renaming |
Exception_Renaming |
Package_Renaming |
Subprogram_Renaming |
Procedure_Renaming |
Function_Renaming |
Generic_Renaming |
Generic_Package_Renaming |
Generic_Sp_Renaming |
Generic_Procedure_Renaming |
Generic_Function_Renaming
The first parameter defines the kind of declaration to which the rule is applicable, and other parameters are strings, interpreted as regular expressions that define the patterns that must be matched (or not). See Syntax of regular expressions. If the string is preceded by the keyword “file”, it is interpreted as a file name containing the patterns. See Syntax of pattern files below for details.
If one or more <location> keyword is specified, the pattern applies only to identifiers declared at the corresponding place. Otherwise, the pattern applies to all identifiers, irrespectively of where they are declared. The definition of locations is as follows:
In the case of objects (corresponding to filters in the “variable” and “constant” families) and functions (in the “function” family), it is possible to be more specific, depending on the type of the object (or the return type of the function), as specified by the <type_spec> modifier. The <type_spec> modifier is either a single <entity> giving the type of the object or one or more <category>. As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name.
The rule traverses derivations, but not privacy (the category “private” can be given, to check objects or functions of a private type). See Definition of type categories.
For a given layer of the hierarchy (i.e. “variable”, “regular_variable”), only the most specific filter is applicable, i.e. “standard.boolean variable” will apply to all boolean variables, while plain “variable” will apply to other variables. See examples below.
If “case_sensitive” is specified, pattern matching considers casing. Otherwise (“case_insensitive”), casing is irrelevant. The default is “case_insensitive”, and can be changed by setting the rule variable “Default_Case_Sensitivity”, see below. Note that the rule checks the name only at the place where it is declared; casing might be different when the name is used later.
If a pattern is preceded by “not”, then the pattern must not be matched (i.e. the rule reports when there is a match).
The rule will be activated if an identifier is declared that does not match any of the “positive” patterns (the ones without “not”), or if it matches any of the ”negative” patterns (the ones with a “not”). If only negative patterns are given, it is implicitely assumed that all other identifiers are OK. In other words, accepted identifiers must have the form of (at least) one of the “positive” patterns (if any), but not the form of one of the “negative” patterns.
The filter kinds are organized hierarchically, as reflected by indentation in the syntax above. To be valid, the name must match the patterns specified for its own filter, and for all filters above it in the hierarchy. For example, a modular type declaration must follow the rules (if specified) for “all”, “type”,”discrete_type”, “integer_type” and “modular_integer_type”. However, if a filter kind is preceded by “others”, the rule will apply only if there is no applicable positive pattern deeper in the hierarchy; similarly, if a filter kind is preceded by “root”, no rule above it in the hierarchy is considered (neither for itself nor its children). This is useful to make exceptions to a more general rule. For example:
-- All identifiers must have at least 3 characters: check naming_convention (all, "..."); -- And start with an upper-case letter -- (will not apply to types and access types, because of "others" and -- other rules given below) check naming_convention (others all, case_sensitive "^[A-Z]"); -- Exception to the rule for "all": -- No minimum length for "for loop" identifiers, but must be -- all uppercase check naming_convention (root loop_control, case_sensitive "^[A-Z]+$"); -- Types must start with "t", then an upper-case letter: -- (will not apply to access types, because of "others" and -- other rule given below) check naming_convention (others type, case_sensitive "^t[A-Z]"); -- Access types must start with "ta", then an upper-case letter: check naming_convention (access_type, case_sensitive "^ta[A-Z]"); -- Boolean variables, and only these, must start with "Is_" or -- "Has_": check naming_convention (variable, not "^Is_", not "^Has_"); check naming_convention (standard.boolean variable, "^Is_", "^Has_"); -- Functions returning Wide_String must start with "Wide_", and -- similarly for Wide_Wide_String, and no other: check naming_convention (standard.wide_string function, "^Wide_", not "^Wide_Wide_"); check naming_convention (standard.wide_wide_string function, "^Wide_Wide_"); check naming_convention (function, not "^Wide_");
It is of course not necessary to specify all the filter kinds, nor to specify filters down to the deepest level; if you specify a rule for “type”, it will be applied to all type declarations, whether there is a more specific rule or not.
Subtypes and derived types must follow the rule for their respective original (full) type. Incomplete type declarations are not checked, since their corresponding full declaration is (normally) checked. Private types (including of course the full declaration of a private type) follow the rule for private types, not the rules for their full type view (otherwise it would be privacy breaking).
Renamings are treated specially: if there is no explicit rule for a given renaming, the applicable rule is the one for the renamed entity.
Ex:
-- Predefined name is forbidden:
check naming_convention (all, not "Integer");
-- Types must either start or end with T
check naming_convention (type, case_sensitive "^T_",
case_sensitive "_T$");
-- "Upper_Initials" naming convention:
check naming_convention
(all, case_sensitive "^[A-Z][a-z0-9]*(_[A-Z0-9][a-z0-9]*)*$");
-- All global variables must start with "G_"
check naming_convention (global variable, "G_");
A set of patterns corresponding to a given control can be given in a file.
The syntax is the same as for regular patterns, and the patterns must be given
as strings (enclosed in double quotes (")).
As a matter of simplification, if a pattern does not contain any wildcard character, it can be given as an identifier (without quotes): in this case, it matches only the corresponding identifier as a whole.
Example:
"abc" -- A pattern string, matches any identifier containing "abc"
abc -- An identifier, matches any identifier which is exactly
-- "abc" (same as "^abc$")
It is possible to put several pattern strings or identifiers on the same line,
separated by spaces or tabs. The file can contain Ada-like comments (starting with
‘--”, up to the end of line).
This rule generate fixes to help in refactoring the improper name. The
fix is ignored by adactl_fix, since automatic fixing is not
possible. Under GPS (interactive fixing) the “fix” icon launches the
“rename entity” dialog, allowing to give a proper name to the
entity, and changing all occurrences.
The rule provides a variable to specify the default casing.
| Variable | Values | Effect |
| Default_Case_Sensitivity | off (default) | controls that do not explicitely specify case sensitivity are not case sensitive. |
| on | controls that do not explicitely specify case sensitivity are case sensitive. |
The rule only checks the casing of identifiers at the place where they are declared. A useful companion rule is “style (casing_identifier, original)”, which ensures that every use of the identifier will use the same casing as in the declaration. See Style. Similarly, in the case of a subprogram and its parameters, the check is not done on the body if there is an explicit specification (since specification and body have to match anyway).
The rule does not check the names of operators, since it would make little sense to have naming conventions for things whose name is imposed. If you want to prevent the definition of operators, refer to the rule “declarations” and its subrules “operator”, “equality_operator”, and“predefined_operator”. See Declarations.
Remember that a Regexp matches if the pattern matches any part of the identifier. Use “^” and “$” to match the beginning (resp. end) of the name, or both.
A constant is considered static for the purpose of “Regular_Static_Constant” and “Regular_Nonstatic_Constant” if it is of a discrete type initialized by a static expression, or if it is an aggregate whose components all have static values. Staticness here is defined as “RM_Static” (see Rules reference). This is different from the official definition of “static” in the language, but corresponds to what most users would expect.
“class_type” is applicable to subtypes that designate a class-wide type. Similarly, “access_to_class_type” is applicable to access types whose designated type is class-wide.
If you don’t want any special rule for renamings (not even the one that applies to the renamed entity), specify:
check naming_convention (renaming, "");
This imposes no constraint on renamings, but since it is specified explicitely, the implicit rule for the renamed entity won’t apply.
The rules directory of Adacontrol contains two files named
no_standard_entity.aru and no_system_entity.aru. These
are files that contain a naming_convention rule that forbids the
declaration of names declared in packages Standard and System,
respectively. You can simply “source” these files from your own rule
file (or copy the content) if you want to disallow these identifiers.
Like usual, naming_convention rule can be given multiple times, and can be disabled. However, consider the following:
Rule1 : check naming_convention (constant, "^c_"); Rule2 : check naming_convention (constant, "^const_");
The rule will trigger if a constant is declared that does not start with either “c_” or “const_”. But here, we have two different rule labels. The message will refer to the first label encountered in the command file; this is the label that must be mentionned in a disabling comment, unless you simply disable “naming_convention”.
A gnatcheck dictionary file for “name_clashes” is compatible and corresponds to the following control:
check naming_convention (all, not file "gnat_check_dictionary.txt");
This rule does not support wide characters outside the basic Latin-1 set.
Next: Non_Static, Previous: Naming_Convention, Up: Rules reference
This rule controls integer types that do not use any arithmetic operators, which indicates that they might be replaceable with other kinds of types.
<control_kind> no_operator_usage [([<category>] <parameter>
[,<parameter>])];
<parameter> ::= [<filter>] <observed>
<filter> ::= not | ignore | report
<observed> ::= relational | logical | indexing
This rule controls integer types where no arithmetic operator of the
type is used in the program. If the <category> is range, the
control applies only to signed integer types; if it is mod, it
applies only to modular integer types; without <category>, it applies
to both. No other <category> is allowed. The rule traverses
derivations and privacy (the rule applies also to private types whose
full declaration is an integer type). See Definition of type categories.
When such a type is found, it migh be interesting to find out other
usages to determine a possible better kind of type. “relational”
means that relational operators (<, <=, >,
>=, in, not in) are used, “logical”
means that logical operators (and, or,
xor) are used, and “indexing” means that the type is
used as an index in some array type.
If an <observed> property is given as parameter, only types that feature the property are controlled, or those that do not feature the property if the <observed> is preceded by “not”. If the <observed> is preceded by “ignore” the type is controlled irrrespectively of the property, and the message does not mention it at all, while if it is preceded by “report”, the message still mentions whether the <observed> is used or not.
Without parameters, the rule is equivalent to “ignore relational, ignore logical, ignore indexing” (i.e. it controls all types that do not use any arithmetic operator).
This rule can be given only once for each combination of values of the parameters.
Ex:
-- Simply report types that don't use arithmetic operators: check no_operator_usage; -- Do the same, but mention if indexing/logical ops are used: check no_operator_usage (report indexing, report logical); -- Find modular integer types that use only logical operators: check no_operator_usage (mod logical); -- Find integer types that don't use artihmetic operators and are -- not used for indexing nor in relational operators: check no_operator_usage (not indexing, not relational);
An integer type that uses no operator at all is a good candidate to be replaced by an enumerated type. A modular type where only logical operators are used is likely to be used as a bit field or a set, and is a good candidate for being replaced by an array of booleans.
The rule does not make a distinction between predefined and user-defined operators. On the other hand, only calls to operators are considered, operators used for example as actual generic parameters in instantiations are not considered.
Next: Not_Elaboration_Calls, Previous: No_Operator_Usage, Up: Rules reference
This rule controls that expressions used in certain contexts are static.
<control_kind> non_static [(<subrule> {, <subrule>})];
<subrule> ::= constant_initialization | variable_initialization |
index_constraint | discriminant_constraint |
instantiation | index_check
Since this rule is generally used for making sure that some elements are “hard coded”, or of a known size, by default staticness for all checks is “RM_Static”. However, a rule variable allows to use the more general notion of “statically provable”. See Rules reference.
The parameters are subrule keywords that define the elements that are required to be static:
If no keyword is given, all contexts are controlled.
Ex:
check non_static (index_constraint);
The rule provides a variable to select the definition of staticness as defined in the reference manual, or more generally as statically provable.
| Variable | Values | Effect |
| RM_Static | off | Staticness is defined as statically provable. |
| on (default) | Staticness is defined in accordance with the Ada Reference Manual. |
Currently, “constant_initialization” and “variable_initialization”
do not control structured (record and array) variables. For access
variables, the initial value is considered static only if it is a plain
null. This may improve in future versions of AdaControl.
If all index and discriminant constraints are static, the space occupied by data structures is computable from the program text. This rule is useful to enforce this in contexts where the memory space must be statically determined.
Next: Not_Selected_Name, Previous: Non_Static, Up: Rules reference
This rule controls that certain subprograms (or allocators) are called only during program initialization.
<control_kind> not_elaboration_calls (<entity>|new {, <entity>|new});
The <entity> parameters are callable entities (procedure, function or entry calls). As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name. This rule controls calls to the indicated callable entities, or allocators if “new” is given, that are performed at any time except during the elaboration of library packages.
If <entity> is the name of a generic procedure or function, then calls to all instances are controlled.
Ex:
search not_elaboration_calls (Data.Initialize, new);
Note that renamings are followed: if <entity> has been renamed, it will be found under all its various names; on the other hand, if <entity> is the name of a renaming declaration, the rule will only apply to this name, not to the entity that has been renamed.
Due to an (allowed by ASIS standard) limitation of ASIS-for-Gnat, the
rule will not detect calls to subprograms that are implicitely
defined, like calling a "+" on Integer. Fortunately,
it is very unlikely that the user would want to forbid that kind of
calls in non-elaboration code.
Note also that calls that cannot be statically determined, like calls to dispatching operations or calls through pointers to subprograms cannot be detected either.
Next: Object_Declarations, Previous: Not_Elaboration_Calls, Up: Rules reference
This rule controls that certain entities are always refered to using
selected notation, even in the presence of use clauses.
<control_kind> not_selected_name
(<exception places>, <entity> {, <entity>});
<exception places> ::= none | unit | compilation | family
A name is “selected” if it is prefixed by the name of the construct where it is declared. Only one level of prefix is required, unless the prefix itself is the target of a not_selected_name rule.
The first parameter specifies places where the rule is not enforced, i.e. where simple notation is allowed:
Other parameters indicate the <entity> to which the rule applies. As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name.
Ex:
check not_selected_name (unit, all Instance); search not_selected_name (none, Pack.T);
This rule generates fixes:
Note that, as usual, the entity can be given in the form “all
name”. This is especially useful for types that must always be
declared with a special name (like Instance, Object,
T) and are intended to be always used with the name of the
enclosing package.
Next: Parameter_Aliasing, Previous: Not_Selected_Name, Up: Rules reference
This rule controls various aspects of object (constants and variables) declarations.
<control_kind> object_declarations (min_integer_span, <min_spec>
{, <min_spec>});
<control_kind> object_declarations (type, <type_spec> {, <type_spec>});
<control_Kind> object_declarations (not_required_type, <type_spec>
{, <type_spec>});
<control_kind> object_declarations (volatile_no_address);
<control_kind> object_declarations (address_not_volatile);
<min_spec> ::= [constant | variable] <value>
<type_spec> ::= [constant | variable] <entity>
The first parameter is a subrule keyword:
This subrule can be given only once for each combination of <control_kind> and “constant”/”variable”.
This subrule can be given only once for each combination of <entity> and “constant”/”variable”.
for loop parameters. The control can be
restricted to only constants or only other kinds of objects
(i.e. “variable” applies to all objects that are not constants); if
no modifier (“constant” or “variable”) is supplied, both are
controlled.
An object is required to be of a type if:
for loop, and the loop index
is required to be of the type.
An expression (or subexpression) requires a type if it includes only:
'First or 'Last attribute references with a prefix of an
array type;
This subrule can be given only once for each combination of <entity> and “constant”/”variable”.
Since this subrule has no parameters, it can be given only once.
Since this subrule has no parameters, it can be given only once.
Ex:
check object_declarations (min_integer_span, variable 5, constant 10); count object_declarations (min_integer_span, 8); -- Same value for variables and constants search object_declarations (volatile_no_address); search object_declarations (address_not_volatile);
The “min_integer_span” subrule can be useful for detecting variables that should use an enumerated type rather than an integer type.
The “not_required_type” is instrumental when a coding standard
prohibits the use of predefined types, except when it cannot be
avoided. Typically, when the use of type Integer is allowed
only for indexing String or for calling language defined
subprograms. Subexpressions allow only predefined operators, because
user defined operators could avoid the use of predefined
types. However, computations involving the 'First or
'Last attributes are often unavoidable in string manipulations.
Due to a shortcomming of the ASIS interface, the subrules “volatile_no_address” and “address_not_volatile” will not detect variables of a class-wide type that are volatile due to a pragma volatile applying to the class-wide type. If the pragma applies to the variable, the subrule will work correctly. A pragma volatile applied to a class-wide type is detected by the rule “uncheckable”. See Uncheckable.
Declaring a class-wide type as volatile seems very peculiar anyway...
Next: Parameter_Declarations, Previous: Object_Declarations, Up: Rules reference
This rule controls aliased use of variables in subprogram calls.
<control_kind> parameter_aliasing [([with_in] <level>)]; <level> ::= Certain | Possible | Unlikely
This rule identifies calls (including function calls) where the same
variable is given as an actual to more than one out or
in out parameter, like in the following example:
procedure Proc (X, Y : out Integer); ... Proc (X => V, Y => V);
If the modifier “with_in” is given, aliasing between
out or in out parameters and in
parameters is also considered (unless the in parameter is
of a user-defined by-copy type). Although aliasing of in
parameters is generally considered less of an issue, it can lead to
unexpected results when the parameter is passed by reference.
There are many cases where aliasing cannot be determined statically. The optional parameter specifies how aggressively the rule will check for possible aliasings. Possible values are (case irrelevant):
Swap (Tab (I), Tab (J));
there is no aliasing, unless I equals J.
If all expressions used for indexing in both variables are static, the rule will be able to eliminate the diagnosis of aliasing (if the values are different). This avoids unnecessary messages in cases like:
Swap (Tab (1), Tab (2));
type R is
record
X : aliased Integer;
end record;
X : R;
Y : Access_All_Integer := R.X'access;
...
P (X, Y.all);
There will be no false positive with “Certain”. There will be no false negative with “Unlikely” (but many false positives). “Possible” is somewhere in-between.
The rule may be specified at most once for each value of the parameter. This allows for example to “check” for “Certain” and “search” for “Possible”.
Ex:
check parameter_aliasing (with_in certain); search parameter_aliasing (Possible);
Note that the rule is quite clever: it will consider partial aliasing (like a record variable as one parameter, and one of its components as another parameter), and will not be fooled by renamings.
Due to a weakness of the ASIS standard, dispatching calls are not analyzed. Some calls cannot obviously have aliasing (if there is only one parameter, or if there are no variables in the parameters f.e.); other calls are detected by the rule “uncheckable”. See Uncheckable.
Next: Positional_Associations, Previous: Parameter_Aliasing, Up: Rules reference
This rule controls various characteristics of the declaration of parameters for all callable entities (i.e. functions, procedures and entries).
<control_kind> parameter_declarations ([no_inout] <subrule>
[,<bounds>] {,<callable>});
<subrule> ::= all_parameters | in_parameters |
defaulted_parameters | out_parameters |
in_out_parameters | access_parameters |
tagged_parameters | class_wide_parameters |
single_out_parameter
<bounds> ::= min|max <value> [, min|max <value> ]
<callable> ::= function | procedure |
dispatching_function | dispatching_procedure |
protected_function | protected_procedure |
protected_entry | task_entry
The first parameter is a subrule keyword. “single_out_parameter” has no bounds and is the only subrule that allows “no_inout”; all other subrules require one or two bounds.
in,
out, or in out respectively.
out parameter. if “no_inout” is specified, the rule
does not report a single out parameter if there is also at
least one in out parameter.
If one or more <callable_kind> is specified after the <value>, the rule applies only to the corresponding declaration(s), otherwise it applies to all callable entities. “dispatching_function” and “dispatching_procedure” allow different counts for dispatching subprograms (i.e. primitive subprograms of a tagged type). If “dispatching_function” or “dispatching_procedure” is not explicitely specified, “function” (conversely “procedure”) applies also to dispatching functions (conversely dispatching procedures).
This rule can be given once for each of check, search, and count for each subrule and each kind of entity. This way, it is possible to have a level considered a warning (search), and one considered an error (check).
Ex:
-- Callable entities should preferably not have more than 5
-- parameters, and in any case not have more that 10 parameters,
check parameter_declarations (all_parameters, max 10);
search parameter_declarations (all_parameters, max 5);
-- All functions must have parameters and no out or in out
-- parameters (allowed in Ada 2012):
check parameter_declarations (all_parameters, min 1, function);
check parameter_declarations (out_parameters, max 0, function);
check parameter_declarations (in_out_parameters, max 0, function);
-- A regular (not protected) procedure with one out parameter
-- should be replaced by a function
check parameter_declarations (single_out_parameter, procedure);
-- Find all callable entities with class-wide parameters:
search parameter_declarations (class_wide_parameters, max 0);
-- Dispatching operations may have only one parameter of a tagged type:
check parameter_declarations (tagged_parameter,
max 1,
dispatching_function,
dispatching_procedure);
Procedures with a single out parameter are candidates
to becoming functions. Whether this applies also to procedures with
in out parameters is debatable, now that
functions can have in out parameters...
This rule applies to generic subprograms as well as to regular ones. On the other hand, it does not apply to generic formal subprograms, since instantiations would only be possible with subprograms which are supposed to have been already controlled.
Instantiations are also controlled; the number of parameters is taken from the corresponding generic.
Note that this rule controls only “regular” parameters, not generic formal parameters.
Note that dispatching operations have necessarily at least one tagged parameter, although a “max 0” could be specified in the example above. If you do this, all declarations of dispatching subprograms will be controlled. Maybe that’s what you want...
Next: Potentially_Blocking_Operations, Previous: Parameter_Declarations, Up: Rules reference
This rule controls the use of positional associations (as opposed to named associations) in all kinds of associations.
<control_kind> positional_associations
[(<subrule>, <max_allowed> [, <assoc_kind> {, <entity>}])];
<subrule> ::= all | all_positional | declared | same_type
<assoc_kind> ::= [not_operator] call | discriminant | pragma |
record_aggregate | array_aggregate | instantiation |
enumeration_representation
The rule controls pragmas, discriminants, calls, aggregates, or instantiations that use too many positional associations. The definition of “too many” depends on the subrule:
If an <assoc_kind> is specified, it restricts the rule to specific kinds of associations; if not specified, all kinds of associations are controlled. The association kinds carry their obvious meaning, with the distinction that “array_aggregate” applies only to “true” array aggregates, while “enumeration_representation” applies to the special array aggregate used in enumeration representation clauses. For “pragma”, ”call”, and “instantiation”, entities can also be specified; such entities are exempted from the rule (i.e. the rule will not control these entities). See examples below.
For calls, positional association is not reported for operators
that use infix notation (since named notation is not possible); in
addition, if the “not_operator” modifier is specified before the
“call” keyword (not allowed elsewhere), positional association is
never reported for operators, even if they are called with the syntax
of a normal function call (i.e. Pack."+" (A,B)). Calls to
subprograms that are attributes are not reported either, since named
notation is not allowed for them.
This rule can be specified once for each combination of <subrule>, <assoc_kind>, and <control_kind>. This way, it is possible to have a number of positional associations considered a warning (search), and one considered an error (check). Of course, this makes sense only if <max_allowed> for search is greater than the one for check. It is also possible to have different criteria for each category.
If no parameter is given, it is equivalent to
“positional_associations (all, 0)”, i.e. all positional
associations are controlled.
Ex:
-- All positional associations: check positional_associations; -- All positional associations in aggregates: check positional_associations(all, 0, array_aggregate); check positional_associations(all, 0, record_aggregate); -- All positional associations with more than 3 elements: search positional_associations (all, 3); -- Positional associations in calls -- with more than 3 params of the same type search positional_associations (same_type, 3, call); -- Positional associations in calls with more than 2 elements (except -- calls to any subprogram called Put) search positional_associations(all, 2, call, all put); -- All positional association in calls to subprograms with more -- than 3 parameters check positional_associations (declared, 3, call);
The rule provides a variable to define how to count parameters in the case of calls that use the prefix notation (i.e. the “object.method” syntax).
| Variable | Values | Effect |
| Count_Prefix_Operand | off | The parameter given as prefix is not counted as a positional parameter. |
| on (default) | The parameter given as prefix is counted as a positional parameter, just like if the prefix notation had not been used. |
This rule generates fixes: in calls and instantiations, names are added to transform positional associations into named associations.
There are two kinds of calls where the rule does not complain about usage of positional association: infix operator calls (since requiring named notation would not allow infix notation any more), and calls to subprograms that are attributes (since named notation is not allowed for these).
For the purpose of the “same_type” subrule, integer literals are considered of the same type as any parameter of an integer type, and similarly for other universal values. The reason is that this rule is intended to avoid confusion between parameters, when strong typing would not detect an inversion of parameters for example; such a case would happen between parameters of a universal type.
For calls, another rule controls positional associations according to the value of parameters rather than their number: See Insufficient_Parameters.
Next: Pragmas, Previous: Positional_Associations, Up: Rules reference
This rule controls usage of potentially blocking operations (as defined in LRM 9.5.1 (8..16)) from within protected operations.
<control_kind> potentially_blocking_operations;
The rule follows the call graph, starting from every protected operation, and identifies all (direct and indirect) potentially blocking operations encountered. All protected types in the program are controlled.
Of course, calls to standard subprograms (notably IOs) that are defined to be potentially blocking are recognized.
Ex:
check potentially_blocking_operation;
This rule is very clever at finding potentially blocking operations resulting from external calls (or requeues) to the current protected object, even if this happens through a long chain of subprogram calls. Typically, this happens when a protected operation calls a subprogram, which in turn makes a call to an operation of the same protected object. Such calls generally result in dead-locks.
Therefore, it is advisable to run this rule on any program that exhibits mysterious (and hard to find) deadlocks that seem to involve protected objects.
When a single protected object is being analyzed, the rule will diagnose a circularity if there is a call to an operation of the same object in the call chain; however, if a protected type is being analyzed, the rule will diagnose a circularity if there is a call to any object of the same type in the call chain. Although it is possible to construct examples of this latter case where there is no risk of deadlock, it is so contrieved that it certainly deserves being looked at. But since the call is not 100% certain to be potentially blocking, the message will tell “possible external call” instead of “external call” in this case.
There is one case defined in LRM E.4(17) which is not recognized: remote subprograms calls.
Calls through pointers to subprograms, dispatching calls and calls to generic formal subprograms are unknown statically; they are assumed to be non potentially blocking. Such calls are detected by the rule “uncheckable”. See Uncheckable.
Next: Record_Declarations, Previous: Potentially_Blocking_Operations, Up: Rules reference
This rule controls usage of one or several specific pragmas.
<control_kind> pragmas (<pragma spec> {, <pragma spec>});
<pragma spec> ::= [multiple|not] all|nonstandard|<pragma name>
If the special name “nonstandard” is given, then all implementation-defined and unrecognized pragmas will be controlled. If the special name “all” is given, then all pragmas will be controlled. Otherwise, the parameters are the names of pragmas to be controlled. Note that <pragma name> must be the simple name of the pragma, since pragma names are predefined and do not follow the rules for regular Ada entities.
If “multiple” is specified before the pragma name (or the special name), the corresponding pragma(s) are controlled only if they apply to multiple entities, because one of the parameters is an overloaded name.
If “not” is specified before a pragma name, the corresponding pragma(s) is not controlled. This is useful to specify exceptions to “all” or “nonstandard”.
Ex:
check pragmas (elaborate_all, elaborate_body); -- Search pragma Convention that apply to several entities: search pragmas (multiple convention); -- Check nonstandard pragmas, except "unreferenced": check pragmas (nonstandard, not unreferenced);
If “all” and/or “nonstandard” is given together with a specific pragma name in a “search” or “check” rule, a message is issued only for the most specific occurrence. However, for “count”, all appropriate occurrences are counted, i.e. given the following rules:
C1 : count pragmas (annotate); C2 : count pragmas (nonstandard); C3 : count pragmas (all);
Counter C1 will report the number of occurrences of pragma
Annotate (a non-standard GNAT pragma), counter C2 will report the
number of non-standard pragmas (including occurrences of
Annotate), and counter C3 will report the total number of
pragmas (including occurrences of Annotate).
Next: Reduceable_Scope, Previous: Pragmas, Up: Rules reference
This rule controls various aspects of the components of records.
<control_kind> record_declarations (component, <compo_kind>
{,<repr_cond>});
<compo_kind> ::= <entity>|<category>
<repr_cond> ::= [not] in_variant | aligned | initialized | packed |
sized
The first parameter is a subrule keyword:
This rule traverses derivations, but not privacy (the category “private” can be given, to check components of a private type). See Definition of type categories.
If <repr_cond> are specified, the rule controls only record components to which all the corresponding representation items apply:
Storage_Unit.
Storage_Unit.
This rule can be specified several times for the “component” subrule.
Ex:
-- All record components of a discrete type should be initialized: check record_declarations (component, (), not initialized); -- The size of all components of type HW_Types.Squeezed must -- have a component clause: check record_declarations (component, HW_Types.Squeezed, not sized); -- Find unaligned components of a packed array type: check record_declarations (component, array, packed, not aligned);
It may seem strange to have a rule with only one subrule, but we expect to add more in the near future. Stay tuned...
If “[not] aligned” is specified, there are some rare cases where AdaControl cannot evaluate whether a component is aligned or not; in this case, it will “assume the worse” (i.e. report as if the component had the specified alignment), thus creating possible false positives. Such cases are detected by the rule “uncheckable”. See Uncheckable.
Next: Renaming_Declarations, Previous: Record_Declarations, Up: Rules reference
This rule controls declarations that could be moved to some inner scope.
<control_kind> reduceable_scope [(<subrule> {, <subrule>})];
<subrule> ::= {<restriction>} all | variable | constant |
subprogram | type | package |
exception | generic | use |
use_type | use_all_type
<restriction> ::= no_blocks | to_body
The rule reports on any declaration that is referenced only from a
single, inner scope, or in the case of use clauses (three
kinds), it will report on packages (or types) named in the clause
whose elements made visible by the clause are in a single, inner
scope. For entitities declared in package specifications, the rule
reports if they could be moved to the corresponding package body.
The initialization of an object is considered a usage of the object at the place where it is declared, thus preventing it from being moved. Therefore, constants and initialized variables are never reported as being movable to inner scopes; they are reported as being movable to package bodies however. Entities that are used as prefixes of a ’Access or ’Address attribute are never reported, since moving them would change their accessibility level. Similarly, task objects are not reported since moving them would change their master. Finally, dispatching operations (primitive operations of tagged types) are not reported either, since they can be the target of an “invisible” (dispatching) call.
If no <subrule> is given, or the <subrule> is “all”, all declarations
are controlled. If no_blocks is specified in front of a
<subrule>, the rule will not consider blocks as possible targets for a
reduced scope for the corresponding category. If to_body is
specified in front of a <subrule>, the rule will report only elements
declared in a package specification that could be moved into the body.
Specifying “all” explicitely is only useful in the case where there
is a <restriction>.
As a side effect, the rule will report about entities that are declared but not used (i.e. whose scope reduces to nothing).
Ex:
-- Types and variables shall be declared in the innermost scope -- where they are useful: check reduceable_scope (variable, type); -- Packages and subprograms shall be declared in the innermost -- scope where they are useful, but they are not allowed in blocks: check reduceable_scope (no_blocks subprogram, no_blocks package); -- Use clauses should be as restricted as possible: search reduceable_scope (use, use_type, use_all_type);
The following subrules generate fixes:
If you think that use clauses are acceptable, but should be
limited to the smallest possible scope, you would generally specify:
check unnecessary_use_clause; check reduceable_scope (use);
Note that there is some overlap between the two rules: use clauses
that serve no purpose or could be moved to body are reported by
both. There are differences too: “unnecessary_use_clause” reports
use clauses that could be changed to use type or
use all type clauses, or where all uses are qualified,
while “reduceable_scope” reports clauses that are useful, but only
in an inner scope.
Next: Representation_Clauses, Previous: Reduceable_Scope, Up: Rules reference
This rule controls usage of renaming declarations, possibly only those occurring at specified locations.
<control_kind> renaming_declarations (<subrule> {, <subrule>})
<subrule> ::= {[not] <location>} {[not] <filter>} <renaming_kw>
<location> ::= block | library | local | own |
private | public | in_generic | task_body
<filter> ::= identical | generic | as_body | operator |
as_operator | synonym |library_unit | renaming
<renaming_kw> ::= all | object | function_call | procedure |
function | package | exception
The <location> restricts the places where the occurrence of the renaming declaration is controlled. If it is preceded by “not”, the declaration is controlled except at this location. Several <location_kw> can be given, in which case the declaration is controlled at places where all the keywords apply.
block: only declarations appearing in block statements are controlled.
library: only library level declarations are controlled.
local: only local declarations are controlled (i.e. only declarations
appearing in (generic) packages, possibly nested, are allowed).
own: only declarations that are local to a (generic) package body
are controlled.
public: only declarations appearing in the visible part of
(generic) packages are controlled.
private: only declarations appearing directly in a private
part are controlled.
in_generic: only declarations appearing directly or indirectly in a generic
specification or body are controlled.
task_body: only declarations appearing directly in a task body
are controlled. Note that it would not make sense to have a
<location> for task specifications, since renaming declarations are not
allowed there.
The <filter> restricts the renaming declarations that are
controlled to those with certain properties (or to those not
having the property, if preceded by not). Several <filter>
can be given, in which case the declaration is controlled when all the
keywords apply.
identical: the identifier of the renaming is the same as the
one of the renamed entity.
generic: the renamed entity is generic.
as_body: the renaming is a “renaming as body” of a
subprogram.
operator: the renamed entity is an operator.
as_operator: the identifier of the renaming is an operator
symbol.
synonym: the renaming and the renamed entity are declared in
the same declarative part (these serve no purpose as far as
visibility is concerned, and are thus pure synonyms).
library_unit: the renamed entity is a library unit.
renaming: the renamed entity is itself declared by a renaming
declaration.
This rule can be given once for each combination the parameters.
Ex:
-- No renaming in same scope as renamed entity: check renaming_declarations (synonym all); -- Renamings "as body": check renaming_declarations (as_body, all); -- Renaming of an operator as a different operator: check renaming_declarations (not identical operator as_operator function); -- Renamings declared in block statements: check renaming_declarations (not block all); -- Renamings of library packages check renaming_declarations (library_unit package); -- Renamings as library units check renaming_declarations (library all);
“library” is a <location> and means that the renaming is itself a library unit. “library_unit” is a <filter> and means that the renamed entity is a library unit.
“as_operator” means that the renaming’s identifier is an operator symbol, while “operator” means that the renamed entity is an operator.
Of course, some <filter> do not apply to some forms of renaming declarations: it is not an error if you use them, but don’t expect to find any!
Next: Return_Statements, Previous: Renaming_Declarations, Up: Rules reference
This rule controls usage of representation clause.
<control_kind> representation_clauses [(<subrule> {, <subrule>})];
<subrule> ::= {<category>} <repr_kw> | [global] [object] <attribute>
<repr_kw> ::=
at | at_mod | enumeration |
fractional_size | incomplete_layout | layout |
non_aligned_component | non_contiguous_layout | non_power2_size |
no_bit_order_layout | overlay
Without parameter, the rule controls all representation clauses, otherwise it will control the representation clauses given as parameter.
If a representation keyword or attribute is preceded by one or several
categories, the rule controls only the representation items that apply
to types that belong to one of the provided categories (the type of
the component for the non_aligned_component subrule).
This rule does not traverse derivations and privacy (the category “new” can be given for derived types and “private” for private types). The rule separates extensions, i.e. “tagged” applies only to root tagged types, and “extension” can be used for type extensions. See Definition of type categories.
The meaning of the representation keywords is:
for XXX
use at AAA;”).
for T
use record at mod AA;”).
System.Storage_Unit. “non_power2_size”
controls size clauses whose value in System.Storage_Unit is not
a power of 2 (i.e. for most machines, it will mean a value different
from 8, 16, 32, and 64).
'Address of some other element.
In addition to these keyword, any specifiable attribute can be given
(including the initial “'”); the rule will control
specifications of this attribute. If the modifier “global” is given
before the attribute, only attribute specifications for global
entities are controlled. If the modifier “object” is given before
the attribute, only attribute specifications for objects are
controlled (as opposed to types for example). Note that double
attributes (like “'CLASS'INPUT”) can be given, and are
considered different from the simple attribute (“'INPUT”). It
is of course possible to specify both.
Ex:
All_Addresses: check representation_clauses (at, 'address);
All_Input: check representation_clauses ('input, 'class'input);
Sized_Objects: check representation_clauses (object 'size);
count representation_clauses ('SIZE);
-- check layout clauses for derived types:
check representation_clauses (new layout);
-- check layout clauses for root tagged types and type extensions:
check representation_clauses (tagged extension layout);
For the “fractional_size” and “non_contiguous_layout” subrules, there are some rare cases where AdaControl cannot evaluate the given size or elements of the record representation clause, and thus not detect the corresponding situation. Such cases are detected by the rule “uncheckable”. See Uncheckable.
The specifiable attributes (the ones that can be given as parameters
to this rule) are 'Address, 'Size,
'Component_Size, 'Alignment, 'External_Tag,
'Small, 'Bit_Order, 'Storage_Pool,
'Storage_Size, 'Write, 'Output, 'Read,
'Input, and 'Machine_Radix. See Ada Reference Manual
13.3(77).
Ada allows partial record representation clauses, i.e. it does not require all fields to be specified. This means that if you add a field to a record and forget to update the associated representation clause, there will be no compilation error. The “incomplete_record” subrule is handy for making sure that this does not happen.
Derived types with a representation clause may suffer an efficiency penalty, since calling an inherited subrograms requires a change of representation. Representation clauses for tagged types are dubious, since these types have hidden fields added by the compiler.
Next: Return_Type, Previous: Representation_Clauses, Up: Rules reference
This rule controls the number of return statements (in regular code and in exception handlers) and how deep they are nested in compound statements.
<control_kind> return_statements
(<subrule>, <value>|<bounds> {, <callable>});
<subrule> ::= depth | regular_count | handler_count
<bounds> ::= min|max <value> [, min|max <value> ]
<callable> ::= procedure | function | entry
The rule controls various metrics related to the use of return statements, depending on the subrule:
if statement it has a depth of 1, etc.
For all subrules, the rule is triggered if the measured value is stricty less than the value for “min” or strictly greater than the value for “max” (i.e. “min” and “max” represent the range of allowed values). If not given, “min” defaults to 0 and “max” to infinity. If a value is given (without “min” or “max” keywords), it stands for both “min” and “max” (i.e. it is the only allowed value).
If one or several <callable> is given after the bounds, the rule
applies only to return statements from the corresponding kind of
callable entity (procedure, function, or in the case of
entry, entry body and accept statements). Otherwise, the
rule applies to all kinds of callable entities.
This rule can be specified once for each combination of <subrule>, <callable>, and <control_kind>. This way, it is possible to have a value considered a warning (search), and one considered an error (check).
Ex:
-- warning if 2 return in the body of callables, error if 3 and above: check return_statements (regular_count, max 2); search return_statements (regular_count, max 1); -- every handler in a function must have at least 1 return: check return_statements (handler_count, min 1, function); -- no deep nested (more than 1 level) return statement: check return_statement (depth, max 1);
return statements appear in so-called callable entities
(procedures, functions, entry bodies and accept statements), but they
can also appear in blocks nested in one of these. The block itself
counts as a compound statement for the purpose of the “depth”
subrule. For the “regular_count” and “handler_count” subrules,
return statements from the regular statements of the block
are counted as belonging to the enclosing callable entity or handler,
but each exception handler of the block has its own counter of
return statements.
For the simple case of just forbidding several return
statements in a subprogram, see the simpler rule Statements.
Next: Side_Effect_Parameters, Previous: Return_Statements, Up: Rules reference
This rule controls certain types or form of types that are used for function results.
<control_kind> return_type [(<subrule> {, <subrule>})];
<subrule> ::= type <entity> | anonymous_access |
class_wide | constrained_array |
limited_class_wide | protected |
task | unconstrained_array |
unconstrained_discriminated |
This rule controls functions that return the indicated type, or whose return type belongs to one of the kinds given as <subrule>:
If no subrule is specified, all type kinds are controlled. Note that more than one kind may apply to a type: for example, a function can return a class-wide type with discriminants that includes tasks and protected objects as subcomponents. In this case, several messages are issued for the same type.
Ex:
check return_type (unconstrained_discriminated, unconstrained_array);
Next: Silent_Exceptions, Previous: Return_Type, Up: Rules reference
This rule controls calls that may depend on the order of evaluation of parameters.
<control_kind> side_effect_parameters (<entity> {, <entity>});
This rule controls subprogram calls or generic instantiations where different actual parameters call functions known to have side effects. This is dangerous practice, since correct behaviour may depend on a certain evaluation order of parameters, which is not specified by the language.
All <entity> are functions that are assumed to interfere, i.e. the rule will signal if any of these functions is called more than once in the parameters of a call. As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name.
It is allowed to give the name of a generic function, or of a function declared in a generic package; in this case, all functions resulting from instantiations of these generics will be considered.
In the case of renamings, you must give the name of the original function; the rule will work correctly if the call is made through a renaming of this function.
Ex:
check side_effect_parameters (F1); check side_effect_parameters (G1, G2);
Here, F1 has a side effect, and the rule will signal if it is called more than once. G1 and G2 are assumed to interfere, and therefore the rule will signal if either is called more than once, or if both are called. However, having a call that mentions F1 and G2 is OK.
Due to the size of internal structures, this rule may not be given more than 100 times.
Due to an unimplemented feature of ASIS-for-Gnat, this rule will not process defaulted parameters, and hence not detect interferences due to calling a side-effect function through the default value.
Next: Simplifiable_Expressions, Previous: Side_Effect_Parameters, Up: Rules reference
This rule controls exception handlers that can cause exceptions to silently disappear.
<control_kind> silent_exceptions (<element> {, <element>});
element ::= <control-item> | <report-item>
control-item ::= not | with <entity> | others
report-item ::= raise | explicit_raise | reraise | return |
requeue | <entity>
The rule controls handlers that do not call one of the given subprograms (for example a reporting procedure) nor perform other required operations, like returning, requeuing, or re-raising an exception.
A parameter that starts with “not” or “with” is a <control-item> and defines wich exceptions are controlled; the <entity> should be either an exception, or the name of a library unit (in which case, it applies to all exceptions declared in the library unit). As usual, the whole syntax for entities is allowed here. See Specifying an Ada entity name. If the <entity> is (part of) a generic, then it applies to all exceptions from all corresponding instantiations. If there is no <control-item>, then all exceptions are controlled.
If several <control-item> are given, the ones with “with” add exceptions to the set of controlled exceptions, and the ones with “not” remove exceptions, in order, starting from the empty set if the first <control-item> is a “with”, or starting from the set of all exceptions if the first <control-item> is a “not”. See examples below.
“when others” handlers are always controlled, unless
there is an explicit “not others” <control-item>. A “with others”
<control-item> can be specified to check only “when
others” handlers.
The other parameters are <report-item> and define the constructs considered “reporting”. <entity> should correspond to an Ada callable entity or generic package; as usual, the whole syntax for entities is allowed here. See Specifying an Ada entity name. If a generic procedure or function is given, then all corresponding instances are considered reporting subprograms. If a generic package is given, any instantiation (in an inner block of the handler) is considered reporting. In addition, the special names “explicit_raise”, “reraise”, “return” and “requeue” mark raise statements with an explicit exception name, raise statements without an exception name, return statements (including extended return statements), and requeue statements (respectively) as reporting. “raise” is a shorthand for both “explicit_raise” and “reraise”.
If “explicit_raise” is given as a parameter, the procedure
Ada.Exceptions.Raise_Exception is automatically added to the
list of procedures for both Check and Search, unless it is
explicitely specified as a parameter in a rule; and similarly
Ada.Exceptions.Reraise_Occurrence is added for “reraise”.
This way, it is possible to consider them as reporting procedures for
Check (for example) and not for Search.
A handler where all exceptions are uncontrolled is not
controlled at all (i.e. it is allowed to be non reporting). Otherwise,
the rule reports if the handler does not contain at least one of the
<report-item> in each possible path of the handler. If the
<report-item> appear only in if or case
statements, but not in all possible paths, or if they appear only in
the body of loop statements, the rule will issue a message
asking for a manual verification, since it cannot be statically
determined whether the proper treatment happens in every case.
Note that the purpose of this rule is to require the reporting calls to be “eye-visible”, i.e. textually written in the exception handler. For example, the rule will accept a call to a procedure inside the sequence of statements of a package body declared in some inner block; however, it will not accept the same call if it is in the sequence of statements of a package instantiation (unless the generic package is itself mentionned as reporting), because the call is not “eye-visible”. For the same reason, a call to a reporting function which happens as the default value of an omitted parameter in some other call will not be accepted.
This rule can be given once for each of check, search and count. This way, it is possible to have a level considered a warning (search), and one considered an error (check).
Ex:
-- Make an error if exception is not reraised and does not call
-- Reports.Trace, but make it only a warning if the exception is an
-- IO exception or Constraint_Error:
check silent_exceptions (not ada.io_exceptions,
not standard.constraint_error,
raise,
reports.trace);
search silent_exceptions (raise, reports.trace);
-- check handlers that do not reraise the exception, except for
-- IO exceptions:
check silent_exceptions (not Ada.IO_Exceptions, reraise);
-- Same for predefined exceptions, except Constraint_Error:
check silent_exceptions (not Standard, with Standard.Constraint_Error,
reraise);
-- Same for all exceptions named User_Error, wherever they are declared,
-- and no others
check silent_exceptions (with all User_Error, reraise);
-- Same for "when others" handlers
check silent_exceptions (with others, reraise);
Currently, “return” includes all return statements. It would be nice to separate function returns from procedure or accept returns. This is expected to be done in some future version of AdaControl.
There are two cases that are not statically checkable, and thus may not be identified by this rule: if an exception is raised in an inner block statement and handled locally, and if the exception handler aborts the current task.
If a reporting function is given, there are a few cases where the calls will not be recognized:
This limitation is intentional: these are such weird places to call a reporting function that it seems better to draw attention to it...
Next: Simplifiable_Statements, Previous: Silent_Exceptions, Up: Rules reference
This rule controls expressions that can be simplified in various ways.
<control_kind> simplifiable_expressions [(<subrule> {, <subrule>})];
<subrule> ::= conversion | if_not | logical |
logical_false | logical_not | logical_redundant |
logical_true | membership | parentheses |
range
The parameters are subrule keywords:
if expressions with an
else path and no elsif path, and where the
condition is given in negative form (i.e. it is a not, or a
"/=" comparison). Such expressions could be made positive (and
thus less error-prone) by interverting the if and
else paths.
<expr> = True (or /=), and “logical_false” does the
same for comparisons with false.
and”, “or”,
“and then”, and “or else” operations where the
left and right parts are identical.
not operators whose argument is a
comparison (which could be inverted).
in”
membership tests, and range comparisons of the form “X >= E1
and X <= E2”, all connected by “or” operators, can be
changed to a single “in” membership test. Multiple
comparisons for inequality, “not in” membership tests,
and range comparisons of the form “X <= E1 or X >= E2”,
all connected by “and” operators, can be changed to a
single “not in” membership test.
T'First .. T'Last
that should be T'range (or even simply T).
Without parameters, all kinds of simplifiable expressions are controlled.
This rule can be given at most once for each subrule.
Ex:
search simplifiable_expressions (parentheses); check simplifiable_expressions (range, logical);
The following subrules generate fixes:
in” or “not in” membership test.
There are cases where parentheses may seem unnecessary, but are (purposedly) not reported by this rule. Consider for example:
X := A + (B + C);
Removing the parentheses would change the expression to mean:
X := (A + B) + C;
If the "+" operator has be redefined and is no more
associative, this would actually change the meaning of the program. In
a less contrieved example, note that:
X mod (A*B)
is not the same as:
X mod A * B
For these reasons, and to make the rule easier to understand for the user, the rule does not report unnecessary parentheses between operators of identical priority levels.
Conversion of universal value is never necessary, however there are cases where overloading resolution may require the conversion to be replaced by a qualification, rather than being simply removed.
Logical redundant operations may result from cut-and-paste errors, and are often hard to spot. Typically:
if A < Limit1 or A < Limit1 then ...
where the right “Limit1” should have been changed to “Limit2”.
Next: Statements, Previous: Simplifiable_Expressions, Up: Rules reference
This rule controls statements that can be removed or simplified in various ways without changing the meaning of the program.
<control_kind> simplifiable_statements [(<subrule> {, <subrule>})];
<subrule> ::= [no_exit] [full_range] all |
block | dead |
[full_range] for_in_for_for_of | for_for_slice |
handler | if |
if_for_case | if_not |
loop |
[no_exit] loop_for_while | nested_path |
null | true_if |
unnecessary_if | [no_exit] while_for_for
The parameters are subrule keywords:
return, requeue, or goto statement,
or an exit statement that is either unconditional or whose
condition is statically known to be true;
while statements and if statements (including
elsif paths) whose condition is statically false;
else and elsif paths that follow an
if statement (or elsif path) whose condition is
known to be true;
elsif paths whose condition is identical
to the one of a preceding if or elsif path;
case statements whose choices are all
statically null ranges;
for loops whose range is
statically empty.
For case statements, it is possible to
not control branches that contain only null or
raise statements, see variable “acceptable_dead_case”
below.
for .. in loops
where the loop index is used only for indexing a single variable. Such
loops can be changed to a for .. of on the
corresponding array, often resulting in simpler code. For example:
declare
S : constant String := Function_Returning_String;
begin
for I in S'range loop
-- Do something with S(I)
end loop;
end;
can be changed to:
for C of Function_Returning_String loop -- Do something with c end loop;
If the “full_range” modifier is given, the rule controls only loops whose range is statically known to cover the whole range of the indexed variable.
This subrule applies only to monodimensional arrays. Although
for .. of loops can be used with
multidimensional arrays, this usage is dubious in most
cases.
for I in S'First .. S'Last-1 loop S (I+1) := S(I); end loop; for I in S'Range loop S (I) := ' '; end loop;
can be changed to:
S(S'First + 1 .. S'Last) := S(S'First .. S'Last - 1); S := (others => ' ');
raise
statement without an exception name. However, a handler is not
reported if there is also a non trivial handler for others.
These examples show the situation:
exception
when Constraint_Error => --Reported (no when others)
raise;
end;
exception
when Constraint_Error => --Reported (trivial when others)
raise;
when others => --Reported
raise;
end;
exception
when Constraint_Error => --Not reported (non trivial when others)
raise;
when others =>
Put_Line ("Error");
end;
if statements with an else
path that contains only null statements (and can thus be
removed).
if statements that
could be replaced by case statements. An if
statement is assumed to be replaceable if it has at least one
elsif and all conditions are comparisons (or membership
tests, possibly connected by logical operators) of the same discrete
variable with static values. Typically, this subrule will spot
constructs like:
if X = 1 then
...
elsif X = 2 or X = 3 or X = 4 then
...
elsif X >= 5 and X <= 10 then
...
elsif X in 11 .. 20 then
...
else
...
end if;
if statements with an
else path and no elsif path, and where the
condition is given in negative form (i.e. it is a not, or a
"/=" comparison). Such statements could be made positive (and
thus less error-prone) by interverting the if and
else paths.
while loop statements where the condition
is statically known to be True, and can thus be changed to simple loops.
exit (for the same loop), and which can
therefore be turned into a while loop. If the “no_exit”
modifier is given, the loop is not controlled if it includes another
exit statement that applies to it.
if statements that
can be moved outside. This happens if the if has only
then and else paths, and either of them ends
with a “breaking” statement (raise, return,
exit or goto); in this case, the other path
needs not be nested inside the if statement. However, if
both paths end with the same “breaking” statement, no error is
reported. In short, the rule signals the following examples:
if Cond then return; else I := 1; end if; if Cond then I := 1; else return; end if;
because they can be changed to:
if Cond then return; end if; I := 1; if not Cond then return; end if; I := 1;
The rule will not signal the following example, where both paths end
with the same “breaking” statement (return), because it
would break the symetry of the statement:
if Cond then return 1; else return 2; end if;
null statements that serve no purpose
and can be removed. Note that if a null statement carries
a label, it is not considered simplifiable.
if statements and elsif paths
whose condition is statically known to be true.
if statements with no
elsif path whose then and else paths
are both assignments to the same variable or return
statements and whose (assigned or returned) value is a plain True
in one path and a plain False in the other path. The
if statement can be removed, and its logical expression
directly assigned to the variable, or returned (possibly with a
negation of the condition). Typically:
if V=1 then -- Equivalent to "Flag := V=1;" Flag := True; else Flag := False; end if; if V=1 then -- Equivalent to "return V /= 1;" return False; else return True; end if;
while loops that could be
changed into for loops. More precisely, it controls
while loops where:
while is a greater, greater or equal,
less than, less than or equal, or not equal comparison involving only
a simple variable on one side and an expression on the other side whose acceptable
elements depend on the rule variable “While_For_Expression”, see below.
while condition.
out or in out
parameter to a procedure (or entry)
exit statement that applies to it.
This rule can be given at most once for each subrule.
Ex:
check simplifiable_statements (block, null); search simplifiable_statements (if); check simplifiable_statements (no_exit while_for_for);
The rule provides a variable to define branches of case
statements that are not to be controlled.
The rule provides a variable to define the maximum number of allowed
indexings for the for_in_for_for_of subrule.
The rule provides a variable to define the complexity of expressions
accepted by the while_for_for subrule for while
loops to be considered changeable to for loops.
| Variable | Values | Effect |
| Acceptable_Dead_Case | none (default) | All dead branches are controlled. |
| only_null | Dead branches that contain only null statements are not controlled. | |
| only_raise | Dead branches that contain only a raise statement are not controlled. | |
| null_and_raise | Dead branches that contain only null statements or a raise statement are not controlled. | |
| Acceptable_Indexings | <Integer> (default = 0) | for loops that use their loop index for indexing a variable up to the indicated number of times are not controlled by the for_in_for_for_of subrule. |
| While_For_Expression | any (default) | No restriction on the expression used for comparisons |
| no_function | The expression must not contain any (non-operator) function call. | |
| static | Only comparison with static expressions are accepted. |
The following subrules generate fixes:
while <cond> loop” is changed to a
plain loop
null statement is removed.
if statement is removed and its expression assigned to the
variable, or as the return value. Negation of the condition is performed if necessary.
The “dead” subrule does not signal a when others branch
of a case statement
that covers no value at all; this can be checked with:
check case_statement (others_span, min 1);
Ignoring dead case branches that contain only
null or raise statements is useful when the
language requires some branches to be given due to the completion
check of the case statement, but these values are actually
impossible due to the logic of the program.
A for .. in loop whose index does not cover the
totality of the range of the indexed variable can be replaced by a
for .. of loop over a slice of the variable. However,
some might prefer to keep using a for .. in loop in
that case, hence the modifier “full_range”.
“loop” may seem a strange thing to check, since no Ada programmer is supposed to write this. However, experience shows that it is a good indicator of code written by people who did not get proper Ada training. Such code is certainly worth a peer review...
When the value “any” is given for the variable
While_For_Expression, the “while_for_for” subrule will not
signal any false-negative; with the value “static”, the subrule will
not signal any false-positive. The value “no_function” is an
acceptable compromise in-between.
“while_for_for” may trigger false positives in some unlikely cases
that are impossible (or deemed too costly) to check, like passing the
control variable as an out or in out parameter
to a function, modifying the variable directly from a called
subprogram or from a concurrently running task... If the user replaces
the while loop with a for loop in those cases,
the control variable will be changed to a constant and the program
will not compile any more; there is therefore no risk.
In accordance with ARM(5.5.2(6.1/4)), “for_in_for_for_of” does not control loops where the loop index is used to index an array whose constraint depends on a discriminant with default values. However, the special case of “known-to-be-constrained” variables is not recognized, possibly resulting in false negatives. This is harmless, since it is a very rare case that would just result in keeping the “for in” loop.
Next: Style, Previous: Simplifiable_Statements, Up: Rules reference
This rule controls usage of certain Ada statements.
<control_kind> statements (<subrule> {, <subrule>};
<subrule> ::= any_statement |
abort | accept |
accept_return | assignment |
asynchronous_select | backward_goto |
block | case |
case_others | case_others_null |
code | conditional_entry_call |
declare_block | delay |
delay_until | dispatching_call |
dynamic_procedure_call | effective_declare_block |
entry_call | entry_return |
exception_others | exception_others_null |
exit | exit_expanded_name |
exit_for_loop | exit_outer_loop |
exit_plain_loop | exit_while_loop |
exited_extended_return | extended_return |
for_in_loop | for_iterator_loop |
for_loop | for_of_loop |
function_return | goto |
goto_not_continue | hard_bounds_array_for_loop |
if | if_elsif |
inherited_procedure_call | labelled |
loop_return | multi_for_of_loop |
multiple_exits | named_exit |
no_else | null |
null_case_path | null_if_path |
null_loop_body | procedure_call |
procedure_return | raise |
raise_foreign | raise_locally_handled |
raise_nonpublic | raise_standard |
redispatching_call | requeue |
reraise | selective_accept |
simple_block | simple_loop |
terminate | timed_entry_call |
unconditional_exit | unnamed_block |
unnamed_exit | unnamed_for_loop |
unnamed_loop_exited | unnamed_multiple_loop |
unnamed_simple_block | unnamed_simple_loop |
unnamed_while_loop | untyped_for |
untyped_for_in | untyped_for_of |
while_loop
Subrules that are Ada keywords control the corresponding Ada statements. The meaning of other subrules is as follows:
any_statement controls all statements. This is of course not
intended to forbid all statements in a program (!), but
counting all statements can be quite useful.
accept_return controls return statements that return from an
accept statement, entry_return controls return
statements that return from a (protected) entry body, and
procedure_return controls return statements that return from a
procedure. loop_return controls return statements (including
extended return statements) that appear inside a loop
statement.
assignment controls all assignment statements.
asynchronous_select controls the select
... then abort statement. conditional_entry_call
controls the select ... else
statement. timed_entry_call controls the select
... or delay statement. selective_accept controls
the regular select statement.
block controls all block statements, while unnamed_block
controls blocks without a name, declare_block controls blocks
with an explicit declare (even if the declarative part is
empty), and effective_declare_block controls blocks with a
declarative part that includes anything else than use
clauses and pragmas. simple_block controls block statements
that have no declarative part (or an empty declarative part) and no
exception handlers, and unnamed_simple_block does the same,
but only for blocks without a name.
case controls all case statements.
case_others controls any when others path in a
case statement, while case_others_null controls only
when others paths in a case statement that
contain only null statements.
code controls code statements.
delay controls only relative delay statements, while
delay_until controls absolute delay until
statements.
entry_call controls all entry call statements, including those
that are part of a conditional or timed entry call statement.
exit controls all exit statements, while exit_for_loop,
exit_while_loop, and exit_plain_loop control
exit statements that terminate for loops,
while loops, and plain (neither for nor
while) loops, respectively. unconditional_exit
controls exit statements without a when
condition. multiple_exits controls loop that have more than
one exit statement. unnamed_loop_exited controls
exit statements that terminate an unnamed loop. exit_outer_loop
controls exit statements that exit from an outer loop
(i.e. not the innermost one). exit_expanded_name controls named
exit statements where the name is given as an expanded
name.
exception_others controls any when others exception
handler, while exception_others_null controls only
when others exception handlers that contain only
null statements.
extended_return controls extended return statements (i.e. the
Ada 2005 construct “return V : T do ... end
return”). exited_extended_return controls extended
return statements that can be left without actually returning due to
an exit or goto statement within their sequence of
statements.
for_loop controls all for loops, while
for_in_loop controls only the traditional form of
for loop (for I in range loop),
for_iterator_loop controls the iterator form (for I
in Iterator loop), and for_of_loop controls the
components form (for V of ... loop).
multi_for_of_loop controls the components form only when the
iterated-on array has more than one dimension (this is allowed by the
language, but “flattens” the array which might be undesirable).
function_return controls return statements (including extended
return statements) from functions. Obviously, return statements cannot
be forbidden in functions; this keyword controls that there is only
one return statement in the body of functions, and at most one return
statement in each exception handler of the exception part of
functions.
goto controls all goto statements, while
goto_not_continue controls goto statements except
those whose target statement is a null statement (including
the implicit null statement of Ada 2012) which is the last
statement of the body of a loop statement (i.e. when the
goto statement is used as a replacement for the
continue statement of other
languages). backward_goto controls goto statements
whose target label is located ahead of the goto (i.e. those
that could create loops).
hard_bounds_array_for_loop controls for loops whose loop
parameter is used in (or as part of) the indexing of an array
variable, and where the given bounds of the loop parameter do not use
any of the 'First, 'Last, or 'Range attributes.
if controls all if statements.
if_elsif controls if statements that have at least
one elsif.
labelled controls statements with a label (true statement
labels, not block and loop names).
named_exit controls exit statements with a loop
name.
no_else controls if statements that have no else
path.
null controls all null
statements. null_if_path, null_case_path and
null_loop_body control paths (branches) of if or
case statements, or bodies of loop statements
(respectively) that contain only null statements.
procedure_call controls all calls to
procedures. dispatching_call does the same, but only for
dispatching calls, while redispatching_call does the same, but
only for dispatching calls that are (directly or indirectly) inside a
primitive operation of a tagged type. dynamic_procedure_call
does the same, but only for calls through pointers.
inherited_procedure_call controls calls to procedures that have
been inherited by a derived type and not redefined.
raise controls all raise statements.
reraise controls raise statements in exception
handlers that reraise the same exception, and calls to the
Ada.Exceptions.Reraise_Occurrence procedure.
raise_standard controls raise statements that raise
one of the predefined exceptions (those declared in package
Standard). raise_nonpublic controls statements that
raise exceptions that are neither predefined nor defined in the
visible part of a package. raise_foreign controls statements
that raise exceptions that are neither predefined nor declared in the
same program unit (or an ancestor of the unit) as the statement that
raises the exception. raise_locally_handled controls
statements that raise an exception which is handled by a handler in
the same subprogram body as the statement.
Note that for these subrules, the exception can be raised either by a
raise statement, or by a call to
Ada.Exceptions.Raise_Exception where the raised exception is
statically determinable.
simple_loop controls simple loops, i.e. those that are neither
while nor for loops.
unnamed_exit controls exit statements without a
loop name that exits from a named loop.
unnamed_for_loop, unnamed_simple_loop, and
unnamed_while_loop control loops of the given kind that are not
named.
unnamed_multiple_loop controls nested loops that are not named
(i.e. under this rule, only loops that contain no inner loop, and are
not nested in another loop, are allowed not to be named). The kind of
loop (plain, for, while) is not considered.
untyped_for_in controls regular for .. in loops
that use a range without an explicitely named type (i.e. for
I in 1..10 loop). Using a 'Range attribute is
OK. untyped_for_of controls for .. of loops that
have no subtype indication. untyped_for controls both. Note
that generalized iterators are not controlled, since the syntax
does not allow the specification of an explicit subtype for them.
while_loop controls all while loops.
Ex:
search statements (delay); check statements (goto, abort); check statements (case_others_null, exception_others_null);
The rule provides a variable to specify the amount of information displayed with the “procedure_call” and “entry_call” subrules.
The rule provides a variable to define the length in lines of “small
loops” that are not controlled by the unnamed_for_loop,
unnamed_simple_loop, and unnamed_while_loop subrules.
| Variable | Values | Effect |
| Called_Info | none (default) | No extra information. |
| compact | Display the name of the called procedure or entry. | |
| detailed | Display the name of the called procedure or entry with overloading information. | |
| root_detailed | Display the name of the root called procedure or entry (i.e. the original procedure if the called procedure is a renaming) with overloading information. | |
| Small_Loop_Length | <Integer> (default = 0) | Loops that span up to the indicated number of lines without being
named are not controlled by the unnamed_for_loop,
unnamed_simple_loop, and unnamed_while_loop subrules |
It may seem strange to control things like if or
case statements, since no coding standard would prohibit
their use. However, this may be useful, especially with “count”, for
statistical purposes, like measuring the ratio of if to
case statements.
The plain “raise” subrule controls the raise statement,
and only this one. If you want to check all places where exceptions
can be raised, use also the “entities” rule like this:
"all raise": check statements (raise),
check entities (Ada.Exceptions.Raise_Exception,
Ada.Exceptions.Reraise_Occurrence);
Other subrules of the “raise” family are more about which kind of
exception is being raised, and therefore control also exceptions
raised by calling the procedures from Ada.Exceptions.
“inherited_procedure_call” controls only procedure calls. For function calls, see rule Expressions.
For more sophisticated controls over return statements, see
the rule Return_Statements.
“hard_bounds_array_for_loop” is quite tolerant, it just controls the presence of the attributes in the bounds, but not, for example, that they refer to the index type of the indexed variable. This is deliberate: the rule is just intended to control “plain” hard-coded bounds, instead of refering to the characteristics of the array. Attempting more sophisticated rules would immediately result in a big number of false positives that would make the rule unusable.
Next: Terminating_Tasks, Previous: Statements, Up: Rules reference
This rules controls usage of various “general” Ada coding style.
<control_kind> style;
<control_kind> style (casing_aspect, <casing_kw> {,<casing_kw>});
<control_kind> style (casing_attribute, <casing_kw> {,<casing_kw>});
<control_kind> style (casing_exponent, <casing_kw> {,<casing_kw>});
<control_kind> style (casing_identifier, <casing_kw> {,<casing_kw>});
<control_kind> style (casing_keyword, <casing_kw> {,<casing_kw>});
<control_kind> style (casing_number, <casing_kw> {,<casing_kw>});
<control_kind> style (casing_pragma, <casing_kw> {,<casing_kw>});
<control_kind> style (compound_statement);
<control_kind> style (default_in);
<control_kind> style (exposed_literal, <type_kw>, {, <value_place>});
<control_kind> style (formal_parameter_order {, <mode list>});
<control_kind> style (multiple_elements {,<element_kw>});
<control_kind> style (no_closing_name [, <max_lines>]);
<control_kind> style (numeric_literal, [not] <base> [, <block_size>]);
<control_kind> style (parameter_order {, <mode list>});
<control_kind> style (renamed_entity);
<casing_kw> ::= uppercase | lowercase | titlecase | original
<element_kw> ::= [flexible] clause | pragma |declaration | statement |
handler | begin | end | then | when |
else | is | loop | do | keywords
<mode_list> ::= <mode> {| <mode>}
<mode> ::= in | defaulted_in | access | in_out | out |
type | procedure | function | package
<type_kw> ::= integer | real | character | string
<value_place> ::= <value> | <place>
<value> ::= [max] <integer number> | <real number> | "<pattern>"
<place> ::= declaration | statement |
aggr_index | attr_index | constant | exponent |
index | number | pragma | repr_clause |
var_init | type
The first parameter is a subrule keyword:
“casing_exponent” controls the case of the ’E’ in a numeric literal using exponent notation, and “casing_number” controls the case of extended digits used in based numbers when the base is above 10 (only “Lowercase” and “Uppercase” allowed for these).
If more than one <casing_kw> is given, it means that any of them is allowed.
if statements,
loop statements, block statements, and accept
statements with a body; 4 for case statements, selective
accept statements, and timed entry call statements; and 5
for conditional entry call statements and asynchronous select
statements.
in mode for a parameter. Access
parameters are not reported, since an an explicit in is not
allowed in that case.
In addition, one or several <place> keyword can be used to specify
constructs where any literal is allowed: “declaration” stands for
any declaration, “statement” for any statement, “aggr_index” for
index values in a (named) array aggregate, “attr_index” for the
index expression of attributes like 'First or 'Length,
“constant” for constant declarations, “exponent” for the right
parameter of an exponentiation (i.e. "**") function call,
“index” for array indexing, “number” for named number
declarations, “pragma” for pragma arguments, “repr_clause” for
representation clauses, “type” for type (and subtype) declarations,
and “var_init” for the initialization expression of variable
declarations. If no <place> is given, it is taken as number,
constant, i.e. any literal is allowed in named numbers and constant
declarations.
begin, end, then
and when are required to be on a line of their own,
together with the possible keyword or identifier attached to them and
the semi-colon. In addition, the is, loop or
do that terminates the first part of some declarations or
statements is required to be on the same line as the begining of the
element, or on a line of its own.
Extra parameters specify which kind of element to check; if not
specified, all kind of elements are controlled. “keywords” is a
shorthand for specifying all keywords. If “flexible” is specified in
front of “clause” (not allowed otherwise), it allows a
use clause to be on the same line as a with
clause, provided all packages named in the use clause are
also named in the preceding with clause.
If no parameter is given, the order for regular parameters is “in” or “access” first, then “in_out”, then “out”, then “defaulted_in”. The order for formal_parameters is “type” first, then “in” “defaulted_in” and “access”, then “in_out”, then “procedure” and “function”, then “package”.
Ex:
search style (no_closing_name);
search style (no_closing_name, 5);
check style (casing_identifier, original);
check style (default_in);
check style (numeric_literal, 10, 3);
check style (exposed_literal, integer, 0, 1);
check style (exposed_literal, real, 0.0, 1.0);
-- in parameters (with or without default) and access
-- parameters must be first, then in out parameters, then
-- out parameters. In parameters are allowed last if they
-- have defaults.
check style (parameter_order,
in | defaulted_in | access,
in_out,
out
defaulted_in);
-- For generics, formal objects must come first, then formal
-- types, then formal subprograms, then formal package:
check style (formal_parameter_order,
in | in_out,
type,
procedure | function,
package);
Without parameter, the rule will control all style aspects with parameter values that correspond to the most commonly used cases, i.e. it is equivalent to the following:
style (no_closing_name); style (casing_aspect, titlecase); style (casing_attribute, titlecase); style (casing_exponent, uppercase); style (casing_identifier, original); style (casing_keyword, lowercase); style (casing_number, uppercase); style (casing_pragma, titlecase); style (default_in); style (multiple_elements) style (literal, 10, 3); style (exposed_literal, integer, 0, 1) style (exposed_literal, real, 0.0, 1.0);
The following subrules generate fixes:
in” is added.
end”.
For the “Casing_Identifier” subrule, if the value is “original”, subprogram and parameter names from the body are checked against those from the specification (if any). This is what the user would expect, although strictly speaking it is not a usage of the name.
Note that operators always follow the casing rule for keywords, even
for calls that use the infix notation (i.e. in "and"(A, B)).
Having more than one allowed casing is useful if for example you want to require Titlecase, but accept that the original casing be used (maybe because your editor or pretty-printer forces it).
For the “Exposed_Literal” subrule, negative values can be specified as being allowed; negative numbers are handled as if they were literals. This is what the casual user would expect, but to the language lawyer, “-1” is not a negative literal, it is a unary minus operator applied to the positive value “1”.
“compound_statement” was a simplistic way of finding badly laid-out statements, at a time when “multiple_elements” did not control the end or intermediate parts of declarations and statements. It is of little use now that “multiple_elements” has been enhanced.
If a predefined operator or an attribute is renamed, the “renamed_entity” subrule cannot check that the original entity is not used in the scope of the renaming. Such cases are detected by the rule “uncheckable”. See Uncheckable.
For a “pragma Interface", both subrules “casing_keyword"
and “casing_pragma” apply to the word “Interface”. You should not
use “pragma Interface" anyway...
Next: Type_Initial_Values, Previous: Style, Up: Rules reference
This rule controls tasks that can terminate.
<control_kind> terminating_tasks
A task is considered a terminating task if its last statement is not
an unconditional loop, or this if this loop is exited. It is also
considered terminating if it contains a selective accept with a
terminate alternative.
Since this rule has no parameters, it can be given only once.
Ex:
check terminating_tasks;
There is still one case where a task terminates, which is not reported by this rule: when a task is aborted. This is intended, since there are cases (like mode changes) where a logically non-terminating task is aborted.
If aborts are also to be reported, use the rule “statements (abort)”. See Statements.
Next: Type_Usage, Previous: Terminating_Tasks, Up: Rules reference
This rule controls that a special constant is declared together with each type, for example to serve as a default initial value.
<control_kind> type_initial_values [("<pattern>")];
This rule controls types that do not feature an initialization constant declared in the same declarative part as the type. If no <pattern> is given, any constant is considered an initialization constant for its type; otherwise, only constants whose name matches the given pattern are considered initialization constants.
Ex:
check type_initial_values ("^C_Init_");
The above example will ensure that every declared type features a constant of the type whose name starts with “C_Init_”.
Next: Uncheckable, Previous: Type_Initial_Values, Up: Rules reference
This rule controls usage of indicated types, either individually or by category.
<control_kind> type_usage (<attribute>, <category> {, <aspect>}]);
<control_kind> type_usage (index, <entity>|<category> {, <aspect>}]);
<aspect> ::= [not] representation | pack | size | component_size
If the first parameter is an attribute (a name starting with a simple quote), the rule controls all occurrences of the attribute where the prefix designates a type belonging to the <category> given as second parameter.
If the first parameter is “index”, the rule controls all array types that have an index of the type given by <entity>, or belonging to the <category> given as second parameter. As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name.
This rule traverses derivations but not privacy (the category “private” can be given for attributes of a private type). Obviously, only categories “()”, “range” and “mod” can be given for the subrule “index”. See Definition of type categories.
For both subrules, if one or several <aspect> are given, only types featuring (or not featuring if “not” is given) the provided aspects are controlled.
The meaning of <aspect> is:
pragma.
Ex:
-- Don't use 'Pos attribute on enumerated types with a representation
check type_usage ('Pos, (), representation);
-- Don't use modular type for array indexes
check type_usage (index, mod);
The subrule “index” controls the use of a type as an index at any position and irrespectively of the number of indices of the array. To control a precise pattern of types used as indices, use the rule “array_declarations”. See Array_Declarations.
The subrule that uses attribute names does not allow an <entity>. To control occurrences of an attribute on a precise type, use the rule “entities”. See Entities.
Next: Unit_Pattern, Previous: Type_Usage, Up: Rules reference
This rules controls cases where it is not possible to guarantee the accuracy of checks performed by AdaControl, and where manual inspection may be required.
<control_kind> uncheckable [(<subrule> [,<subrule>])]; <subrule> ::= false_positive | false_negative | missing_unit
The parameters are subrule keywords:
Although not analyzed, an usual error message will be output for such units.
Otherwise, this rule controls constructs that are not static and prevent other rules from being fully reliable. This rule is special, since it really affects the way other rules behave when they encounter a statically uncheckable construct. Therefore, if a label is given, the message will include the label as usual, with an indication of the rule that triggered the message; if no label is given, the message will include the name of the rule that detected the uncheckable construct, not “uncheckable” itself.
If no keyword is given, all subrules are activated.
As far as statistics are concerned (see Report messages), “uncheckable” messages from rules are counted under the corresponding rule’s statistics (like other messages), but there will be also a count of all “uncheckable” messages under the rule “UNCHECKABLE”, and also subtotals corresponding to the number of “uncheckables” for each rule.
This rule can be given only once for each subrule.
Ex:
check uncheckable (false_negative); search uncheckable (false_positive); check uncheckable (missing_unit);
This rule is especially important when AdaControl is used in safety critical software, since it will detect constructs that could escape verification. Such constructs should be either disallowed, or require manual inspection. On the other hand, in casual software, it may lead to many messages, since for example dispatching calls are uncheckable with many rules.
With “missing_unit”, the message does not include a reference to a source location, since there is no place in the source which can be considered as the origin of the error. If you run AdaControl from GPS, there will always be a separate category (“Uncheckable”) in the locations window, under which the message will appear, with a file name of “none”. Don’t try to click on the error message, since GPS will find no file named “none”!
Next: Units, Previous: Uncheckable, Up: Rules reference
This rule controls various usage patterns of program units and elements declared in them.
<control_kind> unit_pattern (Single_Tagged_Type);
<control_kind> unit_pattern (Tagged_Type_Hierarchy);
<control_kind> unit_pattern (Context_Clauses_Order {, <clause_list>});
<control_kind> unit_pattern (Declarations_Order, <target>,
{, <decl_list>});
<clause_list> ::= <clause> {| <clause>}
<clause> ::= with | use | use_type | use_all_type | pragma
<target> ::= package_public | package_private | package_body |
subprogram
<decl_list> ::= {<place>} <declaration> {| {place>} <declaration>}
<declaration> ::= use | use_type |
use_all_type | number |
constant | variable |
private_type | full_type |
subtype | subprogram_spec |
package_spec | generic_subprogram_spec |
generic_package_spec | task_spec |
protected_spec | subprogram_body |
package_body | generic_subprogram_body |
generic_package_body | task_body |
protected_body | object_renaming |
subprogram_renaming | package_renaming |
exception_renaming | subprogram_instantiation |
package_instantiation | exception |
others
<place> ::= own | public | private
The first parameter is a subrule keyword:
use type clause, specify also “use_all_type”
to include the Ada 2012 use all type clause as well. Note
that all <clause>s not specified explicitely have no place, and thus
are not allowed at all.
Each parameter of the rule consists in one or several of the <declaration> keywords, and describes, in order, which kind of declaration is allowed. Note that all <declaration>s not specified explicitely have no place, and thus are not allowed at all, unless “others” is given as the last parameter, in which case it covers all elements not part of any of the preceding parameters. See example below.
Body declarations (those whose name ends withe “_body”) can be preceded by one or several <place> keywords, in order to restrict the declaration to bodies whose corresponding specification is given in a visible part (“public”), in a private part (“private”), or anywhere else (“own”).
Ex:
check unit_pattern (single_tagged_type);
check unit_pattern (tagged_type_hierarchy);
-- All with clauses must come first, then use and use type clauses
-- (freely mixed), then pragmas
check unit_pattern (context_clauses_order,
with,
use | use_type | use_all_type,
pragma);
-- In the public part of a package, declare constants and named numbers
-- first,then private types, then any of regular types, constants, and
-- variables, then subprograms specifications (including generics and
-- instantiations), then anything else:
check unit_pattern (declarations_order, package_public,
number | constant,
private_type,
full_type | constant | variable,
subprogram_spec | generic_subprogram_spec | subprogram_instantiation,
others);
-- In a package body, declare subprogram and package specs after other
-- declarations, followed by bodies, with bodies of exported
-- units after bodies of local units (but no use clauses allowed)
check unit_pattern (declarations_order, package_body,
number | constant | variable | full_type | subtype | exception |
exception_renaming | object_renaming,
subprogram_spec | generic_subprogram_spec | subprogram_renaming |
package_spec | generic_package_spec | package_renaming|
task_spec |
protected_spec |
subprogram_instantiation | package_instantiation,
own subprogram_body | own package_body |
own generic_subprogram_body | own generic_package_body |
own task_body | own protected_body,
public private subprogram_body | public private package_body |
public private generic_subprogram_body |
public private generic_package_body |
public private task_body | public private protected_body);
For “context_clauses_order” and “declarations_order”, elements given as part of the same parameter (i.e. with a vertical bar between them) can be freely mixed, then followed by any of the elements of the next parameter, etc. An element may appear several times in different parameters. If the last parameter is “others”, any element not mentionned at all is allowed after the ones for which you specify an order; this way, it is possible to specify an order for just some elements, and then don’t care for the rest.
Expression functions and null procedures are classified as “subprogram_spec” unless they are the completion of an explicit specification, in which case they are classified as “subprogram_body”.
If you don’t want a declaration to appear at all, you can also use the rule “declarations”. See Declarations.
Next: Unnecessary_Use_Clause, Previous: Unit_Pattern, Up: Rules reference
This rule controls that all necessary units, and only those, are processed by AdaControl.
<control_kind> units [(<subrule> [,<subrule>])]; <subrule> ::= unreferenced | unchecked
The parameters are subrule keywords:
This rule can only be given once for each of the subrules.
Ex:
check units (unchecked); search units (unreferenced);
The main program will appear as unreferenced, since it is normally part of the controlled units, and not withed by any other unit. As usual, the corresponding message can be disabled by putting the comment:
--## rule line off units
on the main program.
Next: Unsafe_Elaboration, Previous: Units, Up: Rules reference
This rule controls use clauses (all three kinds) that do
not serve any purpose, could be moved, or reduced to a more specific
one.
<control_kind> unnecessary_use_clause [(<subrule> {,<subrule>})];
<subrule> ::= unused | qualified | operator | primitive | nested |
movable
The rule controls use clauses (including use
type and use all type clauses) that can safely be removed,
moved, or changed to a use type or use all type
clause. The subrules define which cases are controlled; if no subrule
is given, all cases are controlled.
use clause is given, but no element from the
corresponding package is used within the scope of the
clause. Similarly, for use type and use all
type clauses, no primitive operator (respectively operation) is used
within the scope of the clause. The message starts with “Unused:”.
In this case, the clause can safely be removed.
use clause is given, but all elements from
the corresponding package are refered to using a qualified name
(i.e. prefixed by the name of the package). Similarly, for
use type and use all type clauses, all uses of
primitive operators (respectively operations) use a qualified
name. The message starts with “Qualified:”.
In this case, the use clause can safely be removed, but you
may want to keep it for documentation purposes, since the package is
actually used within its scope.
use clause or use all type
clause is given, but the only elements within its scope that do not
use a qualified name are primitive operators. The message starts with
“Operator:”.
In this case, the use or use all type clause can
be replaced by one or several use type clause(s).
use clause is given, but the only elements
within its scope that do not use a qualified name are primitive
operations (including operators, enumeration literals,
subprograms...). The message starts with “Primitive:”
In this case, the use clause can be replaced by one or
several use all type clause(s).
use, use type, or use all
type clause is given within the scope of an enclosing
use, use type, or use all type clause
for the same package (or types declared in the same package), or in a
child unit for some ancestor, or inside its own package. The message
tells the location of the other use clause or the
ancestor. The message starts with “Nested:”
In this case, it is possible that some clauses may be removed, but which ones depends on the structure of your program - there might even be several acceptable combinations.
use clause is given in a package
specification, but all uses are from the corresponding body. The
message starts with “Movable: ”.
In this case, the use clause can safely be moved to the
body, unless it appears in a library package, and there are
unqualified references to its elements from child units.
This rule can be given only once for each subrule.
Ex:
remove: search unnecessary_use_clause (unused); use_type: check unnecessary_use_clause (operator);
The rule provides a variable to define the maximum acceptable number
of use type or use all type clauses for
replacing a use clause.
| Variable | Values | Effect |
| Max_Replacements | <Integer> (default = infinity) | The replacement of use clauses is not performed if it
would generate more than the indicated number of use type
and use all type clauses. |
All subrules generate fixes:
use package clause can be replaced by use
type or use all type clauses, the package name is removed
from the use clause, and use type or
use all type clauses are inserted, unless the number of
inserted clauses exceeds the value of the variable
Max_Replacements. If all packages named by the clause are
removed, the clause as a whole is removed.
This rule checks only usage of use clauses. The rule
“reduceable_scope” can be used to check that use clauses
do not span unnecessarily too wide a scope. See Reduceable_Scope.
A use type or use all type clause that mentions
a type that is not declared in a package specification is always
useless, since it occurs necessarily within the scope of the type,
where all its primitive operations are visible. This is mentionned in
the message (subrule “nested”).
There are some rare cases where the rule may signal that a
use clause is not necessary, where it actually is. There is
no risk associated to this since if you remove the use
clause, the program will not compile.
The first one comes from a limitation of the ASIS standard: if the
only use of the use clause is for making the “root”
definition of a dispatching call visible.
The second one comes from a limitation in ASIS-for-Gnat. This happens
when the only use of the use clause is for making an
implicitely declared operation (an operation which is declared by the
compiler as part of a type derivation) visible, and when:
Since these problems come from intrinsic limitations of ASIS, there is nothing we can do about it. When this happens, you can disable the unnecessary_use_clause rule using the line (or block) disabling feature. See Disabling controls.
Next: Unsafe_Paired_Calls, Previous: Unnecessary_Use_Clause, Up: Rules reference
This rule controls (generic) packages that may be subject to elaboration order dependencies.
<control_kind> unsafe_elaboration;
The rule controls library packages (or generic packages) whose
elaboration calls or instantiates elements from other units (except
language defined units) that are not subject to a pragma
Elaborate or Elaborate_All. The elaboration of such
packages may depend on elaboration order.
Since this rule has no parameters, it can be given only once.
Ex:
check unsafe_elaboration;
If the package contains tasks, they are considered as being part of the elaboration code of the package, since tasks could be started by the elaboration of the package. This is somehow pessimistic in the unlikely case where a package would contain a local task type (whose specification is not part of the package specification) and no task object of that type is declared. Anyway, this could create only false positives, therefore there is no risk associated to it.
Next: Unsafe_Unchecked_Conversion, Previous: Unsafe_Elaboration, Up: Rules reference
This rule controls usage of calls to operations that are normally paired (like P/V operations) and do not follow a "safe" coding pattern.
<control_kind> unsafe_paired_calls (<opening procedure>, <closing procedure> [, <lock type>]); <opening procedure> ::= <entity> <closing procedure> ::= <entity> <lock type> ::= <entity>
The following explanations are given in terms of “locks” since this is the primary use of this rule, however the rule can be used for any calls that need to be properly paired.
The rule can deal with three different kinds of locks:
Since this rule is safety related, staticness is “RM_Static”. See Rules reference.
As usual, the whole syntax for entities is allowed for <entity>. See Specifying an Ada entity name.
An opening block is either a call to the first procedure given to the rule, or an if statement whose condition is a simple reference to a boolean constant (that needs not be static) and whose if path or else path is itself an opening block.
A closing block is either a call to the second procedure given to
the rule, or an if statement whose condition is a simple reference to
a boolean constant (that needs not be static) and whose if path or
else path is itself a closing block, possibly followed by
exit, return, and null statements
(and no others).
An opening and a closing block match if:
if statements have their conditions refer to the
same constant, and their if and else paths contain matching blocks.
The "safe" coding pattern is defined as follows:
exit, return or
goto statements) that transfers control out of the handled
sequence of statements is preceded by a closing block.
Typically, the “safe” pattern corresponds to the following structures:
-- Abstract state machine
begin
P;
-- Do something
if Found then
V;
return
end if
V;
exception
when others =>
V;
-- handle exception
end;
-- Object abstract data type
declare
My_Lock : Lock_Type;
begin
P (My_Lock);
-- Do something
V (My_Lock);
exception
when others =>
V (My_Lock);
-- handle exception
end;
-- Reference abstract data type
declare
Lock_Ptr : constant Lock_Access := Get_Lock;
begin
P (Lock_Ptr);
-- Do something
V (Lock_Ptr);
exception
when others =>
V (Lock_Ptr);
-- handle exception
end;
-- Conditional blocks
declare
Lockable : constant Boolean := ...;
Lock1 : constant Boolean := ...;
begin
if Lockable then
if Lock1 then
Lock (V1);
else
Lock (V2);
end if;
end if;
-- Do something
if Lockable then
if Lock1 then
Unlock (V1);
return;
else
Unlock (V2);
exit;
end if;
end if;
end;
Ex:
check unsafe_paired_calls (Sema.P, Sema.V, Sema.Lock_Access);
The rule provides a variable to control whether opening and closing blocks can contain if statements, or just calls to the procedures.
| Variable | Values | Effect |
| Conditionals_Allowed | off | Only direct calls to the indicated procedures are allowed as opening and closing blocks. |
| on (default) | Calls can be nested in if statements as described above. | |
| Name_As_Given | off (default) | The calls can use any name that refers to the procedures given in the rule (i.e. renamings are followed). |
| on | The calls must use the name given in the rule (i.e. renamings are not followed). |
If the <Lock type> parameter is provided, both procedures must have a single parameter of the given type, it must not correspond to an “out” parameter, and if it corresponds to an “in” parameter, the type must be discrete or access.
This rule can be specified several times, and it is possible to have
the same procedure belonging to several rules. For example, if you
have a Mask_Interrupt procedure that should be matched by
either Unmask_Interrupt or General_Reset (all declared
in package IT_Driver), you can specify:
check unsafe_paired_calls (IT_Driver.Mask_Interrupt,
IT_Driver.Unmask_Interrupt);
check unsafe_paired_calls (IT_Driver.Mask_Interrupt,
IT_Driver.General_Reset);
Normally, the legality of a rule is checked when the command file is parsed, and execution does not start if there is any error. However, the legality of the provided type can be checked only during the analysis. If the type is incorrect for some reason, a proper error message is issued and execution stops immediately.
Due to a weakness of the ASIS standard, dispatching calls are not considered. Especially, this means that the <Lock type> cannot be class-wide. Such calls are detected by the rule “uncheckable”. See Uncheckable.
Due to a size limitation of internal data structures, this rule can be specified at most 32 times.
Next: Usage, Previous: Unsafe_Paired_Calls, Up: Rules reference
This rule controls unchecked conversions between types which are not statically known to have identical sizes.
<control_kind> unsafe_unchecked_conversion
This rule controls instances of Unchecked_Conversion between
types where the following conditions are not met:
Moreover, a special message is given if any of the types is a class-wide type (certainly a very questionable construct!).
Ex:
check unsafe_unchecked_conversion
There are cases where a size clause is given for a type, but AdaControl is unable to evaluate it. This happens especially if the size clause refers to a size attribute of a predefined type, like:
for T'Size use Integer'size;
This can lead to false positives (i.e. detection of instantiations of
Unchecked_Conversion that are actually OK). Such cases are
detected by the rule “uncheckable”. See Uncheckable.
Next: Use_Clauses, Previous: Unsafe_Unchecked_Conversion, Up: Rules reference
This rule controls how certain entitities (variables, constants, types, procedures, functions, exceptions, tasks, protected objects, and generics) are used.
<control_kind> usage
(variable|object|in_parameter|out_parameter|in_out_parameter
{,[not] <location> | read | written | initialized});
<control_kind> usage
(constant {,[not] <location> | read});
<control_kind> usage
(type {,[not] <location> | used});
<control_kind> usage
(procedure {,[not] <location> | called | accessed});
<control_kind> usage
(function {,[not] <location> | called | accessed});
<control_kind> usage
(exception {,[not] <location> | raised | handled});
<control_kind> usage
(task {,[not] <location> | called | aborted});
<control_kind> usage
(protected {,[not] <location> | called});
<control_kind> usage
(generic {,[not] <location> | instantiated});
<control_kind> usage
(all {,[not] <location>});
<location> ::= from_visible | from_private | from_spec | from_task_guard
The first parameter defines the class of entities to be controlled. “object” stands for both “constant” and “variable”, “type” stands for both types and subtypes, and “all” stands for all classes.
If only one parameter is given, usage of all entities belonging to the indicated class are reported . Otherwise, other parameter(s) are keyword that restrict the kind of usage being controlled.
“[not] from_visible”, “[not] from_private”, and “[not] from_spec” restrict entities being checked to those that appear (or not) in (generic) package specifications, in the visible part, in the private part, or in any part, respectively. “[not] from_task_guard” restrict entities being checked to those that appear (or not) in the expression of a guard in a selective accept statement; moreover, usage of the entity in the guard itself and in the corresponding accept statement is not taken into account (i.e. only “external” usage is reported).
“accessed” (available for subprograms only) restricts entities being
checked to those that appear as the prefix of a 'Access or
'Address attribute. Other keywords carry their obvious meaning,
and are allowed only where appropriate. The rule will output the
information only for objects that match all the conditions given.
A combination of parameters can be given only once for each of “check”, “search”, and “count”.
The report includes the kind of unit that declares the entity (normal unit, instantiation, or generic unit), the part where it is declared (visible or private) if it is declared in a (generic) package, and whether the entity is known to be initialized, read, written, raised, handled, called, or aborted, depending on the entity’s class. Some combinations give an extra useful message (for example, a variable which is initialized and read but not written will produce a “could be declared constant” message).
Variables of an access type and variables of an array type whose
components are of an access type (or arrays of an access type, etc.)
are always considered initialized, since they are initialized to
null by the compiler.
Variables that cannot be assigned to (i.e. variables of an array type with some null dimension, or variables of a discrete type whose range includes no values) are specially recognized as “pseudo-constants”: there is no message that they are not written to (since it is not possible), but there is an indication that they are pseudo-constants.
The subrules “procedure” and “function” check only regular subprograms, not protected ones. On the other hand, the subrule “protected” controls all calls to any protected subprogram or entry.
Exceptions raised by calling Raise_Exception and tasks aborted by
calling Abort_Task are properly recognized as exceptions being
raised and tasks being aborted, respectively.
In the case of entities declared in generic packages, the rule will report on usage of the entities for each instantiation, as well as on global usage for the generic itself. Usage for an instantiation will include usage in the generic itself (i.e. if the generic writes to a variable, the variable will be marked as “written” for each instantiation). Usage for the generic itself is the union of all usages in all instantiations (i.e., if a variable from any instantiation is written to, the variable from the generic will be marked as written). Therefore, if the rule reports that a variable in a generic package can be declared constant, it means that no instance of this variable from any instantiation is being written to. But bear in mind that this can be trusted only if all units from the program are analyzed. See limitation.
Note that usage of entities whose declaration is not processed (like,
typically, elements declared in standard packages like
Ada.Text_IO), is not reported. For the same reason, it is not
possible to control usage of predefined operators (since they have no
declaration).
Ex:
-- No variable in package spec; check usage otherwise
Package_Variable: check usage (variable, from_spec);
Constantable : search usage (variable, not from_spec, read,
initialized, not written);
Uninitialized : check usage (variable, not from_spec, read,
not initialized, not written);
Removable : search usage (object, not from_spec, not read);
-- Check in out parameters that could be of out mode
check usage (in_out_parameter, not read);
-- Check exceptions that are never raised
-- generics that are never instantiated
-- and protected objects that are never called
check usage (exception, not raised);
check usage (generic, not instantiated);
check usage (protected, not called);
-- Find how many tasks are declared, and report those
-- that may be aborted
count usage (task);
check usage (task, aborted);
-- Check that variables used in guards are not written from
-- outside of the corresponding accept statement:
check usage (variable, from_task_guard, written);
The following subrules generate fixes (unless they are “from_task_guard”, since usage of these from within guards and accept statement is not taken into account):
constant keyword is added to the
declaration of variables that are initialized, read, but not written.
in for
parameters that are not written. The mode is changed to out
for parameters that are not read. This does not apply to parameters
that are neither read nor written, since they are useless and should
be removed.
Constants that are never used, exceptions that are never raised or handled, tasks that are never called, etc. are suspicious. Moreover, some useful compiler warnings (like those about variables that should be declared constants) are not output for variables declared in library packages, and even in some other contexts (at least with GNAT). This rule can check these kind of things, project wide.
Variables used in guards should not be subject to race conditions. The “From_Task_Guard” location allows to check usage from unprotected places.
Some of these checks make sense only for entities declared in package specifications; for example, variables are often discouraged in package specifications, or need at least some extra control. That’s why it can be useful to restrict some checks to package specifications.
Note that an unspecified parameter in a rule stands for two rules (positive and negative form of the missing parameter). I.e.:
search usage (variable, from_spec, read, written);
is the same as:
search usage (variable, from_spec, read, written, initialized); search usage (variable, from_spec, read, written, not initialized);
Therefore, the following example will complain on the second line that the rule has already been given for this combination of parameters:
search usage (variable, from_spec, read, written); search usage (variable, from_spec, read, written, not initialized);
Note that the notion of constants for this rule includes named numbers.
The report of this rule is output at the end of the run, and is meaningful only for the units that have been processed; i.e., if it reports “variable not read”, it should be understood as “not read by the units given”. In order to have meaningful results, it is therefore advisable to use this rule on the complete closure of the program.
An exception can be raised by passing its 'Identity to a
procedure that will in turn call Raise_Exception (and similarly
for Abort_Task). These cases are not statically determinable,
and therefore not recognized by AdaControl. However, these cases can
be identified by searching the use of the 'Identity attribute
with the following rule:
check entity (all 'Identity);
If an object is the prefix of a 'Access,
'Unchecked_Access, or 'Address attribute, it can be used
through the access (or address) value in ways that are not statically
analyzable. The same happens if objects are targets of dynamic
renamings. Such cases are detected by the rule
“uncheckable”. See Uncheckable.
Due to a weakness of the ASIS standard, it is not possible to know the mode (in, out) of variables used as parameters of dispatching calls. Such variables are considered to be read and written at the point of the call, therefore possibly creating false positives (which is safer than false negatives). Use of such constructs is detected by the rule “uncheckable”. See Uncheckable.
Next: With_Clauses, Previous: Usage, Up: Rules reference
This rule controls usage of use clauses.
<control_kind> use_clauses
[([<subrule>,] <package name> {, <package name>})];
<subrule> ::= package | local | global |
type | type_local | type_global |
all_type | all_type_local | all_type_global
The rule controls every use, use type, or
use all type clause, except those that name one of the
mentioned packages/types. It is therefore possible to allow
use, use type or use all type clauses
just for certain packages/types.
The first parameter is a subrule keyword:
use clauses.
use clauses that appear in
context clauses (i.e. together with the with clauses)
use clauses that appear as
declarations.
use type clauses
use
type clauses that appear in context clauses (i.e. together with the
with clauses)
use type clauses that appear as declarations.
use all type clauses
use all type clauses
that appear in context clauses (i.e. together with the with
clauses)
use all type clauses that appear as declarations.
Without parameter, the rule defaults to “package”.
This rule can be given at most once for each of check, search and count. This way, it is possible to have a level considered a warning (search), and one considered an error (check).
Ex:
-- Global use clauses are disallowed, local ones only for IO: check use_clauses (global); check use_clauses (local, Ada.Text_IO, Ada.Wide_Text_IO); -- No use type in context clauses, count types that are "use type"'d check use_clauses (type_global); count use_clauses (type);
All subrules generate fixes:
Previous: Use_Clauses, Up: Rules reference
This rule controls with clauses that should be removed or
moved to a better place.
<control_kind> with_clauses [(<subrule> [, <subrule>])];
<subrule> ::= multiple_names | reduceable | inherited |
limited | private | limited_private
The parameters are subrule keywords:
multiple_names controls any with clause that
mentions more than one unit name.
reduceable reports:
with clauses, i.e. clauses given more than once
for the same unit. This includes the case where the same
with clause is given in a specification and the
corresponding body, and the case of renamings of a same unit
(i.e. Text_IO and Ada.Text_IO). Note that giving a
with clause in a unit, and repeating it in a child unit (or
subunit) is not considered redundant. This also includes the case
of a with clause for an ancestor of the current unit.
with clauses, i.e. when nothing from the withed unit
is referenced in the corresponding unit. The rule signals when a withed
unit is not used in a unit, but used in one or more of its subunits. If
an unused with clause is given on a package specification, the
message reminds that it migh be useful for child units.
with clauses, i.e. when the withed unit is not
used in the specification, but only in the body, and should be moved
to the body, or when the withed unit is only used in the private part,
and could be replaced by a private with.
inherited controls child units and subunits that reference a
unit which is not directly withed, i.e. when withed only from a parent
(or enclosing) unit. Although Ada rules imply that a with
clause carries on to child units and subunits, it can be considered
better practice to ensure that every compilation unit withes directly
the units it needs.
limited controls any limited with clause.
private controls any private with clause.
limited_private controls any limited
private with clause.
Each of the subrules can be given at most once. If no keyword is given, all subrules are activated.
Ex:
check with_clauses (multiple_names, reduceable); search with_clauses (inherited);
The rule provides a variable to control the handling of
private with.
The rule provides a variable to control the handling of package names
in in use clauses.
| Variable | Values | Effect |
| Check_Private_With | off | Do not issue a message when a with can be replaced with a
private with (useful in Ada 95 mode). |
| on (default) | Issues a message when a with can be
replaced with a private with. | |
| Ignore_Use_Clause | off | Names appearing in use clauses are treated like any other identifier (see tip below). |
| on (default) | Package names appearing in use clauses are not considered as a usage of the package. |
The following subrules generate fixes:
with clause is replaced by
several with clauses, each with only one name.
with is not
needed): The unnecessary package is removed from the clause. If all
packages named by the clause are removed, the clause as a whole is
removed.
with that can be made private) : the keyword
private is added to the declaration.
with clause for the inherited package is added
just before the beginning of the unit.
A with clause can safely be removed if it is unused, and no
child unit (or subunit) reports that the unit is inherited.
Normally, use of a package name in a use clause is not
considered a usage of the package; clearly, the with clause
can (and should) be removed (or moved) if the only use of the package
is in use clauses (removing or moving the use
clauses by the same token). However, some programming rules may require
placing use clauses in certain places, forcing the corresponding
with clause. Set the variable Ignore_Use_Clause to
off to make sure that a use clause does mark the
with clause as necessary.
Next: Specifying an Ada entity name, Previous: Rules reference, Up: Top
In most projects, there are programming rules that define the way a program should be written. AdaControl performs controls, i.e. it finds occurrences of certain kinds of constructs. In this chapter, we give examples of commonly found programming rules, and how the corresponding controls can be written.
| • Migrating from Gnatcheck | ||
| • command files provided with AdaControl | ||
| • Automatically checkable rules | ||
| • Rules that need manual inspection |
Next: command files provided with AdaControl, Previous: Examples of using AdaControl for common programming rules, Up: Examples of using AdaControl for common programming rules
The file gnatcheck.aru in directory rules gives the
AdaControl equivalents of rules checked by Gnatcheck. This version of
AdaControl covers most of Gnatcheck rules. For rules where Gnatcheck
requires a parameter, the AdaControl rule is given for the default
value, or with an example value. Small differences in semantics are
indicated by a comment that starts with "Difference:".
This file is not intended to be used directly, but as an example on how to convert Gnatcheck rules into AdaControl rules. Note that in many cases, AdaControl is much more general than Gnatcheck. The file follows as strictly as possible the rules as defined by Gnatcheck, but if you are migrating from Gnatcheck to AdaControl, you may want to use the more powerful forms provided by AdaControl.
Next: Automatically checkable rules, Previous: Migrating from Gnatcheck, Up: Examples of using AdaControl for common programming rules
The rules directory provides also rules files that can be
sourced to enforce some commonly encountered general rules.
Identifiers from Standard shall not be redefined
Use file no_standard_entity.aru.
Identifiers from System shall not be redefined
Use file no_system_entity.aru.
Predefined IO packages shall not be used
Use file no_io.aru.
Standard package XXX shall not be used
File no_standard_unit.aru controls usage of all standard
packages. Comment out those that you do want to allow.
Obsolescent features shall not be used
Use file no_obsolescent_features.aru. Not all obsolescent features are
controlled, but most of them (those that are most worth checking) are.
Gnat specific attributes shall not be used
Use file no_gnat_attribute.aru
Features from annex X shall not be used
Use file no_annex_X.aru.
The Ravenscar profile shall be enforced
Use file ravenscar.aru.
Note that not all of the restrictions of the Ravenscar profile are currently controlled, but many are, and we expect later releases of AdaControl to increase the number of controlled features. In some cases (like “Detect_Blocking”), AdaControl does a better job than the profile, since it can detect statically situations that the profile only requires to be detected at run-time. The command file is also slightly more restrictive than the profile; for example, the restriction “no_task_allocation” only disallows task allocators, while this command file controls the declaration of access types on tasks.
NASA coding guidelines shall be enforced
Use file nasa.aru. This file is an example of how to convert
guidelines (available from
https://www.stephe-leake.org/ada/code_standards_ada.pdf) into an
AdaControl command file.
Ada 83 unit names shall not be used (i.e. use Ada.Text_IO, not Text_IO)
Use file no_83_unit_name.aru.
New reserved words of Ada 2005/2012 shall not be used
Use file reserved_2005.aru. (the file name mentions only 2005,
but it checks also for 2012 - after all, there is only one extra
reserved word).
Measurements for the SQALE method
AdaControl can provide measurements required by the SQALE quality
measurement method. The corresponding file is SQALE.aru.
For information about the SQALE method, please refer to J-P Rosen’s paper at https://www.adalog.fr/publicat/sqale.pdf
Next: Rules that need manual inspection, Previous: command files provided with AdaControl, Up: Examples of using AdaControl for common programming rules
Below are examples of rules that can be directly checked by AdaControl.
Goto statement shall not be used
check statements (goto);
Functions shall not have out or in out parameters (Ada 2012)
check parameter_declarations (out_parameters, max 0, function); check parameter_declarations (in_out_parameters, max 0, function);
Short circuit forms should be preferred over corresponding logical operators
Use_Short_Circuit: search expressions (and, or);
Aggregates should be used for full assignments to structured variables, unless it is a record with a single component
check multiple_assignments (groupable, given 2, ratio 100);
All loops that contain exit statements must be named, and the name must be given in the exit statement
check statements (unnamed_loop_exited); check statements (unnamed_exit);
All type names must start with “T_”
check naming_convention (type, "^T_");
All program units must repeat their name after the “end”
check style (no_closing_name);
Pragma Suppress is not allowed
check pragmas (suppress);
Ada tasking must not be used
check declarations (task);
“=” and “/=” shall not be used between real types
check expressions (real_equality);
All tasks must provide an exception handler that calls “Failure” in the case of an unhandled exception
check exception_propagation (task); check silent_exceptions (failure);
Unchecked_Conversion shall not be used
check entities (ada.unchecked_conversion);
No global variable shall be declared in the visible part of a package specification
check usage (variable, from_spec);
Predefined numeric types of the language shall not be used
check entities (standard.Integer,
standard.short_integer,
standard.long_integer,
standard.Float,
standard.short_float,
standard.long_float);
Access to subprograms shall not be used
check declarations (access_to_sp);
Abort statements shall not be used
check statements (abort);
There shall be only one instantiation of Ada.Numerics.Generic_Elementary_Functions for each floating point type
-- Put a --##RULE LINE OFF GEF -- for the one which is allowed GEF: check Instantiations (Ada.Numerics.Generic_Elementary_Functions);
A local item shall not hide an outer one with the same name
check Local_Hiding;
There shall be no IOs in exception handlers
check entity_inside_exception (ada.Text_IO.put, ada.Text_IO.put_line,
ada.Text_IO.get, ada.Text_IO.get_line);
Note that this checks for all overloaded procedures, but only those dealing with characters and strings (those defined directly within Ada.Text_IO). If the names “get” and “put” are not used for anything else than IOs, a more general form can be given as:
check entity_inside_exception (all get, all put,
all get_line, all put_line);
This will check that no entity with the corresponding names appear in exception handlers.
Exceptions shall not be used
No_Exception: check declarations (exception, handlers); No_Exception: check statements (raise); No_Exception: check entities (Ada.Exceptions);
This will check that no exception is declared, no exception handler is
provided, and no exception is raised, not even through the services of
the package Ada.Exceptions.
No procedure exported to C shall propagate exceptions
check exception_propagation (interface, C);
There shall be no Unchecked_Conversion to or from Address
check instantiations (ada.unchecked_conversion, system.address); check instantiations (ada.unchecked_conversion, <>, system.address);
There shall be no use clause except for Text_IO
check use_clauses(ada.text_IO);
Use explicit list of values in case statements rather than “when others”if the “when others” would cover less than 10 values
check Case_Statement(min_others_span, 10);
If a block is more than 20 lines long, it must be named
check Max_Size(unnamed_block, 20);
Exceptions shall not be handled except by main program
check declaration (handlers)
This check will be disabled for the exception handler of the main program.
Each unit has a header starting with a fixed format, and must contain at least 10 lines of comments
check header_comments (model, "header.txt"); check header_comments (minimum, 10);
The file header.txt contains the required header (as regexps), like:
^--*{50}$
^-- This is a header$
Previous: Automatically checkable rules, Up: Examples of using AdaControl for common programming rules
Below are examples of rules that require manual inspection, but where AdaControl can be used to identify suspicious areas.
All usages of the ’ADDRESS attribute shall be justified and documented
search entities (all 'address);
Specifying an address for a variable shall be restricted to hardware interfacing
search representation_clauses(address);
There shall be no memory leakage
search Allocators;
This rule identifies all allocations, and thus can be used to check that all allocated elements are properly deallocated.
Next: Definition of type categories, Previous: Examples of using AdaControl for common programming rules, Up: Top
Next: Overloaded names, Previous: Specifying an Ada entity name, Up: Specifying an Ada entity name
Many rules can take Ada entities as parameters. Each time a rule uses
the syntactic term <entity>, it refers to an Ada entity that can be
specified with the following syntax:
<entity> ::= <full_name> | "all" <simple_name> | "all" <attribute>
<full_name> is the full name of the Ada entity, using normal
Ada dot notation (with some extensions, see below). Full name means
that you give the full expanded name, starting from a compilation
unit. This name must be the actual full name, i.e. it must not include
any renaming (otherwise the name will not be recognized). For example,
the usual Put_Line must be given as
Ada.Text_IO.Put_Line, not as
Text_IO.Put_Line. Predefined elements (Integer,
Constraint_Error) must be given in the form
Standard.Integer or Standard.Constraint_Error, since
they are logically declared in the package Standard.
<simple_name> is a single identifier, possibly followed by
overloading information. No qualification is allowed.
<Attribute> is an attribute name, including the quote. No
overloading information is allowed.
<full_name> designates a single entity or several overloaded
entities declared in the same place (as identified by the prefix),
while all <simple_name> designates all identifiers with the
given name in the program, irrespectively of where they
appear. all <Attribute> designates all occurrences of the given
attribute, irrespectively of what the attribute applies to.
A utility is provided with AdaControl to help you find the full name of an entity. See pfni. If you are using GPS with AdaControl plug-ins, it can be accessed directly from the contextual menu. See Contextual menu.
Next: Enumeration literals, Previous: General syntax, Up: Specifying an Ada entity name
In Ada, names can be overloaded. This means that you can have several
procedures P in package Pack, if they differ by the
types of the parameters. If you just give the name Pack.P as
the <entity>, the corresponding rule will be applied to all
elements named P from package Pack. If you want to
distinguish between overloaded names, you can specify a profile after
the element’s name. A profile has the syntax:
"{" [ ["access"] <type-name>
{ ";" ["access"] <type-name> } ]
["return" <type-name>] "}"
You must specify the type name, even if the <entity>
declaration uses a subtype of the type; this is because Ada uses types
for overloading resolution, not subtypes. Anonymous access parameters
are specified by putting access in front of the type name. An
overloaded name for a procedure without parameters uses just a pair of
empty brackets. If the subprogram is a function, you must provide the
return <type-name> part for the return type of the
function. The types must also be given as a unique name,
i.e. including the full path: if the type is T declared in
package Pack, you must specify it as Pack.T. As a
convenience, the Standard. is optional for predefined types, so
you can write Standard.Integer as Integer. There is no
ambiguity, since a type is always declared within some construct. Note
that omitting Standard works only for types that are part
of the profile used to distinguish between overloaded Ada entities but
that the Ada entity name must always contain Standard if it is a
predefined element.
Overloaded names can be also be used with the all <simple_name>
form of the <entity>. In this case, the rule will be applied to
all names that are subprograms with the given identifier and matching
the given profile, irrespectively of where they appear.
Note that if you use an overloaded name, all overloadable names that are part of the <entity>, including those of the profile, must use the overloaded syntax. For example, given the following program
procedure P is
procedure Q (I : Integer) is
...
end Q;
procedure Q (F : Float) is
...
end Q;
begin
...
end P;
If you want to distinguish between the two procedures Q, you
must specify them as P{}.Q{Integer} and
P{}.Q{Float} (note the P{} which specifies an
overloaded name for a procedure P without parameters).
The names of entities which can not be overloaded (like package,
exception, …) must not be suffixed by braces
(e.g. Ada.Text_IO.Put_Line{Standard.String}).
Next: Operators, Previous: Overloaded names, Up: Specifying an Ada entity name
Following normal Ada rules, an enumeration literal is considered a parameterless function. If you want to distinguish between overloaded enumeration literals, you can use overloaded names for them. For example, given:
package Pack is type T1 is (A, B); type T2 is (B, C); end Pack;
Ada entities names are:
Pack.B{return Pack.T1}
Pack.B{return Pack.T2}
Next: Attributes, Previous: Enumeration literals, Up: Specifying an Ada entity name
AdaControl handles operators (i.e. functions like "+")
correctly. Of course, you must specify such operations using normal
Ada syntax: if you define the integer type T in package
Pack, an overloaded name for the addition would be
Pack."+"{Pack.T; Pack.T return Pack.T}.
Next: Anonymous constructs and extended return statements, Previous: Operators, Up: Specifying an Ada entity name
It is also possible to designate attributes of entities, using the
normal notation (i.e. Standard.Integer'First). If the name of
an attribute which is a function appears in a name that uses the
overloaded syntax, it is not necessary (and actually not allowed) to
provide its profile, since there is no possible ambiguity in that
case. For example, given:
procedure P (I : Integer) is type T is range 1 .. 10; begin ... end P;
You can designate the 'Image attribute for type T as
P{Standard.Integer}.T'Image (the profile of the 'Image
function is not given, as would be necessary for a normal function).
To designate all occurrences of an attribute, use all in
front of the attribute. To designate only occurrences of an attribute
whose prefix is a (sub) type (but any type or subtype), give it as
type'Attr (i.e. the keyword “type” is put in front of the
quote).
all may be used in place of an attribute name to mean “any
attribute”. See examples below.
check entities (all 'Image); -- Find all occurrences of 'Image
check entities (all type'Length); -- Find all occurrences of 'Length
-- applied to a type
check entities (Standard.Integer'all); -- Find all attributes applied
-- to type Integer
Check entities (all type'all); -- Find all attributes applied
-- to a type
check entities (all 'all); -- Find all attributes
Next: Record and protected types components, Previous: Attributes, Up: Specifying an Ada entity name
There is a special case for elements that are defined (directly or
indirectly) within unnamed loops or block statements. Everything
happens as if the unnamed construct was named
_anonymous_. Therefore if you have the following program:
procedure P is
begin
for I in 1..10 loop
declare
J : Integer;
begin
...
end;
end loop;
end P;
You can refer to I as P._anonymous_.I, and to J
as P._anonymous_._anonymous_.J.
Similarly, an extended return statement is considered “named” return.
Therefore if you have the following program:
function F return Integer is
I : Integer;
begin
return I : Integer do
...
end return;
end F;
You can refer to the I declared in F as F.I, and
to the return object I as F.return.I.
Next: Formals of access to subprogram types, Previous: Anonymous constructs and extended return statements, Up: Specifying an Ada entity name
You can designate the name of a record or protected type component (a “field” name), but to identify it uniquely, you must precede its name by the name of the type. This is a small extension to Ada syntax, but it is the simplest and most natural way to deal with this case. For example, given:
procedure P is
type T is
record
Name : Integer;
end record;
...
The Ada entity name is P.T.Name.
Next: Limitation, Previous: Record and protected types components, Up: Specifying an Ada entity name
Similarly, you can designate the formal of an access to subprogram type by prefixing it by the access type. For example, given:
procedure P is type T is access procedure (X : Integer); ...
The Ada entity name of the formal is P.T.X.
Due to a limitation of ASIS for GNAT, it is not possible to specify a profile with predefined operators; predefined operators without a profile work normally.
-- This will not recognize "<" on Standard.Integer:
check entities (Standard."<"{Standard.Integer,
Standard.Integer
return Standard.Boolean});
-- This will correctly recognize all predefined "<":
check entities (Standard."<");
Next: Syntax of regular expressions, Previous: Specifying an Ada entity name, Up: Top
Many rules can be parameterized with applicable types. A type name can generally be given, but many
rules also accept type categories. Each time a rule uses the syntactic term <category>, it
refers to a type category defined by the following syntax:
<category> ::= <> | () | access | array | delta |
digits | extension | interface | mod | new |
private | protected | range | record | tagged |
task
The category of types are defined as follows:
Depending on the rule, some of these categories may not be applicable. For example, a type derived from an integer type is both a derived type and an integer type, and which category should be prefered depends on the purpose of the rule. In the description of the rule, it is said to:
The “<>” category matches any type, and is allowed only by rules that need a list of categories, to express that no special category is expected at the given location.
Next: Syntax of format strings, Previous: Definition of type categories, Up: Top
The following syntax gives the complete definition of regular
expressions, as used by several rules. It is taken from the
specification of the package gnat.regpat, where additional
information is available.
regexp ::= expr
::= ^ expr -- anchor at the beginning of string
::= expr $ -- anchor at the end of string
expr ::= term
::= term | term -- alternation (term or term ...)
term ::= item
::= item item ... -- concatenation (item then item)
item ::= elmt -- match elmt
::= elmt * -- zero or more elmt's
::= elmt + -- one or more elmt's
::= elmt ? -- matches elmt or nothing
::= elmt *? -- zero or more times, minimum number
::= elmt +? -- one or more times, minimum number
::= elmt ?? -- zero or one time, minimum number
::= elmt { num } -- matches elmt exactly num times
::= elmt { num , } -- matches elmt at least num times
::= elmt { num , num2 } -- matches between num and num2 times
::= elmt { num }? -- matches elmt exactly num times
::= elmt { num , }? -- matches elmt at least num times
non-greedy version
::= elmt { num , num2 }? -- matches between num and num2 times
non-greedy version
elmt ::= nchr -- matches given character
::= [range range ...] -- matches any character listed
::= [^ range range ...] -- matches any character not listed
::= . -- matches any single character
-- except newlines
::= ( expr ) -- parens used for grouping
::= \ num -- reference to num-th parenthesis
range ::= char - char -- matches chars in given range
::= nchr
::= [: posix :] -- any character in the POSIX range
::= [:^ posix :] -- not in the POSIX range
posix ::= alnum -- alphanumeric characters
::= alpha -- alphabetic characters
::= ascii -- ascii characters (0 .. 127)
::= cntrl -- control chars (0..31, 127..159)
::= digit -- digits ('0' .. '9')
::= graph -- graphic chars (32..126, 160..255)
::= lower -- lower case characters
::= print -- printable characters (32..127)
::= punct -- printable, except alphanumeric
::= space -- space characters
::= upper -- upper case characters
::= word -- alphanumeric characters
::= xdigit -- hexadecimal chars (0..9, a..f)
char ::= any character, including special characters
ASCII.NUL is not supported.
nchr ::= any character except \()[].*+?^ or \char to match char
\n means a newline (ASCII.LF)
\t means a tab (ASCII.HT)
\r means a return (ASCII.CR)
\b matches the empty string at the beginning or end of a
word. A word is defined as a set of alphanumerical
characters (see \w below).
\B matches the empty string only when *not* at the
beginning or end of a word.
\d matches any digit character ([0-9])
\D matches any non digit character ([^0-9])
\s matches any white space character. This is equivalent
to [ \t\n\r\f\v] (tab, form-feed, vertical-tab,...
\S matches any non-white space character.
\w matches any alphanumeric character or underscore.
This include accented letters, as defined in the
package Ada.Characters.Handling.
\W matches any non-alphanumeric character.
\A match the empty string only at the beginning of the
string, whatever flags are used for Compile (the
behavior of ^ can change, see Regexp_Flags below).
\G match the empty string only at the end of the
string, whatever flags are used for Compile (the
behavior of $ can change, see Regexp_Flags below).
... ::= is used to indication repetition (one or more terms)
Embedded newlines are not matched by the ^ operator. It is possible to retrieve the substring matched a parenthesis expression. Although the depth of parenthesis is not limited in the regexp, only the first 9 substrings can be retrieved.
The operators ’*’, ’+’, ’?’ and ’{}’ always match the longest possible substring. They all have a non-greedy version (with an extra ? after the operator), which matches the shortest possible substring.
For instance:
regexp="<.*>" string="<h1>title</h1>" matches="<h1>title</h1>" regexp="<.*?>" string="<h1>title</h1>" matches="<h1>"
’{’ and ’}’ are only considered as special characters if they appear in a substring that looks exactly like ’{n}’, ’{n,m}’ or ’{n,}’, where n and m are digits. No space is allowed. In other contexts, the curly braces will simply be treated as normal characters.
Note that if you compiled AdaControl with the
String_Matching_Portable package, only basic wildcards are
available, i.e. only “*” and “?” are supported, where “*”
matches any string of character and “?” matches a single character.
Next: Non upward-compatible changes, Previous: Syntax of regular expressions, Up: Top
The Format, Format_Header, Count_Format, and
Count_Format_Header variables contain a string value that
defines how messages and count reports are formated (like the format
of the printf subprogram of the C language). These variables
can be set normally with the “set” command. See Set command. In these strings, some special character sequences are
substituted with various pieces of information; any other character or
unrecognized sequence is output as is.
The special sequence starts with a percent (“%”) character,
is optionally followed by a double-quote or back-slash character
(“"” or “\”), and a key letter. If the double-quote
or back-slash character is present, every double-quote in the
substitution text will be preceded by that character. This is useful
when the substitution is part of quoted text, like CSV for
example. See examples below.
The recognized key letters and their substitution are:
%c, %"c, %\cThe column number of the message.
%d, %"d, %\dThe defaulted label. It is the control label if there is one, the rule name otherwise.
%DThe current date, in ISO format.
%EThe current count of error (“check”) messages.
%f, %"f, %\fThe name of the file that contains the offending construct. The name uses a short or long format, depending on the value of the variable Long_File_Name.
%k, %"kThe kind of the control (“check” or “search”, unless redefined by the user). The value returned for the “check” and “count” value can be changed by setting the variables Check_Message or Search_Message. “Count” is never returned, since “count” controls are handled separately.
%lThe line number in the file.
%m, %"m, %\mThe message issued by the control. In a count format, the message is the number of occurrences.
%nA new line.
%rThe rule name of the control.
%s, %"s, %\sThe full source line that contains the offending construct.
%SA sequence number. The sequence starts at 1, and is incremented each time it is used. The sequence number can be reset to any value with a “set sequence” command.
%t, %"t, %\tThe label (tag) of the control if any, the empty string otherwise.
%TThe current time, in ISO format.
%WThe current count of warning (“search”) messages.
%!An indicator of the position of the error (a “!” character, preceded
by column-1 spaces; to be used with %s).
%[ and %]The content of the format between “%[” and “%]” is substituted only if it contains a substitution that didn’t return an empty string or a new_line, otherwise it is replaced by an empty string. “%[ ... %]” sequences can be nested.
%%A percent character.
In a header, the substitution related to a specific message (“%f”, “%m” etc.) are those of the first message. Count messages recognize only “%d”, “%D”, “%E”, “%m”, “%n”, “%S”, “%T”, and “%W”.
Examples:
-- Gnat format: set format "%[%f:%l:%c: %]%k: %d: %m" -- CSV format (with header): set format_header ~"file","line","col.","key","label","rule","message"~ set format ~"%"f","%"l","%"c","%"k","%"t","%"r","%"m"~
The “rules” directory of the distribution of AdaControl contains the files “toml.aru” and “yaml.aru” that can be sourced from other command file to get output in Toml or Yaml formats, respectively.
Previous: Syntax of format strings, Up: Top
This chapter is intended to users of a previous version of AdaControl, who want to migrate command files to the latest version. Although we understand the burden of non upward-compatible changes, we consider that making AdaControl more powerful and easier to use is sometimes more important than strict compatibility. Moreover, in most cases the changes are very straightforward and can be done easily by hand, or with scripts if many files are involved.
The various forms of renaming declarations have moved from the rule “declarations” to their own rule “renaming_declarations” (with more possibilities). The correspondance is as follows:
check declarations (renaming); => check renaming_declarations [(all)]; check declarations (function_call_renaming); => check renaming_declarations (function_call); check declarations (non_identical_renaming); => check renaming_declarations (not identical all); check declarations (operator_renaming); => check renaming_declarations (operator function); check declarations (not_operator_renaming); => check renaming_declarations (not operator function); check declarations (non_identical_operator_renaming); => check renaming_declarations (not identical operator function); check declarations (library_unit_renaming); => check renaming_declarations (library all); check declarations (renaming_as_body); => check renaming_declarations (as_body all); check declarations (renaming_as_declaration); => check renaming_declarations (not as_body all); check declarations (synonym_renaming); => check renaming_declarations (synonym all);
The subrule “Negative_Condition” has been removed. It was redundant with “simplifiable_statements (if_not)”, except that it detected less cases.
Change:
check Style (negative_condition);
to:
check Simplifiable_Statements (if_not);
Counts reports are now printed in the same output as Stats reports.
The Format variable now accepts two kinds of values, Identifier (as in previous versions), and string values. See Output format for more details.
The default file path is now in short version instead of long.
This rule has been changed to three subrules of the new rule
actual_parameters. In short, change:
check default_parameter (proc, param, used); check default_parameter (proc, param, not_used); check default_parameter (proc, param, positional);
to:
check actual_parameters (default_used, proc, param); check actual_parameters (default_not_used, proc, param); check actual_parameters (default_positional, proc, param);
The subrules dispatching_call and redispatching_call do
not control function calls anymore, since these are controlled (more
appropriately) by subrules of the expressions rule. In short, change:
check statements (dispatching_call, redispatching_call);
to:
check statements (dispatching_call, redispatching_call);
check expressions (dispatching_function_call,
redispatching_function_call);
The subrule raise_nonpublic does not control any more the
raising of exceptions declared in visible parts of packages other than
the one that contains the raise statement; these are now
controlled by the subrule raise_foreign. It also now accepts
(i.e. does not control) exceptions declared in the visible part of an
ancestor of the package that contains raise statement.
Previous versions mentionned in the command line syntax that “-r” and “-s” could be used together, but the effect of this combination was not documented. It has now a documented (and slightly different, but more useful) effect. See Input units and Generating a units list.
These rules use the concept of “location” to restrict the places where some constructs are controlled. It is now possible to specify “not” in front of a location keyword. As a consequence, the keyword “nested” has been removed, as it was the same thing as “not library”. In short, change:
check declarations (nested procedure);
to:
check declarations (not library procedure);
The extension of aspects to more rules required a slight change in the syntax of the “component” subrule: the keywords “packed”, “sized”, and “component_sized” have been changed to “pack”, “size”, and “component_size”, respectively.
Due to new functionalities, and expecting more in the future, the rule has been renamed to “Assignments”.
The syntax has been changed, due to the introduction of “indexing”. Moreover, the rule was not consistent, in that the result of “none” was affected by the presence or absence of “logical” (without “logical”, “none” included all types, while with it, it counted only those not counted with “logical”). If you want that exact same behaviour (which might not be desirable), change:
-- (1)
check no_operator_usage (none);
-- (2)
check no_operator_usage (logical);
-- (3)
check no_operator_usage (none, logical)
-- or no parameters
to:
-- (1)
check no_operator_usage(ignore indexing, ignore logical);
-- or no parameters
-- (2)
check no_operator_usage (logical);
-- (3)
check no_operator_usage (not logical),
check no_operator_usage (logical);
Due to the necessity of avoiding a syntactic ambiguity in the new subrule “type”, the keyword “all” is no more allowed in the syntax for the subrule “min_integer_span” (specifying neither “variable” or “constant” still means the subrule applies to both, as before). Change:
count object_declarations (min_integer_span, all 8);
to:
count object_declarations (min_integer_span, 8);
The subrule “exit” was documented as controlling all exit
statements, but it did not report exits from for and
while loops if “exit_for_loop” (respectively
“exit_while_loop”) was also specified. It now behaves as documented,
i.e. it controls all exit statements.
Note that if you want separate messages for each kind of loop, the new rule “exit_plain_loop” controls exit from plain loops.
The subrule “positional_association” is now a rule of its own, “positional_associations”. The order of parameters is different, due to various subrules of the new rule. Typically, change:
check style (parameter_association, call, 1);
to:
check positional_associations (all, 1, call);
Note that the new rule distinguishes between regular array aggregates and aggregates used for enumeration representation clauses.
Modes of the subrules “parameter_order” and “formal_parameter_order” are now separated by “|”. With the previous syntax, forgetting a comma was changing the meaning of the rule without introducing a syntax error. Typically, change:
check style (parameter_order, in defaulted_in, out in_out);
to:
check style (parameter_order, in | defaulted_in, out | in_out);
Due to the introduction of extra parameters for allowed patterns, it is no more possible to specify the rule several times in the same command. Change:
check local_hiding (strict, overloading);
to:
check local_hiding (strict); check local_hiding (overloading);
The special subrule “overloading_short” has been replaced by a rule variable to choose the report format. Change:
check local_hiding (overloading_short);
to:
set local_hiding.overloading_report compact; check local_hiding (overloading);
The value given is now the nesting level (consistent with the rule name), no more the maximum depth. This is more natural (Max_Nesting(1) means that the construct can be nested once), but it is one less than in previous versions. For example, change:
check Max_Nesting (5);
to:
check Max_Nesting (4);
The subrules have been generalized, using the same syntax for bounds as other rules. Change:
check parameter_declarations (min_parameters, 1); check parameter_declarations (max_parameters, 5); check parameter_declarations (max_defaulted_parameters, 3);
to:
check parameter_declarations (all_parameters, min 1, max 5); check parameter_declarations (defaulted_parameters, max 3);
The subrule Real_Equality does not control user-defined
equality operators any more. This is intended to be more of an
improvement than an incompatibily.
Since the number of subrules is growing, and do not only address ‘special” comments, this rule has been renamed to “comments”.
Due to a bug/feature of the GPS interface, if a units file was specified, it did not reappear later in the corresponding box of the Switch/AdaControl dialog. This has been fixed, but you must reenter the units file name in the dialog.
The introduction of categories made some subrules syntactically ambiguous or redundant. In consequence, the subrules “derived_record”, “extension_record”, and “tagged_record” have been removed, and the subrules “record”, “incomplete_record”, and “non_contiguous_record” have been renamed as “layout”, “incomplete_layout”, and “non_contiguous_layout” respectively. Change:
check representation_clause (derived_record); check representation_clause (extension_record); check representation_clause (tagged_record); check representation_clause (record); check representation_clause (incomplete_record); check representation_clause (non_contiguous_record);
to:
check representation_clause (new layout); check representation_clause (extension layout); check representation_clause (tagged layout); check representation_clause (layout); check representation_clause (incomplete_layout); check representation_clause (non_contiguous_layout);
The subrule “Max_Length” has been changed to “Length”, with the possibility to specify both min and max values. Change:
check array_declarations (max_length, 100);
to:
check array_declarations (length, max 100);
The subrule names “initialized_record_field”, “uninitialized_record_field”, “initialized_protected_field”, and “uninitialized_protected_field” have been changed to “initialized_record_component”, “uninitialized_record_component”, “initialized_protected_component”, and “uninitialized_protected_component”, respectively, to be more consistent with official Ada terminology. Change:
check declarations (initialized_record_field,
uninitialized_record_field,
initialized_protected_field,
uninitialized_protected_field);
to:
check declarations (initialized_record_component,
uninitialized_record_component,
initialized_protected_component,
uninitialized_protected_component);
The subrule “aliased” has been split into “aliased_constant” and “aliased_variable”. The old rule controlled both at the same time, but did not control aliased components (there are now other subrules to that effect). Change:
check declarations (aliased);
to:
check declarations (aliased_constant, aliased_variable);
The <place> is no more allowed to be “all”, because it was ambiguous with the “all <name>” syntax of <entity>. If you used “all”, duplicate the control with “calls” and “instantiations”. Change:
My_label : check default_parameter (all, ...);
to:
My_label : check default_parameter (calls, ...),
check default_parameter (instantiations, ...);
By default, variables declared directly within (generic) package specifications and bodies are no more checked. To get the previous behaviour, add the “package” modifier. Change:
check improper_initialization (variable);
to:
check improper_initialization (package variable);
If the output format is CSV or CSVX, the file name, line number and column number are generated as three different spreadsheet columns, instead of forming a single message. This makes it easier to use a spreadsheet program for per-file statistics.
Due to the introduction of the “positional” keyword, “not used” is now spelled “not_used”. Change:
check default_parameter (proc, param, not used);
to:
check default_parameter (proc, param, not_used);
This rule has been changed into a subrule of the (new) rule “Dependencies”. Change:
check Other_Dependencies (pack1, pack2);
to:
check Dependencies (others, pack1, pack2);
Due to the introduction of another subrule, add “pattern” as the first parameter to the rule. Change:
check Special_Comments ("TBSL");
to:
check Special_Comments (pattern, "TBSL");
The “raise” subrule now reports all occurrences of the raise
statement, even if another control is applicable to the same statement.
The “reraise” subrule now reports calls to
Ada.Exceptions.Reraise_Occurrence.
The “raise_standard” subrule now reports exceptions raised by calls to
Ada.Exceptions.Raise_Exception.
This rule now allows the specification of both min and max values for each subrule. Subrule names have been changed accordingly. Change:
check Case_Statement (max_range_span, 5); check Case_Statement (max_values, 10); check Case_Statement (min_others_span, 4); check Case_Statement (min_paths, 6);
to:
check Case_Statement (range_span, max 5); check Case_Statement (values, max 10); check Case_Statement (others_span, min 4); check Case_Statement (paths, min 6);
This rule has been changed into a subrule of the (new) rule “Parameter_Declarations”. Change:
check Max_Parameters (10);
to:
check Parameter_Declarations (Max_Parameters, 10);
The message is now syntactically a string, and must always be enclosed in double quotes (quotes were optional in previous versions).
If a “source” command is given in a command file, and the sourced file is given with a relative path, it is interpreted relatively to the sourcing file (it was interpreted relatively to the current directory previously). This should make “chained” sourcing easier, since the interpretation does not depend on where the sourcing file is being called from.
This rule is now called “Characters” and can process other kinds of characters in addition to control characters. Control characters correspond to the “control” parameter of the rule. Change:
check control_characters;
to:
check characters (control);
This rule has been changed into a subrule of the (new) rule “simplifiable_statements”. Change:
check if_for_case;
to:
check simplifiable_statements (if_for_case);
The rule does not print the number of instantiations any more, since the same effect can be achieved with the “count” control kind.
This rule has been removed, since its effect can now be achieved with other rules: the rule “declarations” to check for local instantiations of any generic, and the rule “instantiations” to check for local instantiations of specified generics. Change:
R1: check Local_Instantiation; R2: search Local_Instantiation (Ada.Unchecked_Conversion);
to:
R1: check declarations (local instantiation); R2: search Instantiations (local Ada.Unchecked_Conversion);
Quotes are no more optional around patterns.
The <location> modifier is now before the <filter_kind> (it was before the pattern previously). This may require splitting the rule in two in some cases. For example, change:
check naming_convention (object, local "^L_", global "^G_");
to:
check naming_convention (local object, "^L_"); check naming_convention (global object, "^G_");
The name of this rule has been changed to “improper_initialization”, since it now controls other cases of improper initialization.
Quotes are no more optional around patterns.
Two subrules of this rule have migrated to the new rule “simplifiable_statements” (with slightly different names). Change:
check statements (unnecessary_null); check statements (while_true);
to:
check simplifiable_statements (null); check simplifiable_statements (loop);
The subrule “Formal_In_Out” has been renamed as “In_Out_Generic_Parameter”, for consistency with the new “In_Out_Parameter” subrule.
The subrules “renames” and “not_operator_renames” have been renamed to “renaming” and “not_operator_renaming”.
As a consequence of being able to specify the location of any construct, the subrules “nested_function_instantiation”, “nested_generic_function”, “nested_generic_package”, “nested_generic_procedure”, “nested_package”, “nested_package_instantiation”, and “nested_procedure_instantiation” have been removed and replaced with the corresponding general construct (without “nested_”). You can have the same effect by specifying the “nested” modifier in front of them. I.e., change:
check declarations (nested_generic_function);
to:
check declarations (nested generic_function);
The <location> keyword is placed before the <Filter_Kind> keyword instead of before the <Pattern>, which looks more natural. The “Any” keyword has been removed, since omitting the <location> keyword has the same effect. Change:
check naming_convention (variable, global "^G_"); check naming_convention (package, any "^Pack_");
to:
check naming_convention (global variable, "^G_"); check naming_convention (package, "^Pack_");
This rule is now called Non_Static, since it is no more restricted to constraints. The parameters “index” and “discriminant” have been changed to “index_constraint” and “discriminant_constraint”, respectively. Change:
check non_static_constraint (index, discriminant);
to:
check non_static (index_constraint, discriminant_constraint);
This rule has been renamed to Insufficient_Parameters, since it does no more
handle the “maximum” subrule. Controlling positional parameters according to their number
is now done by the rule style (positional_association). Change:
check positional_parameters (maximum, 3); check positional_parameters (insufficient, 2, Boolean);
to:
check style (positional_association, call, 3); check insufficient_parameters (2, Boolean);
This rule is no more a rule of its own, it is a subrule of the (new) rule Expressions, whose name is Real_Equality. Change:
check Real_Operators;
to:
check expressions (Real_Equality);
The name of the subrule “casing” has been changed to “casing_identifier” since the casing of attributes and pragmas can now also be checked. The casing style is no more optional.
The name of the subrule “literal” has been changed to “numeric_literal” (since characters and strings are also literals, but are not handled by this subrule).
The subrule “exposed_literal” now requires an extra parameter to tell whether it applies to integer literals, real literals, character literals or string literals. Allowed values are provided after this parameter, and must of course be of the appropriate type. In short, if you had:
check style (exposed_literal, 0, 1, 0.0, 1.0);
you must change it to:
check style (exposed_literal, integer, 0, 1) check style (exposed_literal, real, 0.0, 1.0);
The “aggregate” parameter of the subrule “positional_association” has been split into “array_aggregate” and “record_aggregate”. For example, change:
check style (positional_association, aggregate);
into:
check style (positional_association, record_aggregate, array_aggregate);
The XML file used to describe AdaControl features to GPS used to be
called adactl.xml. It is now called zadactl.xml, since
GPS processes its initialization files in alphabetical order. This
avoids shuffling the menus when AdaControl support is activated.
Make sure to remove the old adactl.xml file from the GPS
plug-ins directory before installing the new version.
The parameters “access” and “access_subprogram” have been changed to “access_type” and “access_subprogram_type”, for consistency with the new parameters.
A keyword has been added to specify the required number of comment lines. Change:
check Header_Comments (10);
to:
check Header_Comments (minimum, 10);
This rule is now part of the “style” rule. Change:
check No_Closing_Name;
to:
check Style (No_Closing_Name);
This rule is now part of the “usage” rule. Change:
check Specification_Objects (<parameters>);
to:
check Usage (Object, From_Spec, <parameters>);
Name changed from “statement” to “statements” (added an ’s’), to be consistent with other rules.
This rule is now part of the “statements” rule. Change:
check When_Others_Null (case); check When_Others_Null (exception);
to:
check Statements (case_others_null); check Statements (exception_others_null);