xref: /dports/lang/adacontrol/adactl-1.18r9/doc/adacontrol_ug.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename adacontrol_ug.info
@settitle AdaControl User Guide V1.18r9
@c %**end of header
@macro rule{text}
@sp 1
@noindent @b{\text\}
@end macro

@titlepage
@title AdaControl User Guide

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@end titlepage

@ifnottex
@node Top, Introduction, (dir), (dir)
@top AdaControl User Guide
@end ifnottex

Last edited: @today{}

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.

@menu
* Introduction::
* Installation::
* Program Usage::
* Command language reference::
* Rules reference::
* Examples of using AdaControl for common programming rules::
* Specifying an Ada entity name::
* Syntax of regular expressions::
* Non upward-compatible changes::
@end menu

AdaControl is Copyright @copyright{} 2005-2016 Eurocontrol/Adalog,
except for some specific modules that are @copyright{} 2006
Belgocontrol/Adalog, @copyright{} 2006 CSEE/Adalog, @copyright{}
2006 SAGEM/Adalog, or @copyright{} 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 @copyright{} 2005-2016
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.

@iftex
@contents
@end iftex

@node Introduction, Installation, Top, Top
@chapter Introduction
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.

AdaControl is a commercial product of
@url{http://www.adalog.fr/adalog2.htm,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 @ref{Support} or contact
Adalog at @email{info@@adalog.fr}.

@menu
* Features::
* Support::
* History::
* References::
@end menu

@node Features, Support, Introduction, Introduction
@section Features
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):
@itemize @bullet
@item
Control physical layout of the program (Maximum line length, no use of
tabulations...)
@item
Control occurences of special strings in comments (like TBD for ``To
Be Defined''), with full wildcarding.
@item
Use of features (goto statement, tasking, pointers, variables in
package specifications...)
@item
Use of any declared entity, with full overloading resolution
@end itemize
Other rules are quite sophisticated:
@itemize @bullet
@item
Control series of ``if''...''elsif'' that could be replaced by
``case'' statements
@item
Verify usage of declarations (variables that should be constant,
variables read but not written...)
@item
Control declarations that could be moved to a more reduced, internal
scope
@item
Limit the call depth of a program (and diagnose recursive subprograms)
@item
Enforce a pattern that guarantees that exceptions are not handled
silently
@item
Enforce a pattern for paired calls (like semaphore's ``P'' and ``V'')
that guarantees that the closing call is always executed, even in
presence of exceptions.
@item
Check that there is no aliasing between out parameters
@item
Ensure that no protected operation calls a potentially blocking operation
@end itemize
and much, much more... See @ref{Rules reference} for the complete
reference for all possible controls.

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
@ref{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:
@example
@b{package} Pack @b{is}
   @b{pragma} Pure (Pack);
   ...
@b{end} Pack;
@end example
The following command:
@example
adactl -l "search pragmas (pure)" pack
@end example
produces the following result (displayed to standard output):
@example
pack.ads:2:4: Found: PRAGMAS: use of pragma Pure
@end example

AdaControl integrates nicely in environments such as GPS
(@pxref{Running AdaControl from GPS}), AdaGide (@pxref{Running
AdaControl from AdaGide}), or emacs (@pxref{Control kinds and report
messages}). In those environments, you can run AdaControl from menus
or by just clicking on a button!

@node Support, History, Features, Introduction
@section Support
@subsection Commercial support
Adalog provides commercial support for AdaControl. Support includes
the following benefits:
@itemize @bullet
@item
Help with installation procedures.
@item
Explanations regarding the use of the tool, and help for translating
coding standards into AdaControl rules.
@item
Dedicated account into our BT system for priority handling of
problem reports.
@item
Correction of problems encountered in the use of AdaControl.
Pre-releases versions of AdaControl are provided for each corrected
problem.
@item
Access to beta-versions before they are released
@item
Keeping in sync customer's own custom rules with the latest version of
AdaControl.
@item
Reduced rate for on-demand development of custom rules.
@item
Priority consideration of enhancement requests. Satisfying enhancement
requests is not part of the support contract; however, Adalog is
constantly improving AdaControl, and suggestions originating from
supported customers are given a high priority in our todo list.
@end itemize

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:
@itemize @bullet
@item
Custom improvements to AdaControl, including application-specific
rules;
@item
consulting services for defining coding standards;
@item
consulting services in all areas related to Ada, real-time,
compilation, etc. See @url{http://www.adalog.fr/adalog2.htm,Adalog's site} for details.
@end itemize

For pricing information about support contract and other services,
please contact @email{info@@adalog.fr}.

@subsection Other support
There is a Wiki for questions about AdaControl at @*
@url{https://sourceforge.net/p/adacontrol/wiki/Home/}. This is the
place to ask for information, make suggestions, or get help from the
community.

For problem reports, please create a ticket into our BT system at @*
@url{https://sourceforge.net/p/adacontrol/tickets/}.

@subsection Your support to us, too!
If you enjoy AdaControl, there are several things you can do to help
us continue and improve this nice project.
@itemize @bullet
@item
Rate it, or even better post a review, on the
@url{http://sourceforge.net/projects/adacontrol/reviews/,SourceForge
review page}
@item
Click ``I use it'' from
@url{http://www.adalog.fr/adacontrol2.htm,AdaControl's home page}.
@item
Rate it on @url{http://www.ohloh.net/p/11353?ref=sample, AdaControl's
Ohloh page}
@item
Get a support contract, or encourage your company, your friends, or
anybody else to get a support contract!
@item
Provide good ideas, new rules, suggestions for improvements...
@end itemize
And remember: developing AdaControl is an expensive effort (according
to Ohlo's COCOMO model, it is worth 15 man.year of development). We
need support from our users to keep it running!

@node History, References, Support, Introduction
@section History
The development of AdaControl was initially funded by Eurocontrol
(@url{http://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), and
Isidro Ilasa Veloso (GMV). AdaGide support and improvement of icons
were contributed by Gautier de Montmollin. Emmanuel Masker (Alstom)
and Yannick Duchene contributed to GPS integration.

See file @code{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 @ref{Non upward-compatible changes} for details.

@node  References,  , History, Introduction
@section References
@enumerate
@item
``On the benefits for industrials of sponsoring free software
development'', @i{Ada User Journal}, Volume 26, number 4, december 2005

@url{http://www.adalog.fr/publicat/Free-software.pdf}
@item
``A Comparison of Industrial Coding Rules'', @i{Ada User Journal},
Volume 29, number 4, december 2008

@url{http://www.adalog.fr/publicat/coding-rules.pdf}
@item
``A Methodology for Avoiding Known Compiler Problems
Using Static Analysis'', @i{proceedings of the ACM SIGAda Annual International Conference (SIGAda 2010)}

@url{http://dl.acm.org/authorize?316395}
@end enumerate

@node Installation, Program Usage, Introduction, Top
@chapter Installation
Like any ASIS application, AdaControl can be run only if the compiler
available on the system has exactly the same version as the one used
to compile AdaControl itself. The executable distribution of
AdaControl will work only with GNAT version GPL 2016, as distributed
by AdaCore. 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. @xref{Customizing AdaControl}.

@menu
* Building and installing AdaControl from source::
* Installing an executable distribution::
* Installing support for AdaGide::
@end menu

@node  Building and installing AdaControl from source, Installing an executable distribution, Installation, Installation
@section Building and installing AdaControl from source
This section is only for the source distribution of AdaControl. If you
downloaded an executable distribution (and are using the latest
version of GNAT GPL), you may skip to the next section.

@anchor{Getting the correct version of the sources for your Gnat version}
@subsection Getting the correct version of the sources for your Gnat version
ASIS is continuously evolving to support Ada-2005/2012 features, and
so is AdaControl. As a consequence, the full set of features of
AdaControl is supported only with recent versions of Gnat, namely with
GnatPRO 7.2.0 and GnatGPL-2013 (and higher). We refer to these
versions as the ``new Gnat'', and we encourage all users to use the
latest versions.

Some user may however need to use an older version of Gnat. We provide
also a version of AdaControl that is compatible with versions GnatPRO
7.0.x and GnatGPL-2011 and older (before some incompatible -but
necessary- changes in ASIS happened). We refer to these versions as
the ``old Gnat''.

The release whose distribution files start with ``adactl'' is for the
new Gnat, and the one whose distribution files start with
``adactl-old'' is for the old-gnat.  Both versions provide the same
features, except that controls related to Ada-2012 (or that depend on
new features of ASIS) are not available in the old-gnat
version. Moreover, the old-gnat version is now frozen, and will not
receive any new features or improvements in the future, unless
requested by a supported customer (such requests will be honoured as
part of the support contract). See @ref{Support} for
information on becoming a supported user.

Note that intermediate releases of Gnat (GnatPRO-7.1.x, GnatGPL-2012)
are not fully compatible with either of these distribution. Depending
on exact version, problems may range from compilation errors to
incorrect results in some rare (Ada 2012) cases. Compatible sources
can be obtained from the Git repository of AdaControl on SourceForge
(@url{http://adacontrol.sourceforge.net}). We will be happy to help
our supported customers who must use one of these versions.

@subsection Prerequisites
The following software must be installed in order to compile
AdaControl from source:
@itemize
@item
A GNAT compiler, any version (but please consider @ref{Getting the
correct version of the sources for your Gnat version} above). Note
that the compiler must also be available on the machine in order to
run AdaControl (all ASIS application need the compiler).
@item
ASIS for GNAT
@item
The GNATColl component (if support of .gpr files is desired)
@end itemize

Make sure to have the same version of GNAT and ASIS. The version used
for running AdaControl must be the same as the one used to compile
AdaControl itself.

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 @code{src} directory and:
@itemize @bullet
@item
rename @code{implementation_options-i_options_from_gpr_project.adb} to
@code{implementation_options-i_options_from_gpr_project_gpr.adb}
@item
rename
@code{implementation_options-i_options_from_gpr_project_nogpr.adb} to
@code{implementation_options-i_options_from_gpr_project.adb}
@end itemize

@subsection Build and install with installer (Windows)
Run the installer (@code{adactl_src-setup.exe}). This will
automatically build and install AdaControl, no other installation is
necessary.

@anchor{Build and install with project file}
@subsection Build and install with project file
Simply go to the root directory of the distribution and type:
@example
gprbuild build.gpr
gprinstall build.gpr
@end example
You're done!

Caveat (@i{old gnat only}): Due to a bug in some versions, if you are using GNATPro
6.1.2 and above, you must set the variable GNAT_FIX to 1; i.e. invoke
the command as:
@example
gprbuild -Pbuild.gpr -XGNAT_FIX=1
@end example
or if gprbuild is not available for your distribution:
@example
gnatmake -Pbuild.gpr -XGNAT_FIX=1
@end example

@subsection Build and install with Makefile
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:
@example
make build
make install
@end example

It is also possible to delete object files and do other actions with
this  ``Makefile'', run the following command to get more information:
@example
make help
@end example

NOTE: Building AdaControl needs the ``make'' command provide with GNAT; it
works both with WIN32 shell and UNIX shell.

@subsection Manual installation
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 GPS is not installed in the
Gnat tree).

All you need to run AdaControl is the executable named  @code{adactl}
under Linux or @code{adactl.exe} under Windows. In addition,
@code{pfni} (or @code{pfni.exe} under Windows) is a convenient
utility, required by the GPS support. @xref{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 GPS, copy the file
@code{GPS/adacontrol.xml} into the @code{<GNAT_dir>/share/gprconfig}
directory; copy all other files from the @code{GPS} directory into the
@code{<GPS_dir>/share/gps/plug-ins} directory. Copy also HTML files
from the @code{doc} directory into the
@code{<GPS_dir>/share/doc/gps/html} to access AdaControl's guides from
the "Help" menu of GPS.

@subsection Build with a compiler other than GNAT
It should be possible to compile AdaControl with other compilers than
GNAT, although we didn't have an opportunity to try it. If you have
another compiler that supports ASIS, note that it may require some
easy changes in the package @code{Implementation_Options} to give
proper parameters to the @code{Associate} procedure of ASIS.  Rules
that need string pattern matchings need the package
@code{Gnat.Regpat}. If you compile AdaControl with another compiler,
you can either port @code{Gnat.Regpat} to your system, or use a
(limited) portable implementation of a simple pattern matching
(package @code{String_Matching_Portable}). Edit the file
@code{string_matching.ads} and change it as indicated in the comments.
No other change should be necessary.

Alternatively, if you are using another compiler, you can try and
compile your program with GNAT just to be able to run
AdaControl. However, compilers often differ in their support of
representation clauses, which can cause your program to be rejected by
GNAT. In that case, we provide a sed script to comment-out all
representation clauses; this can be sufficient to allow you to use
AdaControl. @xref{unrepr.sed}.

@subsection Testing AdaControl
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:
@example
cd test
./run.sh
@end example

All tests must report PASSED. If they don't, it may be due to one of
the following issues:
@itemize
@item
You are using an old version of GNAT.  AdaControl runs without any
known problem (and it has been checked against the whole ACATS) only
with the latest GNATPro and GNATGPL versions; earlier versions are
known to have bugs and unimplemented features that will not allow
AdaControl to run correctly in some cases. We strongly recommend to
always use the most recent version of GNAT.
@item
You run an old-gnat version of AdaControl with GNATPro (6.1.2 and
above) and you forgot to specify the ``-XGNAT_FIX=1''
option. @xref{Build and install with project file}.
@item
It may happen that the test @code{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.
@end itemize

@anchor{Customizing AdaControl}
@subsection Customizing AdaControl
If there are some rules that you are not interested in, it is very easy
to remove them from AdaControl:
@enumerate
@item
In the @code{src} directory, edit the file
@code{framework-plugs.adb}. There is a @code{with} clause for each
rule (children of package @code{Rules}). Comment out the ones you
don't want.
@item
Recompile @code{framework-plugs.adb}. There will be error messages
about unknown procedure calls. Comment out the corresponding lines.
@item
Compile AdaControl normally. That's all!
@end enumerate

It is also possible to add new rules to AdaControl. If your favorite
rules are not currently supported, you have several options:
@enumerate
@item
If you have some funding available, please contact
@url{mailto::info@@adalog.fr,,info@@adalog.fr}. We'll be happy to
make an offer to customize AdaControl to your needs.
@item
If you @i{don't} have funding, but have some knowledge of ASIS
programming, you can add the rule yourself. We have made every effort
to make this as simple as possible. Please refer to the AdaControl
programmer's manual for details. If you do so, please send your rules
to @url{mailto::rosen@@adalog.fr,,rosen@@adalog.fr}, and we'll be
happy to integrate them in the general release of AdaControl to make them
available to everybody.
@item
If you have good ideas, but don't feel like implementing them yourself
(nor financing them), please send a note to
@url{mailto::rosen@@adalog.fr,,rosen@@adalog.fr}. We will eventually
incorporate all good suggestions, but we can't of course commit to any
dead-line in that case.
@end enumerate

@node Installing an executable distribution, Installing support for AdaGide, Building and installing AdaControl from source, Installation
@section Installing an executable distribution
If you downloaded the Windows installer executable version of
AdaControl, simply run @code{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:
@example
gprinstall build.gpr
@end example

This will install the executables and the GPS support in the standard
locations (the Gnat directory). However, if you are using AdaGide, the
support will have to be installed manually as explained below.

@node Installing support for AdaGide,  , Installing an executable distribution, Installation
@section Installing support for AdaGide
To add AdaControl support to AdaGide, copy the file
@code{AdaControl.tdf} from the @code{AdaGide} directory of the
distribution into AdaGide's root directory. Note that AdaControl
support requires AdaGide version 7.42 or above.

@node Program Usage, Command language reference, Installation, Top
@chapter Program Usage
AdaControl is a command-line program, i.e. it is normally called
directly from the system shell. @i{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. @i{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:
@example
adactl [-deEirsTuvwx]
       [-p <project file>]     [-f <rules file>]    [-l <rules list>]
       [-o <output file>]      [-t <trace file>]    [-F <format>]
       [-S <statistics level>] [-m <warning limit>] [-M <message limit>]
       @{<unit>[+|-<unit>]|[@@]<file>@} [-- <ASIS options>]
@end example

AdaControl can process Ada-2012 as well as Ada-95 programs, even if
there are currently few Ada-2012 related controls - but we hope to
improve that situation in the near future.

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-GPL). Due to
technical reasons, the -gnat05 option cannot be passed to the compiler
in ``compile on the fly'' mode, but you can do any of the following:
@itemize
@item
have a ``gnat.adc'' file in the current directory that contains a
@code{@b{pragma} Ada_05;} (or @code{@b{pragma} Ada_12;})
@item
put a @code{@b{pragma} Ada_05} (or @code{@b{pragma} Ada_12;}) on top
of every compilation unit that uses Ada-2005/2012 features;
@item
generate the tree files manually (@pxref{Generating tree files
manually}) with the ``-gnat05'' (or ``-gnat12)'') option. Note that
this allows you to pass any other GNAT option as well.
@end itemize

Note that if your program is pure Ada-95 and you are using a version
of GNAT where Ada-2005 is the default (especially GNAT-GPL), 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 @code{@b{pragma} Ada_95} instead.

@menu
* Command line parameters and options::
* Return codes::
* Environment variable and default settings::
* Interactive mode::
* Other execution modes::
* Running AdaControl from GPS::
* Running AdaControl from AdaGide::
* Helpful utilities::
* Optimizing Adacontrol::
* In case of trouble::
@end menu

@node Command line parameters and options, Return codes, Program Usage, Program Usage
@section Command line parameters and options
@menu
* Input units::
* Commands::
* Output file::
* Output format::
* Output limits::
* Project files::
* Local disabling control::
* Verbose and debug mode::
* Treatment of warnings::
* Exit on error::
* ASIS options::
@end menu

@node Input units, Commands, Command line parameters and options, Command line parameters and options
@subsection Input units
Units to be processed are given as parameters on the command
line. Note that they are Ada @emph{compilation unit} names, not
@emph{file names}: case is not significant, and there should be no
extension! Child units are allowed following normal Ada naming rules:
@code{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:
@example
adactl -f my_rules.aru *.adb
@end example

In the unlikely case where you have a child unit called @code{Ads} or
@code{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:
@example
adactl -r -f my_rules.aru my_main
@end example
will process @code{my_main} and all units that @code{my_main} depends
on. If @code{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 @i{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:
@example
adactl -f my_rules_file.aru -r adactl-asis-a4g
@end example
This applies the rules from the file @code{my_rules_files.aru} to
AdaControl itself, but not to units that are part of ASIS (units
@code{Asis}, @code{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. If a name in the file starts with ``@@'', it will
also be treated as an indirect file (i.e. the same process will be
invoked recursively). If a line in the file starts with ``#'' or
``-@w{}-'', it is ignored. This can be useful to temporarily disable
the processing of some files or to add comments.

Ex:
@example
adactl -f my_rules.aru @@unit_file.txt
@end example

@node Commands, Output file, Input units, Command line parameters and options
@subsection Commands
Commands specify which processing AdaControl should apply to
units. See @ref{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:
@example
adactl pack.ads proc.adb -l "check instantiations (My_Generic);"
@end example
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 ``@code{.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. @xref{Interactive mode}.

Ex:
@example
adactl -f my_rules.aru proc.adb
@end example

Note that the ``-l'' and ``-f'' options are @i{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.

@node Output file, Output format, Commands, Command line parameters and options
@subsection Output file
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.

Ex:
@example
adactl -f my_rules.aru -o my_output.txt proc.adb
@end example
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.

@node  Output format, Output limits, Output file, Command line parameters and options
@subsection Output format
The ``-F'' option selects the output format. It must be followed by
``Gnat'', ``Gnat_Short'', ``CSV'', ``CSV_Short'', ``Source'',
``Source_Short'', or ``None'' (case insensitive).  By default, the output
is in ``Gnat'' format. See @ref{Control kinds and report messages} for
details.

The ``-S'' option selects which statistics are output after each
run. It must be followed by a value in the range 0..3. See
@ref{Control kinds and report messages} 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.

Ex:
@example
adactl -F CSV -S 2 -f my_rules.aru -o my_output.csv proc.adb
@end example

@node Output limits, Project files, Output format, Command line parameters and options
@subsection Output limits
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.

@node Project files, Local disabling control, Output limits, Command line parameters and options
@subsection Project files
Starting with version 1.18, AdaControl supports GNAT project files
(``.gpr''). The ``-p'' option is used to provide the name of a project
file; 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).

Ex:
@example
adactl -f my_rules.aru -p proj.gpr proc.adb
@end example

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.

@node  Local disabling control, Verbose and debug mode, Project files, Command line parameters and options
@subsection Local disabling control
The ``-i'' option tells AdaControl to ignore disabling markers in Ada
source code (@pxref{Disabling controls}); i.e. all controls will be
performed, regardless of the presence of disabling markers. This is
equivalent to the command ``@code{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 ``@code{set ignore INVERTED;}''.

@node Verbose and debug mode, Treatment of warnings, Local disabling control, Command line parameters and options
@subsection Verbose and debug mode
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 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. Note that if you hit Ctrl-C in debug
mode, AdaControl aborts with a message telling the currently active
rule and module. This can be useful if you suspect AdaControl to be
stuck in an infinite loop.

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.

@node Treatment of warnings, Exit on error, Verbose and debug mode, Command line parameters and options
@subsection Treatment of warnings
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. @xref{Return codes}. It does not change the messages
however.

Conversely, the ``-E'' option tells AdaControl to @i{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. @xref{Control kinds and report messages}.

@node Exit on error, ASIS options, Treatment of warnings, Command line parameters and options
@subsection Exit on error
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). @xref{In case of trouble}.

Ex:
@example
adactl -x -f my_rules.aru proc.adb
@end example

@node ASIS options,  , Exit on error, Command line parameters and options
@subsection ASIS options
Everything that appears on the command line after ``-@w{}-'' will be
treated as an ASIS option, as described in the ASIS user manual.

Casual users don't need to care about ASIS options, except in one
case: if you are running AdaControl from the command line (not from
GPS), and if the units that you are processing reference other units
whose source is not in the same directory, AdaControl needs to know
how to access these units (as GNAT would). This can be done either by
using a project file with the ``-p'' option (see @ref{Project
files}), by putting the appropriate directories into the
ADA_INCLUDE_PATH environment variable, or by passing ``-I'' options to
ASIS.

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 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. @xref{Optimizing Adacontrol}.

@node Return codes, Environment variable and default settings, Command line parameters and options, Program Usage
@section Return codes
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:
@itemize
@item
0: At most ``search'' controls (i.e. warnings) were triggered (no control
at all with ``-e'' option)
@item
1: At least one ``check'' control (i.e. error) was triggered (or at
least one ``search'' or ``check'' control with ``-e'' option)
@item
2: AdaControl was not run due to a syntax error in the rules or in the
specification of units.
@item
10: There was an internal failure of AdaControl.
@end itemize

@node Environment variable and default settings, Interactive mode, Return codes, Program Usage
@section Environment variable and default settings
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. @xref{Set command}.

For example, you can set ADACTLINI to ``set format Gnat_Short'' if you
prefer having you messages in short format rather than the (default)
long format.

@node Interactive mode, Other execution modes, Environment variable and default settings, Program Usage
@section Interactive mode
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 (@pxref{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 (@pxref{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.

@node  Other execution modes, Running AdaControl from GPS, Interactive mode, Program Usage
@section Other execution modes
In addition to normal usage, AdaControl features special options to
ease its use; no Ada unit is analyzed when using these options.

@menu
* Getting help::
* Checking commands syntax::
* Generating a units list::
@end menu

@node Getting help, Checking commands syntax, Other execution modes, Other execution modes
@subsection Getting help
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:
@example
adactl -h [<keyword> | <rule name> | variables ["<pattern>"] ...]
<keyword> ::= all     | commands | license | list |
              options | rules    | version
@end example

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:
@itemize @bullet
@item
<rule name>: if <rule name> is exactly the name of rule, display the
help message for the indicated rule. Otherwise, <rule name> is
interpreted as a pattern, and help messages for all rules that match
the pattern is displayed. Patterns are given using the full
Regexp syntax. @pxref{Syntax of regular expressions} for details.
@item
``variables'' lists the values of all variables whose name matches <pattern>,
or all variables if there is no <pattern>. Patterns are given using the full
Regexp syntax. @pxref{Syntax of regular expressions} for details.
@item
``all'':  display the help message for all rules.
@item
``commands'': display a summary of all commands
@item
``license'': display the license information
@item
``list'': display the names of all rules (note that ``rules'' also
displays the list of rules, in a prettier format; the ``list'' option
is mainly useful for the integration of AdaControl into GPS).
@item
``options'': display help about the command-line options
@item
``rules'': display the names of all rules.
@item
``version'': display AdaControl and ASIS implementation version numbers.
@end itemize

Ex:
@example
adactl -h pragmas Unnecessary_Use_Clause
adactl -h all
adactl -h version license
adactl -h stat
@end example
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.

@node Checking commands syntax, Generating a units list, Getting help, Other execution modes
@subsection Checking commands syntax
The ``-C'' option is used to check syntax of commands without
executing any control.

Syntax:
@example
adactl -C [-dv] [-f <rules file>] [-l <rules list>]
@end example

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 rules file,
before trying it on many units. The way AdaControl works, it must open
the ASIS context (a lengthy operation) @i{before} analyzing the
rules. This option can therefore save a lot of time if the rules file
contains errors.

@node Generating a units list,  , Checking commands syntax, Other execution modes
@subsection Generating a units list
The ``-D'' options produces a list of units that can be reused as an
indirect file in later runs.

Syntax:
@example
adactl -D [-rsvw] [-o <output file>] [-p <project file>]
          @{<unit>[+|-<unit>]|[@@]<file>@} [-- <ASIS options>]
@end example
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. @xref{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.

@subsubsection Limitation
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.

@node Running AdaControl from GPS, Running AdaControl from AdaGide, Other execution modes, Program Usage
@section Running AdaControl from GPS
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.

@menu
* The AdaControl menu and buttons::
* Contextual menu::
* AdaControl switches::
* AdaControl preferences::
* AdaControl language::
* AdaControl help::
* Caveat::
@end menu

@node The AdaControl menu and buttons, Contextual menu, Running AdaControl from GPS, Running AdaControl from GPS
@subsection The AdaControl menu and buttons
GPS now features an ``AdaControl'' menu, with several submenus:
@itemize @bullet
@item
``Control Current File (rules file)'' runs AdaControl on the currently
edited file, with rules taken from the current rules file; this menu
is greyed-out if no rules file is defined, if no file window is
currently active, or if the associated language is not ``Ada''. The
name of the rules file can be set from the ``Library'' tab from the
``Project/Edit Project Properties'' menu.
@item
``Control Root Project (rules file)'' runs AdaControl on all units
that are part of the root project, with rules taken from the current
rules file; this menu is greyed-out if no rules file is defined. The
name of the rules file can be set from the ``Library'' tab from the
``Project/Edit Project Properties'' menu.
@item
``Control Units from List (rules file)'' runs AdaControls on units
given in a indirect file, with rules taken from the current rules
file. This menu is greyed-out if no rules file is defined or if no
indirect file is defined. The name of the rules file and of the
indirect file can be set from the ``Library'' tab from the
``Project/Edit Project Properties'' menu.
@item
``Control Current File (interactive)'' runs AdaControl on the
currently edited file, with a rule asked interactively from a pop-up;
this menu is greyed-out if no file window is currently active, or if
the associated language is not ``Ada''.
@item
``Control Root Project (interactive)'' runs AdaControl on all units
that are part of the root project, with a rule asked interactively
from a pop-up.
@item
``Control Units from List (interactive)'' runs AdaControls on units
given in a indirect file, with a rule asked interactively from a
pop-up. This menu is greyed-out if no indirect file is defined. The
name of the indirect file can be set from the ``Library'' tab from the
``Project/Edit Project Properties'' menu.
@item
``Check Rules File'' checks the syntax of the current rules file. This
menu is deactivated if the current window does not contain an
AdaControl rules file.
@item
``Open Rules File'' opens the rules file. This menu is deactivated if
there is no current rules file defined.
@item
``Open Units File'' opens the units file. This menu is deactivated if
there is no current units file defined.
@item
``Create units file'' creates a text file containing all units (not
files) names from the current root project. This file is appropriate
as an indirect file for the ``... from list'' commands.
@item
``Create .adp project'' creates an Emacs-style project file from the
current GPS project. This is of little interest now that AdaControl
accepts GPS project files directly, and is still provided for
compatibility with older versions of AdaControl. @xref{Project files}.
@item
``Delete Tree Files'' removes existing tree files from the current
directory.  This is convenient when AdaControl complains that the tree
files are not up-to-date. Note that you can set the preferences for
automatic deletion of tree files after each run (see below). Note that
the name of this menu is changed to ``Delete Tree and .ali Files'' if
you have chosen to delete .ali files in the preferences (see below).
@item
``Load results file'' loads in the location window the result file
obtained from a previous run of AdaControl. The file must have been
produced with the ``Gnat'' or ``Gnat_Short'' format. @xref{Control kinds
and report messages}.
@end itemize

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):
@itemize @bullet
@item
When you use the ``interactive'' menus several times, the
previously entered command(s) is used as a default.
@item
You can enter any command from AdaControl's language in the dialog;
you can even enter several commands separated by ``;''.
@item
Especially, if you want to run AdaControl with a rules file that is
not the one defined by the switches, you can use one of the
``interactive'' commands, and give ``source <file name>'' as the
command.
@end itemize

@node Contextual menu, AdaControl switches, The AdaControl menu and buttons, Running AdaControl from GPS
@subsection Contextual menu
AdaControl adds two entries to the contextual menus (right click) of
Ada files.  They call the @code{pfni} utility on the current
entity. @xref{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. @xref{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.

@node AdaControl switches, AdaControl preferences, Contextual menu, Running AdaControl from GPS
@subsection AdaControl switches
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).

@subsubsection Files
This section controls the definition of various files used by AdaControl.
@itemize @bullet
@item
``Rules file''. This is the name of a file that contains the
definition of the controls to be applied to your project. This file is
required for all ``control (rules file)'' commands.
@item
``Units file''. This is the name of a file that contains the list of
units to be controlled.  This file is required for all ``control from
list'' commands.
@end itemize

@subsubsection Processing
This section offers options that control how units are processed.
@itemize @bullet
@item
``Recursive mode''. This sets the ``-r'' option. @xref{Input units}.
@item
``Ignore local deactivation''. This sets the ``-i''
option. @xref{Local disabling control}.
@item
``Process specs only''. This sets the ``-s'' option. @xref{Input
units}.
@item
``Compilation unit mode''. This sets the ``-u'' option. @xref{Input
units}.
@end itemize

@subsubsection Debug
This section controls the debugging options of AdaControl.
@itemize @bullet
@item
``Debug messages''. This sets the ``-d'' option. @xref{Verbose and
debug mode}.
@item
``Halt on error''. This sets the ``-x'' option. @xref{Exit on error}.
@end itemize

@subsubsection Output
This section offers options that control where and how the output of
AdaControl is displayed.
@itemize @bullet
@item
``Display only errors''. This sets the ``-E'' option. @xref{Treatment
of warnings}.
@item
``Warnings as errors''. This sets the ``-e'' option. @xref{Treatment
of warnings}.
@item
``Statistics''. This sets the ``-S'' option from a pull-down
menu. @xref{Control kinds and report messages}.
@item
``Send results to GPS''. When checked (default), the output of
AdaControl is sent to the ``locations'' window of GPS.
@item
``Send results to File''. When checked, the output of AdaControl is
sent to the file indicated in the box below.
@item
``Send results to File and GPS''. When checked, the output of
AdaControl is sent to the file indicated in the box below, and the
content of the file is then automatically reloaded in the
``locations'' window of GPS. If this option is set, the file format is
always ``Gnat'' (the file format option is ignored).
@item
``File name''. This is the name of the file that will contain the
results when sent to ``File'' or ``File and GPS''.  If the results are
sent to ``File'' and the file exists, AdaControl will ask for the
permission to overwrite it. If the results are sent to ``File and
GPS'', the result file is always overriden without asking.
@item
``File format''. This is a pull-down menu that allows you to select
the desired format when output is directed to a file (``-F'' option).
@xref{Control kinds and report messages}.
@end itemize

@subsubsection ASIS
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, @pxref{ASIS options}.

@node AdaControl preferences, AdaControl language, AdaControl switches, Running AdaControl from GPS
@subsection AdaControl preferences
There is an entry for AdaControl in the ``edit/preferences'' menu:
@itemize @bullet
@item
``delete trees''. If this box is checked, tree files are automatically
deleted after each run of AdaControl. This avoids having problems with
out-of-date tree files, at the expanse of slightly slowing down
AdaControl if you run it several times in a row without changing the
source files.
@item
``Delete .ali files with tree files''. If this box is checked, the
``.ali'' files in the current directory will also be deleted together
with the tree files (either automatically if the previous box is
checked, or when the ``AdaControl/Delete Tree Files'' menu is
selected). This is normally what you want, unless the current
directory is also used as the object directory for compilations; in
the latter case, deleting ``.ali'' files would cause a full
recompilation for the next build of the project.
@item
``Help on rule''. This allows you to select how rule specific help
(from the ``Help/AdaControl/Help on rule'' menu) is displayed. If you
select ``Pop-up'', a summary of the rule's purpose and syntax is
displayed in a pop-up. If you select ``User Guide'', the user guide
opens in a browser at the page that explains the rule. (@b{Caveat}:
due to a problem in GPS under Windows, the ``User Guide'' option may
not work at all, or the browser will not find the right anchor;
hopefully, this will be fixed in an upcomming release of GPS. No such
problem under Linux).
@item
``Use separate categories''. If this box is checked, there will be one
category (i.e. tree in the locations window) for each rule type or
label, otherwise all messages will be grouped under the single
category ``AdaControl''. In practice, this means that with the box
checked, messages will be sorted by rules first, then by files, while
otherwise, the messages will be sorted by files first, then by rules.
In any case, compilation errors appear under the ``Compilation''
category, final counts under the ``Counts summary'' category, and
statistics under the ``Statistics'' category.
@item
``Auto save files''. If this box is checked, all modified files are
automatically saved without asking before running
AdaControl. Otherwise, a dialog appears allowing the user to choose
which files to save.
@item
``Buttons operate on''. This defines the behaviour of the buttons.
If ``Current File'' is selected, the buttons operate on the file being
currently edited. If ``Root Project'' is selected, the buttons operate
on all files that are part of the current project. If ``Units from List''
is selected, the buttons operate on all units from the units file.
@item
``Display AdaControl run''. If this box is checked, the command line used
to launch AdaControl and the output messages are displayed in the ``Messages''
window.
@item
``Max allowed error messages''. If non zero, run will stop if the
number of error messages exceeds this limit. @xref{Output limits}.
@item
``Max allowed messages (all kinds)''. If non zero, run will stop if
the number of error and warning messages exceeds this
limit. @xref{Output limits}.
@end itemize

@node AdaControl language, AdaControl help, AdaControl preferences, Running AdaControl from GPS
@subsection AdaControl language
If you check ``AdaControl'' in the ``Languages'' tab of the project
properties, GPS will recognize files with extension @code{.aru} as
AdaControl rules files, and provide appropriate colorization. Remember
to check also the corresponding ``no compiler'' checkbox to avoid
spurious messages from GPS.

@node AdaControl help, Caveat, AdaControl language, Running AdaControl from GPS
@subsection AdaControl help
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.

@node Caveat,  , AdaControl help, Running AdaControl from GPS
@subsection Caveat
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.

@node  Running AdaControl from AdaGide, Helpful utilities, Running AdaControl from GPS, Program Usage
@section Running AdaControl from AdaGide
If you want to use AdaControl from AdaGide, make sure you have copied
the necessary file into the required place. @xref{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 rules file or the output format, can
easily be changed by editing the tool description file
@code{AdaControl.tdf}.

AdaGide now features several AdaControl commands from the ``tool'' menu:
@itemize @bullet
@item
``AdaControl'' runs AdaControl on the currently
edited file, with rules taken from the file named @code{verif.aru}.
@item
``AdaControl recursive'' works like the previous command, with the
addition of the ``-r'' (recursive) option. When used on the main
program, it will analyze the whole set of compilation units in the
program.
@item
``AdaControl interactive'' runs AdaControl on the currently
edited file, with a rule asked interactively from a pop-up.
@item
``AdaControl: delete .adt'' removes existing tree files from the
current directory.  This is convenient when AdaControl complains that
the tree files are not up-to-date.
@end itemize

@node Helpful utilities, Optimizing Adacontrol, Running AdaControl from AdaGide, Program Usage
@section Helpful utilities
This section describe utilities that are handy to use in conjunction
with AdaControl.

@menu
* pfni::
* makepat.sed::
* unrepr.sed::
@end menu

@node pfni, makepat.sed, Helpful utilities, Helpful utilities
@subsection pfni
The convention used to refer to entities (as described in
@ref{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.

@code{pfni} (which stands for @i{Print Full Name Image}) can be used
to get the correct spelling for any Ada entity. The syntax of
@code{pfni} is:
@example
pfni [-sofdq] [-p <project-file>] <unit>[:<span>]
     [-- <ASIS options>]
<span> ::=   <line_number>
           | [<first_line>]-[<last_line>]
           | <line_number>:<column_number>
@end example
or
@example
pfni -h
@end example
If called with the ``-h'' option, @code{pfni} prints a help message
and exits.

Otherwise, @code{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, @code{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 ``-@w{}-'' (but -FS is the
default). @xref{ASIS options}.

As a side usage of @code{pfni}, if you are calling a subprogram that
has several overloadings and you are not sure which one is called, use
@code{pfni} with the ``-o'' option on that line: the program will tell
you the full name and profile of the called subprogram.

@node makepat.sed, unrepr.sed, pfni, Helpful utilities
@subsection makepat.sed
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. @xref{Header_Comments}.

@node unrepr.sed,  , makepat.sed, Helpful utilities
@subsection unrepr.sed
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:
@example
sed -i -f unrepr.sed *.ads *.adb
@end example
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 ``-@w{}-UNREPR '' to all representation
clauses. Its effect can thus easily be undone with the following
commad:
@example
sed -i -e "s/--UNREPR //" *.ads *.adb
@end example

@node Optimizing Adacontrol, In case of trouble, Helpful utilities, Program Usage
@section Optimizing Adacontrol
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 ``-@w{}-''.

@menu
* Tree files and the ASIS context::
* Generating tree files manually::
* Choosing an appropriate combination of options::
@end menu

@node Tree files and the ASIS context, Generating tree files manually, Optimizing Adacontrol, Optimizing Adacontrol
@subsection Tree files and the ASIS context
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:
@itemize
@item
-C1 Only one tree makes up the context. The name of the tree file must
follow the option.
@item
-CN Several explicit trees make up the context. The name of the tree
files must follow the option.
@item
-CA All available trees make up the context. These are the tree files
found in the current directory, and in any directory given with a
``-T'' option (which works like the ``-I'' option, but for tree files
instead of source files).
@end itemize

The ``-F'' option specifies what to do if the program tries to access
an Ada unit which is not part of the context:
@itemize
@item
-FT Only consider tree files, do not attempt to compile units
on-the-fly
@item
-FS Always compile units on-the-fly, ignore existing tree files
@item
-FM Compile on-the-fly units for which there is no already existing
tree file
@end itemize
Note that ``-FT'' is the only allowed mode, and @i{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.

@node Generating tree files manually, Choosing an appropriate combination of options, Tree files and the ASIS context, Optimizing Adacontrol
@subsection Generating tree files manually
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:
@itemize @bullet
@item
Your project has several source directories (ASIS had problems with
ADA_INCLUDE_PATH, until releases dated later than Sept. 1st,
2006). Note that an alternative solution is to provide a project file
with the -p option, or to specify source directories with the -I
option;
@item
Your project uses some compilation options that cannot be set
otherwise (AdaControl just uses the ``source_dirs'' from GPR projects,
not other options)
@item
It is faster to generate tree files once than to use ``compile on the
fly'' mode.
@end itemize

To generate tree files manually, simply recompile your project with
the ``-gnatct'' option.  This option can be passed to @code{gnatmake}
or  @code{gprbuild} normally. 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.

@node Choosing an appropriate combination of options,  , Generating tree files manually, Optimizing Adacontrol
@subsection Choosing an appropriate combination of options
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 @i{specifications} of all units
that the given unit depends on. Moreover, our measures showed that
reading an existing tree file may be @i{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.
@itemize
@item
If you want to run AdaControl on all units of your program, use the
``-D'' option to create a file containing the list of all required
units, then use this file as an indirect file. Using the the ``-r''
option (recursive mode) of AdaControl implies an extra pass over the
whole program tree to determine the necessary units.
@item
If you have not disabled any rule (and have many messages), specifying
the ``-i'' option (ignore disabling) saves AdaControl the burden of
checking whether rules are disabled, which can result in a
sensible speed-up.
@item
Avoid having unnecessary tree files. All tree files in the context are
read by ASIS, even if they are not later used.  If you don't want to
run AdaControl on the whole project, deleting tree files from a
previous run can save a lot of time.
@item
When using an indirect file, the order in which units are given may
influence the speed of the program. As a rule of thumb, units that are
closely related should appear close to each other in the file. A good
starting point is to sort the file in alphabetical order: this way,
child units will appear immediately after their parent. You can then
reorder units, and measure if it has a significant effect on speed.
@item
If you want to check a unit individually, try using the ``-C1'' option
(especially if the current directory contains many tree files from
previous runs). Remember that you must specify the unit to check to
AdaControl, and the tree file to ASIS. I.e., if you want to check the
unit ``Example'', the command line should look like:
@example
adactl -f rules_file.aru example -- -FT -C1 example.adt
@end example
provided the tree file already exists.
@item
For each strategy, first run AdaControl with the default options
(which will create all necessary tree files). Compare execution time
with the one you get with ``-FT'' and ``-FS''. This will tell you if
compiling on-the-fly is more efficient than loading tree files, or not.
@end itemize

@node In case of trouble,  , Optimizing Adacontrol, Program Usage
@section In case of trouble
@subsection Known issues
If you are using an old version of GNAT and your project includes
source files located in several directories, the ADA_INCLUDE_PATH
environment variable may not be considered by ASIS, resulting in error
messages that tell you that the bodies of some units have not been
found (and hence have not been processed). This problem has been fixed
in GNAT dated later than Sept. 1st, 2006. If this happens, either
provide your source directories as ``-I'' options (@pxref{ASIS
options}), or generate the tree files manually (@pxref{Generating tree
files manually}). Note that this problem does not happen if you are
using a project file (@pxref{Project files}), nor if you are
running AdaControl from GPS.

@subsection AdaControl or ASIS failure
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 @i{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. @xref{Inhibit command}.

If you encounter a problem while using AdaControl, you are very
welcome to report it through our
@url{https://sourceforge.net/p/adacontrol/tickets/,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).

@node Command language reference, Rules reference, Program Usage, Top
@chapter Command language reference
AdaControl is about @i{controlling rules}. @i{Rules} are built in
AdaControl; each rule has a name, and may require parameters. For the
complete description of each rule, @pxref{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; @xref{Interactive
mode}.

@menu
* General::
* Controls::
* Other commands::
* Example of commands::
@end menu

@node General, Controls, Command language reference, Command language reference
@section General
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 ``-@w{}-'', 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. @xref{Syntax of regular expressions}.

If a syntax error is encountered in a command, an appropriate error
message is output, and analysis of the rules file continues in order
to output all errors, but no analysis of user code will be performed.

@node Controls, Other commands, General, Command language reference
@section Controls
A @i{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:
@example
<control_command> ::= [<label> ":"] <control> @{"," <control>@} ";"
<control>    ::= <ctrl_kind> <Rule_Name> [<parameters>]
<parameters> ::= "(" [<modifiers>] <value>
                @{"," [<modifiers>] <value>@} ")"
<ctrl_kind>  ::= "check"|"search"|"count"
@end example

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).  @xref{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 (@code{"}), in which case it can contain any character.

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.

Here are some examples of commands:
@example
check unnecessary_use_clause;
All_Imports: search pragmas (Import);
"Why do you need that?": check entities (Unchecked_Conversion,
                                         all 'Address);
@end example

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:
@example
"Check why this obsolete stuff is still used":
   check entities (obsolete_unit_1),     -- Note comma here!
   check instantiations (some_obsolete_generic);
@end example

@menu
* Control kinds and report messages::
* Parameters::
* Multiple controls::
* Disabling controls::
@end menu

@node Control kinds and report messages, Parameters, Controls, Controls
@subsection Control kinds and report messages
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).

``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.

A report message (except for the final report of ``count'') comprises
the following elements:
@itemize
@item
the file name (where the control matches)
@item
the line number (where the control matches)
@item
the column number (where the control matches)
@item
the label (if there is one) and/or the rule name (the rule that matches).
@item
a message (why the control matches). A control whose kind is ``check''
will produce an error report message (i.e. containing the keyword
``Error'') and a control whose kind is ``search'' will produce a
found report message (i.e. containing the keyword ``Found'').
@end itemize

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) or ``Gnat_Short'', 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'' or ``CSV_Short'', 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,
except Excel(tm) by default, which uses the semicolon and not the
comma to separate fields. Therefore, the formats ``CSVX'' and
``CSVX_Short'' do the same thing, but using semi-colons (';') instead
of commas. 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'' or ``Source_Short'', 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 @i{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.

With recent versions of GNAT, the file name includes the full path of
the source file. If the ``_Short'' form of the format option is used,
the file name is stripped from any path. This can make it easier to
compare the results of controlling units from various directories.
Note that with older versions of GNAT, the file name never includes
the full path, and the ``_Short'' form of the format option has no
effect.

After each run (@pxref{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:
@itemize
@item
0: No statistics are output (default)
@item
1: A count of error and warning messages is output
@item
2: The rule name and label (if any) of any control @i{not} triggered are
output
@item
3: The rule name and label (if any) of every control is output,
together with a count of each triggering kind (``check'', ``search'',
``count''), or ``not triggered'' if the control was not triggered.
@end itemize

@node Parameters, Multiple controls, Control kinds and report messages, Controls
@subsection Parameters
Most rules accept parameters. Parameters can be:
@itemize
@item
a keyword for the rule
@item
a numerical value
@item
a character string (often a regular expression)
@item
an Ada entity name
@end itemize

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 @ref{Specifying an Ada entity name} for the full
description of the syntax. Here are some examples of entity names:
@example
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
@end example

@node Multiple controls, Disabling controls, Parameters, Controls
@subsection Multiple 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 rules files produce an identical configuration:
@example
Search Pragmas (Pure, Elaborate_All);
@end example
and
@example
Search Pragmas (Pure);
Search Pragmas (Elaborate_All);
@end example

However, the second form can be used to give different labels. Consider:
@example
Search Pragmas (Pure);
No_Elaborate: Search Pragmas (Elaborate_All);
@end example

The messages for pragma @code{Pure} will contain ``PRAGMAS'', while
those for @code{Elaborate_All} will contain ``No_Elaborate''. If a
disabling comment mentions @code{pragmas}, it will disable both controls,
but a disabling comment that mentions @code{No_Elaborate} will disable
only the second one.

@node  Disabling controls,  , Multiple controls, Controls
@subsection Disabling 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 (@code{--}) is immediately followed by the special
tag ``@code{##}'' (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 ``@code{--##}'' 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. @xref{Set command}.

@subsubsection Block disabling
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:
@example
--## rule off <control_list>
Ada code block
--## rule on <control_list>
@end example

Ex:
@example
--## rule off rule1 rule2 ## Authorized by QA ref 1234
I := I + 1;
Proc (I);
--## rule on rule2
@end example

@subsubsection Line disabling
A control is disabled only for the line where a marker that applies to
it appears.

Syntax:
@example
Ada code line --## rule line off <rule_list>
@end example
Ex:
@example
I := I + 1; --## rule line off rule3 rule_label_1
@end example
Conversely, it is possible to re-enable a control for just the current
line in a block where it is disabled:

Syntax:
@example
Ada code line --## rule line on <rule_list>
@end example
Ex:
@example
--## rule off rule1 rule2
...
I := I + 1; --## rule line on rule2
@end example

@subsection Limitation
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. @xref{Header_Comments}.

@node  Other commands, Example of commands, Controls, Command language reference
@section Other commands
In addition to controls, AdaControl recognizes a number
of commands. Although these commands are especially useful when using
the interactive mode (@pxref{Interactive mode}), they can be used in
command files as well.

@menu
* Go command::
* Quit command::
* Message command::
* Help command::
* Clear command::
* Set command::
* Source command::
* Inhibit command::
@end menu

@node Go command, Quit command, Other commands, Other commands
@subsection Go command
This command starts processing of the controls that have been
specified.

Syntax:
@example
go;
@end example
Controls are @i{not} reset after a ``go'' command; for example, the
following program:
@example
search entities (pack1);
go;
search entities (pack2);
go;
@end example
will first output all usages of @code{Pack1}, then all usages of both
@code{Pack1} and @code{Pack2}. See @ref{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 rules files.

@node Quit command, Message command, Go command, Other commands
@subsection Quit command
This command terminates AdaControl.

Syntax:
@example
quit;
@end example
If given in a file, all subsequent commands will be ignored. This
command is really useful only in interactive mode. @xref{Interactive
mode}.

@node Message command, Help command, Quit command, Other commands
@subsection Message command
This command prints a message on the output file.

Syntax:
@example
message "<any string>" [pause];
@end example
The length of the message is limited to 250 characters. If the word
``pause'' (case irrelevant) is specified after the message, 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).

@node Help command, Clear command, Message command, Other commands
@subsection Help command
This command prints various informations about the rules and AdaControl
itself.

Syntax:
@example
Help [<help_item> @{,<help_item>@}]
<Help_Item> ::=<keyword> | <rule name> | variables ["<pattern>"]
<keyword>   ::= all   | commands | license | list | options |
                rules | version
@end example
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 @ref{Getting help} for the details.

@node Clear command, Set command, Help command, Other commands
@subsection Clear command
This command command clears (i.e. removes) controls that have been
previously given.

Syntax:
@example
Clear all | <rule name>@{,<rule name>@} ;
@end example
The command clears all controls given for the indicated rules, or for
all rules if the @code{all} keyword is given. Rule variables
(@pxref{Set command}) associated to cleared rules are returned to
their default values. For example, the following program:
@example
search entities (pack1);
go;
clear all;
search entities (pack2);
go;
@end example
will first output all usages of @code{Pack1}, then all usages of
@code{Pack2}. Without the ``clear all'' command, the second ``go''
would output all usages of @code{Pack1} together with all usages of
@code{Pack2}.

@node Set command, Source command, Clear command, Other commands
@subsection Set command
This command sets various parameters of AdaControl.

Syntax:
@example
set Format Gnat|Gnat_Short|CSV|CSV_Short|Source|Source_short|None;
set Check_Key|Search_Key "<value>"
set Max_Errors [<value>];
set Max_Messages [<value>];
set Output|New_Output <output file>;
set Statistics <level>;
set Tag1|Tag2 "<value>";
set Trace <trace file>;
set Debug|Exit_On_Error|Verbose|Warning|Warning_As_Error
      On|Off;
set Timing On|Off|Global
set Ignore On|Off|Inverted;
set <Rule_Name>.<Variable> <Value>
@end example
The ``set format'' command selects the output format for the messages,
like the ``-F'' option; see @ref{Control kinds and report messages} 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 max_errors'' and ``set max_messages'' limit the output of
AdaControl, like the ``-m'' and ``-M'' options; see @ref{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
@code{console} (case irrelevant) is given as the <output file>, output
is redirected to the console.

The ``set new_output'' always create a new file (or overwrites an
existing file with the same name).

The ``set output'' command appends if the file exists, unless the
``-w'' option is given, in which case it is overwritten. However, the
file is overwritten only the first time it is mentionned in an
``output'' command. This means that you can switch forth and back
between two output files, all results from the same run will be
kept. Note however that for this to work, you need to specify the
output file exactly the same way: if you specify it once as
``result.txt'', and then as ``./result.txt'', the second one will
overwrite the first one.

The ``set statistics'' command sets the statistics level, like the
``-S'' option;  see @ref{Control kinds and 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 (@code{--}), 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 @ref{Disabling
controls} for details.

The ``set trace'' command redirects the trace messages of the
``-d'' option to the indicated file. If the string @code{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 Debug|Exit_On_Error|Verbose|Warning|Warning_As_Error''
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, ``Timing'' to the ``-T''
option, ``Verbose'' to the ``-v'' option, ``Warning'' to the ``-E''
option, and ``Warning_As_Error'' to the ``-e'' option. See
@ref{Verbose and debug mode}, @ref{Exit on error}, @ref{Treatment of
warnings}, @ref{Output format}, and @ref{Local disabling control} for
details.

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.

The ``set Ignore'' command governs handling of disabled messages
(@pxref{Disabling controls}). In default mode (``set Ignore Off''),
disabled messages are not printed. When set to ``on'' (``set Ignore
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'' (``set Ignore
Inverted''), @i{only} disabled messages are printed. This is useful to
check which messages have been disabled.

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.

@node Source command, Inhibit command, Set command, Other commands
@subsection Source command
This command inputs commands from another file.

Syntax:
@example
Source <input file>;
@end example
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 @code{ADACTL_PATH}.

The default extension is @code{.aru}, i.e. if <input file> is not
found as given, AdaControl will retry the same name with @code{.aru}
appended. It is a syntax error if the file is not found either.

If the string @code{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.

@node Inhibit command,  , Source command, Other commands
@subsection Inhibit command
This command prevents execution of certain controls on particular units.

Syntax:
@example
Inhibit <rule name>|all ([all] <unit> @{,[all] <unit>@});
@end example
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:
@itemize
@item
The unit is known not to obey the rule in many places, and you don't
want the output to be cluttered with too many messages (of course,
you'll fix the unit in the near future!);
@item
The unit is known to obey the rule, execution of the rule is
time-consuming, and you want to save some processing time;
@item
The unit is known to raise an ASIS bug, and until you upgrade to the
appropriate version of GNAT, you don't want to be bothered by the
error messages.
@end itemize

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.

@node Example of commands,  , Other commands, Command language reference
@section Example of commands
Below is an example of a file with multiple commands:
@example
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;
@end example
This file will output all usages of @code{Ada.Unchecked_Conversion}
into the file @code{uc_usage.txt}, then output all usages of the
@code{'Address} attribute into the file
@code{address_usage.txt}. Messages are output to tell the user about
what's happenning.

@node  Rules reference, Examples of using AdaControl for common programming rules, Command language reference, Top
@chapter Rules reference
This chapter describes each rule currently provided by
AdaControl. Note that the @code{rules} directory of the distribution
contains a file named @code{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 @i{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.

@menu
* Abnormal_Function_Return::
* Allocators::
* Array_Declarations::
* Aspects::
* Assignments::
* Barrier_Expressions::
* Case_Statement::
* Characters::
* Comments::
* Declarations::
* Default_Parameter::
* Dependencies::
* Derivations::
* Directly_Accessed_Globals::
* Duplicate_Initialization_Calls::
* Entities::
* Entity_Inside_Exception::
* Exception_Propagation::
* Expressions::
* Generic_Aliasing::
* Global_References::
* Header_Comments::
* Improper_Initialization::
* Instantiations::
* Insufficient_Parameters::
* Local_Access::
* Local_Hiding::
* Max_Blank_Lines::
* Max_Call_Depth::
* Max_Line_Length::
* Max_Nesting::
* Max_Size::
* Max_Statement_Nesting::
* Movable_Accept_Statements::
* Naming_Convention::
* No_Operator_Usage::
* Non_Static::
* Not_Elaboration_Calls::
* Not_Selected_Name::
* Object_Declarations::
* Parameter_Aliasing::
* Parameter_Declarations::
* Positional_Associations::
* Potentially_Blocking_Operations::
* Pragmas::
* Record_Declarations::
* Reduceable_Scope::
* Representation_Clauses::
* Return_Type::
* Side_Effect_Parameters::
* Silent_Exceptions::
* Simplifiable_Expressions::
* Simplifiable_Statements::
* Statements::
* Style::
* Terminating_Tasks::
* Type_Initial_Values::
* Type_Usage::
* Uncheckable::
* Unit_Pattern::
* Units::
* Unnecessary_Use_Clause::
* Unsafe_Elaboration::
* Unsafe_Paired_Calls::
* Unsafe_Unchecked_Conversion::
* Usage::
* Use_Clauses::
* With_Clauses::
@end menu

@node Abnormal_Function_Return, Allocators, Rules reference, Rules reference
@section Abnormal_Function_Return
This rule controls functions that may not terminate normally, i.e. where
@code{Program_Error} could be raised due to reaching the end of the
function without encountering a @code{@b{return}} statement.

@subsection Syntax
@example
<control_kind> abnormal_function_return;
@end example

@subsection Action
The rule controls that the sequence of statements of each function
body, as well as each of its exception handlers, ends with:
@itemize @bullet
@item
a @code{@b{return}} statement (including extended return statements)
@item
a @code{@b{raise}} statement (or equivalently, a call to
@code{Ada.Exceptions.Raise_Exception} or
@code{Ada.Exceptions.Reraise_Occurrence});
@item
a call to a procedure which is the target of a @code{@b{pragma} No_Return};
@item
a block statement, whose last statement of its sequence and any
exception handler is one of these;
@item
an @code{@b{if}} statement that includes an @code{@b{else}} path, and
where the last statement of every  path is one of these;
@item
a @code{@b{case}} statement where the last statement of every  path is
one of these.
@item
a plain @code{@b{loop}} statement (not @code{@b{for}} or
@code{@b{while}}) without any @code{@b{exit}} or  @code{@b{goto}}
statement transfering control outside of the loop.
@end itemize

This is a sufficient (but of course not necessary) condition to ensure
that no function raises @code{Program_Error} due to reaching the end
of its statements without encountering a @code{@b{return}}.

This rule can be specified only once.

Ex:
@example
check abnormal_function_return;
@end example

@subsection Tips
This rule checks that a function always returns correctly, but does not
prevent multiple @code{@b{return}} statements in functions. If you want
to ensure that there is exactly one @code{@b{return}} statement in functions,
and that this statement is always the last one, use this rule together with
the rule @code{statements(function_return)}.
@xref{Statements}.

It is possible to exit from an extended return statement with an
@code{@b{exit}} or @code{@b{goto}} statement. If this happens, the
return statement is not considered a proper return statement, and an
appropriate message is issued.

@node Allocators, Array_Declarations, Abnormal_Function_Return, Rules reference
@section Allocators
This rule controls the use of allocators (i.e. dynamic memory allocation).
@subsection Syntax
@example
<control_kind> allocators [(<target> @{, <target>@})];
<target>   ::= [anonymous | inconsistent | not] [<category>|<entity>]
<category> ::= ()  | access    | array | delta  | digits |
               mod | protected | range | record | tagged | task
@end example

@subsection Action
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>. @xref{Specifying an Ada entity name}. The meaning of
<category> is:
@itemize @bullet
@item
``()'': The allocated value is of an enumerated type.
@item
``access'':  The allocated value is of an access type.
@item
``array'': The allocated value is of an array type.
@item
``delta'': The allocated value is of a fixed point type (it is not currently
possible to distinguish ordinary fixed point types from decimal fixed
point types).
@item
``digits'': The allocated value is of a floating point type.
@item
``mod'': The allocated value is of a modular type.
@item
``protected'': The allocated value is of a protected type.
@item
``range'': The allocated value is of a signed integer type.
@item
``record'': The allocated value is of an (untagged) record type.
@item
``tagged'': The allocated value is of a tagged type (including type
extensions).
@item
``task'': The allocated value is of a task type.
@end itemize

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 ``@code{@b{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:
@itemize @bullet
@item
when it is a class-wide type, since the allocator subtype will
generally be of some descendant specific type;
@item
when it is an unconstrained array type, since the allocated subtype is
necessarily constrained;
@item
when it is a base type (of the form @code{T'Base}).
@end itemize

Note that if the access type includes a constraint like in the
following example:
@example
   @b{type} Acc @b{is} @b{access} integer @b{range} 1..10;
@end example
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:
@example
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);
@end example

@subsection Tips
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
@code{@b{new}} keyword, which is not necessarily the same as the
expected type in presence of implicit conversions like this:

@example
   @b{type} T @b{is} @b{tagged} ...;
   @b{type} Class_Access @b{is} @b{access} T'Class;
   X : Class_Access;
begin
   X := @b{new} T;
@end example

This allocator will be found for type @code{T}, not for type @code{T'Class}.

For <categories>, note that the rule ``sees through'' derived and
private types (i.e. it will trigger if the ultimate type belongs to
the indicated category).

The reason for the ``inconsistent'' modifier is that inconsistent
allocators may cost a double check. Given:
@example
   @b{type} Acc @b{is} @b{access} Positive;
   V : Acc;
@b{begin}
   V := @b{new} Natural'(...);
@end example
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.
@subsection Limitations
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''.
@xref{Uncheckable}.

@node Array_Declarations, Aspects, Allocators, Rules reference
@section Array_Declarations
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.
@subsection Syntax
@example
<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>
<category > ::= () | access    | array | delta  | digits | mod | private
                   | protected | range | record | tagged | task
<repr_cond> ::= [not] pack | size | component_size
@end example
@subsection Action
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:
@itemize
@item
``First'' and ``Last'' control the lower (respectively upper) bound of
each dimension of arrays (even unconstrained array types). If a single
value is specified without the ``min'' or ``max'' modifiers, the
subrule controls the bounds that are not exactly this value;
otherwise, it controls the bounds that are smaller than the given
``min'' value or greater than the given ``max'' value. It is possible,
but not required to specify both ``min'' and ``max''. If this subrule
is given both for ``search'' and for ``check'', the value(s) for
``search'' is interpreted as the prefered one, and the value(s) for
``check'' is interpreted as an alternative acceptable one; i.e., it is
a warning if the value is the one given for ``check'', and an error if
it is neither. In short:
@example
search array_declarations (first, 1);
check array_declarations (first, min -1, max 1);
@end example
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.
@item
``Dimensions''controls the number of dimensions of arrays. If a single
value is specified without the ``min'' or ``max'' modifiers, the
subrule controls arrays whose number of dimensions is not exactly this
value; otherwise, it controls arrays whose number of dimensions are
smaller than the given ``min'' value or greater than the given ``max''
value. It is possible, but not required to specify both ``min'' and
``max''. If this subrule is given both for ``search'' and for
``check'', the value(s) for ``search'' is interpreted as the prefered
one, and the value(s) for ``check'' is interpreted as an alternative
acceptable one; i.e., it is a warning if the value is the one given
for ``check'', and an error if it is neither. In short:
@example
search array_declarations (Dimensions, 1);
check array_declarations (Dimensions, min 2, max 3);
@end example
will be silent for one-dimensional arrays, it will issue a warning for
2- and 3-dimensional arrays, and an error otherwise.
@item
``Length'' controls arrays that have a dimension whose number of
elements is smaller than the given ``min'' value or greater than the
given ``max'' value (except for unconstrained array types). At least
one of ``min'' or ``max'' must be specified, but it is not required to
specify both.

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:
@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"
@end example

@item
``Component'' controls arrays whose component type is the indicated
<entity>, or whose component type belongs to the indicated
<category>. If the <entity> is a subtype, only arrays whose components
are of that subtype are controlled. If the indicated <entity> is a
type, all arrays whose components are of that type (including
subtypes) are controlled. The meaning of <category> is:
@itemize @bullet
@item
``()'': The component is of an enumerated type.
@item
``access'':  The component is of an access type.
@item
``array'': The component is of an array type.
@item
``delta'': The component is of a fixed point type (it is not currently
possible to distinguish ordinary fixed point types from decimal fixed
point types).
@item
``digits'': The component is of a floating point type.
@item
``mod'': The component is of a modular type.
@item
``private'': The component is of a private type (including private
extensions).
@item
``protected'': The component is of a protected type.
@item
``range'': The component is of a signed integer type.
@item
``record'': The component is of an (untagged) record type.
@item
``tagged'': The component is of a tagged type (including type
extensions).
@item
``task'': The component is of a task type.
@end itemize
If <repr_cond> are specified, the rule controls only arrays to which
all the corresponding representation items apply:
@itemize @bullet
@item
``pack'': A pragma Pack applies to the array.
@item
``not pack'': No pragma Pack applies to the array.
@item
``size'': A size representation clause applies to the array.
@item
``not size'': No size representation clause applies to the array.
@item
``component_size'': A component_size representation clause applies to
the array.
@item
``not component_size'': No component_size representation clause
applies to the array.
@end itemize

@item
``index'' controls arrays whose index types are the indicated
<entity>, or whose index types belong to the indicated <category>. If
the <entity> is a subtype, only arrays whose indexes are of that
subtype are controlled. If the indicated <entity> is a type, all
arrays whose indexes are of that type (including subtypes) are
controlled. The meaning of <category> is the same as for
``component'', but obviously only ``()'', ``range'', and ``mod'' are
allowed.

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.
@end itemize

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:
@example
-- 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, <>, (), <>);
@end example

@subsection Tips
The subrule @code{Max_Length} ignores index constraints that are not
static.  Non static index constraints can be controlled with the rule
@code{Non_Static (Index_Constraint)}. @xref{Non_Static}.

Requiring the same @i{upper} bound for all arrays is not very useful, but:
@example
check array_declarations (last, min 1);
@end example
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''. @xref{Type_Usage}.

@node Aspects, Assignments, Array_Declarations, Rules reference
@section Aspects
This rule controls aspect specifications (new feature in Ada 2012), either
all of them or specific ones.
@subsection Syntax
@example
<control_kind> aspects [(all | <aspect mark> @{, <aspect mark>@})];
@end example
@subsection Action
Without parameters (or if ``all'' is given), controls all aspect
specifications. Otherwise, controls only the aspect specifications
corresponding to the given aspect marks.

Ex:
@example
search aspects;
DBC: check aspects (Pre, Post, Pre'Class, Post'Class);
@end example

@node  Assignments, Barrier_Expressions, Aspects, Rules reference
@section Assignments
This rule controls various issues related to the assignment
statement: assignments that involve array sliding, redundant
assignments to the same variable, or groups of assignments that are
replaceable by aggregate assignment.

@subsection Syntax
@example
<control_kind> assignments (sliding);
<control_kind> assignments (repeated);
<control_kind> assignments (groupable, <filter> @{,<filter>@});
<filter> ::= given <min_val> | missing <max_val> | ratio <min_val> |
             total <max_val>
@end example

@subsection Action
The first form (keyword ``sliding'') controls array assignments where
the target variable has a different lower bound than the assigned
expression; this is allowed by the language only in so-called
``sliding'' contexts.

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).

The second form (keyword ``repeated'') controls when a same variable
(or a same subcomponent of a structured variable) is assigned several
times in the same group of assignments. This form of the rule can be
given only once.

The third form (keyword ``groupable'') controls assignments to
different subcomponents of a same structured variable; such
assignments are often replaceable by a global assignment of an
aggregate to the variable. One or several <filter> parameters
indicate under which conditions a group is reported:
@itemize @bullet
@item
``given'': <min_val> (an integer value) indicates the minimum number
of assigned subcomponents that will trigger the rule (i.e. the rule is
triggered if  the number of assignments to subcomponents of a same
variable is greater or equal to the indicated value).
@item
``missing'': <max_val> (an integer value) indicates the maximum number
of subcomponents not assigned that will trigger the rule (i.e. the
rule is triggered if  the number of subcomponents not assigned to is
lesser or equal to the indicated value).
@item
``ratio'': <min_val> (an integer value) indicates the minimum
percentage of assigned subcomponents that will trigger the rule
(i.e. the rule is triggered if  the percentage of assigned
subcomponents is greater or equal to the indicated value).
@item
``total'': <max_val> (an integer value) indicates the maximum number
of subcomponents of the type that will trigger the rule (i.e. the
rule is triggered if  the number of subcomponents of the record type is
lesser or equal to the indicated value).
@end itemize

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 @i{not} triggered on an object if a subcomponent of that object
is of a limited 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 @i{should} have been assigned
in full (in other words: if the rule is triggered on those
subcomponents as well) - recursively, of course.

Ex:
@example
search Assignments (sliding);
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);
@end example

@subsection Tip
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.

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.

@subsection Limitations
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.

@node Barrier_Expressions, Case_Statement, Assignments, Rules reference
@section Barrier_Expressions
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.
@subsection Syntax
@example
<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
@end example
@subsection Action
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:
@itemize @bullet
@item
Any <entity> (like a global variable, a function...) can be specified
and is thus allowed. As usual, the whole syntax for entities is allowed for
<entity>. @xref{Specifying an Ada entity name}.
@item
``allocation'' allows use of allocators.
@item
``any_component'' allows use of protected components that are not of
type @code{Standard.Boolean}.
@item
``any_variable'' allows use of any variable (i.e. variables external to
the protected element).
@item
``arithmetic_operator'' allows use of predefined arithmetic operators
(@code{"+"}, @code{"**"}, etc.).
@item
``array_aggregate'' allows use of array aggregates.
@item
``comparison_operator'' allows use of predefined comparison and
membership operators (@code{"="}, @code{">"}, @code{@b{in}}, etc.).
@item
``conversion'' allows use of type conversions and type qualifications.
@item
``dereference'' allows use of dereferencing of access types (both implicit
and explicit dereferences).
@item
``indexing'' allows use of array indexing and slices.
@item
``function_attribute'' allows use of attributes that are functions
(like @code{'Pred}, @code{'Image}, etc.).
@item
``local_function'' allows use of (protected) functions declared in the
same protected object.
@item
``logical_operator'' allows use of predefined logical operators and
short-circuit forms (@code{@b{and}}, @code{@b{or else}}, etc.).
@item
``record_aggregate'' allows use of record aggregates and extension
aggregates.
@item
``value_attribute'' allows use of attributes that are simple values
(like @code{'First}, @code{'Terminated}, etc.).
@end itemize

This rule can be given only once for each of ``check'', ``search'' and
``count''.

Ex:
@example
search barrier_expressions;
check  barrier_expressions (logical_operator, comparison_operator,
                            any_component,
                            Pack.Global_State);
@end example

@subsection Tips
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.

@node Case_Statement, Characters, Barrier_Expressions, Rules reference
@section Case_Statement
This rule controls various metrics related to the @code{@b{case}}
statement.  It is intended for cases where it is desired to limit the
complexity of @code{@b{case}} statements.
@subsection Syntax
@example
<control_kind> Case_Statement (<subrule>, <bound> [, <bound>]);
<subrule> ::= others_span      | paths | range_span | values |
              values_if_others
<bound>   ::= min | max <value>
@end example

@subsection Action
The first parameter is a subrule keyword. 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. The parameters controlled by each subrule are:
@itemize
@item
``others_span'' controls the number of values covered by
@code{@b{when}} @code{@b{others}} case alternatives.
@item
``paths'' controls the number of paths (i.e. @code{@b{when}} branches).
@item
``range_span'' controls the number of values covered by ranges used as
choices.
@item
``values'' controls the number of values covered by the subtype
of the @code{@b{case}} selector.
@item
``values_if_others'' is like ``values'', but is activated only for
@code{@b{case}} statements with a @code{@b{when}} @code{@b{others}}
alternative.
@end itemize

This rule 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:
@example
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);
@end example

@subsection Tips
To control that no range is used as a choice in a @code{@b{case}}
statement:
@example
check case_statement (range_span, max 0);
@end example

To control ``@code{@b{when}} @code{@b{others}}'' that
cover no value at all:
@example
check case_statement (others_span, min 1);
@end example

@subsection Limitations
If some characteristic of the @code{@b{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''. @xref{Uncheckable}.

If the subtype of the selecting expression of the @code{@b{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''. @xref{Uncheckable}. We hope to be able to
remove this limitation in the future, but the problem is quite
difficult...

@node  Characters, Comments, Case_Statement, Rules reference
@section Characters
This rule makes sure that the program text does not use
``undesirable'' characters.
@subsection Syntax
@example
<control_kind> characters [(<subrule> @{, <subrule>@})];
<subrule> ::= control | not_iso_646 | trailing_space | wide
@end example

@subsection Action
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:
@itemize @bullet
@item
``control'': control characters that are allowed by the language
(ASCII HT,  ASCII VT and ASCII FF).
@item
``not_iso_646'': characters outside the ISO-646 set (aka ASCII).
@item
``trailing_space'': space characters appearing at the end of the
source line.
@item
``wide'': wide characters that are not in @code{Standard.Character}.
@end itemize

This rule can be given only once for each class of characters.

Ex:
@example
check characters (control, trailing_space);
search characters (not_iso_646);
@end example

@subsection Limitations
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):
@example
S : Wide_String := "["1041"]["1042"]";
@end example
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
@code{'Val} attribute) are not controlled.

@node  Comments, Declarations, Characters, Rules reference
@section Comments
This rule controls comments that must, or must not, appear in certain cases.

@subsection Syntax
@example
<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>@});
<bounds>    ::= min|max <value> [, min|max <value> ]
<kind>      ::= [<condition>] <unit_kind>
<condition> ::= always | declaration | program_unit
<unit_kind> ::= all | procedure | function | entry | package | task
@end example

@subsection Action
The first parameter is a subrule name which detemines what is being
controlled.
@itemize @bullet
@item
``pattern'' controls comments that match one of the given patterns
(given as strings). Only the ``useful'' part of the comment is
matched against the patterns, i.e. the part after the ``@code{--}''
and spaces following it. Patterns are given using the full Regexp
syntax. @pxref{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.
@item
``position'' controls the starting position of comments. If a single
value is specified without the ``min'' or ``max'' modifiers, the
subrule controls comments that do not start exactly at the indicated
column position; otherwise, it controls comments whose starting column
is smaller than the given ``min'' value or greater than the given
``max'' value. It is possible, but not required to specify both
``min'' and ``max''. If this subrule is given both for ``search'' and
for ``check'', the value(s) for ``search'' is interpreted as the
prefered one, and the value(s) for ``check'' is interpreted as an
alternative acceptable one; i.e., it is a warning if the value is the
one given for ``check'', and an error if it is neither. In short:
@example
search comments (position, 1);
check  comments (position, min 1, max 6);
@end example
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.

@item
``terminating'' controls comments that are at the end of an otherwise
non empty line (i.e. that appear on the same line as a declaration or
statement). If ``begin'' is specified, comments appearing on a line
that contains only a @code{@b{begin}} are allowed (not reported);
similarly, if ``end'' is specified, comments appearing on a line that
contains only an @code{@b{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.
@pxref{Syntax of regular expressions} for details. Pattern matching is
always case insensitive.
@item
``unnamed_begin'' controls @code{@b{begin}} of various constructs that
do not have a comment that repeats the name of the program unit
associated to the @code{@b{begin}}. Except for spaces, the comment
must not contain anything else than the unit name.

The <condition> keyword determines circumstances where the comment is required:
@itemize
@item
''always'' (default): the comment is always required.
@item
``declaration'': the comment is required only if the preceding
declaration part is non-empty (not counting pragmas).
@item
``program_unit'': the comment is required only if the preceding
declaration part contains the declarations of other program units
(subprograms, packages, protected objects, or tasks).
@end itemize

The <unit_kind> keyword detemines the kind of program unit to which
the rule applies (``all'' stands for all kinds).  The subrule can be
given only once of each kind of program unit.
@end itemize

Ex:
@example
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 example

@subsection Tips
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.

@subsection Limitations
This rule does not support wide characters outside the basic Latin-1 set.

@node Declarations, Default_Parameter, Comments, Rules reference
@section Declarations
This rule controls usage of various kinds of declarations, possibly only
those occurring at specified locations.
@subsection Syntax
@example
<control_kind> declarations (<subrule> @{, <subrule>@});
<subrule>     ::= @{[not] <location_kw>@} <declaration_kw>
<location_kw> ::= all | block   | library | local      | nested |
                  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_unconstrained_array_type  | access_unknown_discriminated_type |
  access_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       | controlled_type                   |
  decimal_fixed_type               | defaulted_discriminant            |
  defaulted_generic_parameter      | defaulted_parameter               |
  deferred_constant                | derived_type                      |
  discriminant                     | empty_private_part                |
  empty_visible_part               | enumeration_type                  |
  entry                            | equality_operator                 |
  exception                        | expression_function               |
  extension                        | fixed_type                        |
  float_type                       | formal_function                   |
  formal_package                   | formal_procedure                  |
  formal_type                      | function                          |
  function_call_renaming           | function_instantiation            |
  generic                          | generic_function                  |
  generic_package                  | generic_procedure                 |
  handlers                         | incomplete_type                   |
  in_out_generic_parameter         | in_out_parameter                  |
  initialized_protected_component  | initialized_record_component      |
  initialized_variable             | instantiation                     |
  integer_type                     | interface_type                    |
  library_unit_renaming            | 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_identical_operator_renaming   |
  non_identical_renaming           | non_joint_ce_ne_handler           |
  non_limited_private_type         | non_ravenscar_task                |
  not_operator_renaming            | null_defaulted_formal_procedure   |
  null_extension                   | null_ordinary_record_type         |
  null_procedure                   | null_procedure_body               |
  null_procedure_declaration       | null_tagged_type                  |
  operator                         | operator_renaming                 |
  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                   |
  renaming                         | renaming_as_body                  |
  renaming_as_declaration          | scalar_variable                   |
  self_calling_function            | self_calling_procedure            |
  separate                         | signed_type                       |
  single_array                     | single_protected                  |
  single_task                      | subtype                           |
  synonym_renaming                 | 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
@end example

@subsection Action
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''.
@itemize @bullet
@item
@code{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.
@item
@code{block}: only declarations appearing in block statements are controlled.
@item
@code{library}: only library level declarations are controlled.
@item
@code{local}: only local declarations are controlled (i.e. only declarations
appearing in (generic) packages, possibly nested, are allowed).
@item
@code{own}: only declarations that are local to a (generic) package body
are controlled.
@item
@code{public}: only declarations appearing in the visible part of
(generic) packages are controlled.
@item
@code{private}: only declarations appearing directly in a private
part are controlled.
@item
@code{in_generic}: only declarations appearing directly or indirectly in a generic
specification or body are controlled.
@item
@code{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 @i{specifications}, since only entries can
appear there, and they cannot appear anywhere else.
@end itemize

The <declaration_kw> specifies what kind of declaration to control:
@itemize @bullet
@item
Declaration keywords that are Ada keywords match the corresponding Ada
declarations.
@item
@code{any_declaration} controls all declarations. This is of course not
intended to forbid all declarations in a program (!), but
@emph{counting} all declarations can be quite useful.
@item
@code{abstract_function}, @code{abstract_operator}, and
@code{abstract_procedure} control the declarations of abstract
functions, abstract operators, and abstract procedures, respectively.
@item
@code{abstract_type} controls the declaration of non-formal abstract
types.
@item
@code{access_type} controls all access type declarations, while
@code{access_subprogram_type}, @code{access_protected_type}, and
@code{access_task_type} control only access to procedures or
functions, access to protected types, or access to task types,
respectively. Similarly, @code{access_constrained_array_type} and
@code{access_unconstrained_array_type} control access to constrained
or unconstrained array types, @code{access_def_discriminated_type},
@code{access_nondef_discriminated_type}, and
@code{access_unknown_discriminated_type} control access to types with
discriminants with default values, without default values, and unknown
discriminants, respectively. @code{access_formal_type} controls access
to (generic) formal types, @code{access_all_type} control generalized
access to variables types (aka "@code{@b{access} @b{all} T}", and
@code{access_constant_type} control generalized access to constants
types (aka "@code{@b{access} @b{constant} T}"). @code{access_language_type}
controls access to language defined private types.
@item
@code{aliased_variable} and @code{aliased_constant} control the
declarations of aliased variables or constants, respectively.
@item
@code{aliased_array_component} controls the declaration of arrays
(array types or single arrays) whose components are declared aliased.
@item
@code{aliased_record_component} and @code{aliased_protected_component}
control the declarations of aliased record (respectively protected)
components.
@item
@code{anonymous_access_component} controls array and record components
that are of an anonymous access type (but not discriminants, which are
controlled by @code{anonymous_access_discriminant}). Similarly,
@code{anonymous_access_constant} and  @code{anonymous_access_variable}
control constants and  variables that are of an anonymous access type
(including generic formal @code{@b{in}} and @code{@b{in} @b{out}}
parameters, respectively). @code{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
@code{anonymous_access_parameter} is given on the specification and
not repeated on the body.
@item
@code{anonymous_subtype_declaration} controls the declarations of
anonymous subtypes and ranges that are part of some other
declaration. Similarly, @code{anonymous_subtype_allocator},
@code{anonymous_subtype_case}, @code{anonymous_subtype_for}, and
@code{anonymous_subtype_indexing} control anonymous subtype
declarations and ranges that are part of allocators, @code{@b{case}}
statements (ranges in the @code{@b{when}} path), @code{@b{for}} loop
statements, and indexing of slices or array aggregates, respectively.
@item
@code{array} controls all array definitions (array types and single
arrays), while @code{array_type} controls only array types and
@code{single_array} controls only single arrays (objects of an
anonymous array type). @code{constrained_array_type} controls only
constrained array types, while @code{unconstrained_array_type}
controls only unconstrained array
types. @code{constrained_array_variable} controls variable
declarations where the given (or anonymous) array type is constrained,
while @code{unconstrained_array variable} controls variable
declarations where the given (or anonymous) array type is
unconstrained (and the constraint is provided by the initial value).
@code{constrained_array_constant} and
@code{unconstrained_array_constant} do the same with constants instead
of variables.
@item
@code{character_literal} controls the declaration of new character
literals, i.e. character literals defined as part of the values of an
enumeration type.
@item
@code{child_unit} controls the declaration of all child units.
@item
@code{constant} controls all constants, while
@code{class_wide_constant} control the declaration of constants of a
class-wide type, and @code{deferred_constant} controls the declaration
of deferred constants.
@item
@code{controlled_type} controls the declaration of controlled types,
i.e. descendants of @code{Ada.Finalization.Controlled} or
@code{Ada.Finalization.Limited_Controlled}. Note that this includes
also private types that are not visibly controlled.
@item
@code{defaulted_parameter} controls subprogram or entry (@b{in})
parameters that provide a default value, while
@code{defaulted_generic_parameter} controls generic formal objects
that provide a default value.
@item
@code{derived_type} controls regular derived types, but not type
extensions (derivations of tagged types). These are controlled by
@code{extension} and @code{private_extension}.
@item
@code{discriminant} controls all declarations of types with
discriminants, while @code{protected_discriminant} and
@code{task_discriminant} control only discriminants of protected types
and task types, respectively.  @code{defaulted_discriminants} controls
only discriminants where default values are
provided. @code{unknown_discriminants} controls only unknown
discriminants (AKA ``@code{(<>)}'' discriminants).
@item
@code{empty_private_part} controls package specification with an empty
private part, i.e. where the word @code{@b{private}} appears, but the
private part contains no declaration (even if it contains pragmas).
@item
@code{empty_visible_part} controls package specifications that contain
no declaration in the visible part (before the word @code{@b{private}}
if any), even if it contains pragmas.
@item
@code{enumeration_type} controls the declaration of enumeration types.
@item
@code{exception} controls exception declarations.
@item
@code{expression_function} controls declaration of expression functions
@item
@code{extension} controls type extensions, i.e. derivations from a tagged type
with a @code{@b{with record}} extension part.
@item
@code{fixed_type} controls all declarations of fixed point types while
@code{ordinary_fixed_type} controls only ordinary (binary) fixed point
types, @code{ordinary_fixed_type_no_small} controls ordinary fixed
point type without a representation clause for @code{'SMALL},
@code{ordinary_fixed_type_with_small} controls ordinary fixed point
type with an explicit representation clause for @code{'SMALL}, and
@code{decimal_fixed_type} controls only decimal fixed point types
(those can never have a representation clause for @code{'SMALL}).
@item
@code{float_type} controls declarations of floating point types.
@item
@code{formal_function}, @code{formal_package},
@code{formal_procedure}, and @code{formal_type} control all generic
formal functions, packages, procedures, and types,
respectively. @code{box_defaulted_formal_function},
@code{box_defaulted_formal_procedure}, @code{name_defaulted_formal_function},
@code{name_defaulted_formal_procedure}, and
@code{null_defaulted_formal_procedure} control generic formal
functions and procedures with a box default, a name default, and a
null default, respectively.
@item
@code{generic_function}, @code{generic_package},
@code{generic_procedure} control generic function (respectively
package, procedure) declarations.
@item
@code{handlers} controls the presence of exception handlers in any
handled sequence of statements.
@item
@code{in_out_parameter} and @code{out_parameter} control subprogram
and entry parameters of modes @code{@b{in}} @code{@b{out}} and
@code{@b{out}} (respectively), while @code{in_out_generic_parameter}
and @code{out_generic_parameter} do the same for @i{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.
@item
@code{incomplete_type} controls (regular) incomplete type
declarations, while @code{tagged_incomplete_type} controls tagged
incomplete type declarations (Ada 2005).
@item
@code{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.
@item
@code{instantiation} controls all instantiations, while
@code{function_instantiation}, @code{package_instantiation},
@code{procedure_instantiation} control function (respectively package,
procedure) instantiations.
@item
@code{integer_type} controls all declarations of integer types, while
@code{signed_type} controls only signed integer types, and
@code{modular_type} controls only modular types (both kinds);
@code{binary_modular_type} controls only modular types whose modulus
is a power of 2, and @code{non_binary_modular_type} controls only
modular types whose modulus is not a power of 2.
@item
@code{initialized_record_component} and
@code{initialized_protected_component} control the declaration of
record (respectively protected) component that include a default
initialization, while @code{uninitialized_record_component} and
@code{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.
@item
@code{limited_private_type} controls limited private type
declarations, while @code{non_limited_private_type} controls regular
(non limited) private type declarations. @code{tagged_private_type}
controls tagged private type declarations.
@item
@code{multiple_names} controls declarations where more than one
defining identifier is given in the same declaration.
@item
@code{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.
@item
@code{named_number} controls declarations of named numbers,
i.e. untyped constants.
@item
@code{no_spec_function} and @code{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.
@item
@code{non_joint_CE_NE_handler} controls exception handlers whose
choices include @code{Constraint_Error} or @code{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).
@item
@code{null_extension} controls record extensions (derived tagged
types) that contain no new elements.  Similarly,
@code{null_ordinary_record_type} and @code{null_tagged_type} control
ordinary records and tagged types that contain no elements. Note that
the record definitions may be plain ``@code{@b{null}}
@code{@b{record}}'' definitions, or full record definitions that
contain only null components. However, a definition is not considered
null if it contains a variant part.
@item
@code{null_procedure_body} controls procedure declarations whose
sequence of statements contain only @code{@b{null}} statements (or
blocks without declarations and containing only @code{@b{null}}
statements).  @code{null_procedure_declaration} controls Ada2005 null
procedure declarations (i.e., ``@b{procedure} P @b{is}
@b{null};''). @code{null_procedure} controls both.
@item
@code{operator} controls the definition of operators (things like
@code{"+"}); note that the message is given on the specification if
there is an explicit specification, on the body
otherwise. @code{equality_operator} controls only equality operators
(@code{"="} and @code{"/="}) and @code{predefined_operator} controls
only operator definitions that overload a predefined operator (like
@code{"+"} on a numeric type, for example).
@item
@code{package_statements} controls the presence of elaboration
statements in the bodies of packages (or generic packages).
@item
@code{private_extension} controls private extensions, i.e. derivations
from a tagged type with a @code{@b{with private}} extension part.
@item
@code{record_type} controls all record type declarations (tagged or
not), while @code{ordinary_record_type} controls only non-tagged
record types, and @code{tagged_type} controls only tagged record types.
@item
@code{interface_type} controls interface type declarations.
@item
@code{relay_function} controls functions whose statement part includes
only a single @code{@b{return}} statement whose expression is another
function call; similarly, @code{relay_procedure} controls procedures
whose statement part includes only a call to another procedure, and
@code{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).
@item
@code{renaming} controls all renaming declarations, while
@code{renaming_as_body} controls only those that are renamings as
bodies of subprograms, @code{renaming_as_declaration} controls only
those that are regular renamings of subprograms (i.e. not as bodies),
@code{operator_renaming} controls only those that are renamings of an
operator, @code{not_operator_renaming} controls only those that are
@emph{not} renamings of an operator, @code{function_call_renaming}
controls renaming of the result of a function call, and
@code{library_unit_renaming} controls renaming of library units.
@code{non_identical_renaming} controls only renamings where the new
name and the old name are not the same, and
@code{non_identical_operator_renaming} does the same, but only for
renamings of operators. @code{synonym_renaming} controls renamings declared in
the same declarative part as the entity being renamed (these serve no purpose
as far as visibility is concerned, and are thus pure synonyms).
@item
@code{self_calling_function} controls functions whose body contains
only a single (simple) @code{@b{return}} statement, and the return
expression is a (recursive) call to the same function. Similarly,
@code{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.
@item
@code{subtype} controls all explicit subtype declarations (i.e. not
all anonymous subtypes that appear at various places in the
language), while @code{unconstrained_subtype} controls only the
subtype declarations that do not include a constraint.
@item
@code{task} controls task type declarations as well as single tasks
declarations while @code{single_task} and @code{task_type} control
only single task declarations or task type declarations respectively
(and similarly for @code{protected}). @code{non_ravenscar_task} controls
all task type and task object declarations from a unit to which no
@code{pragma Profile (Ravenscar)} applies.
@item
@code{type} controls all type (but not subtype) declarations.
@item
@code{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.
@item
@code{variable} controls all variable declarations.
@code{scalar_variable} controls the declarations of variables of a
scalar type (integer, enumeration, float, fixed).
@code{ordinary_record_variable} controls declarations of variables of
an untagged record type.  @code{tagged_variable} controls declarations
of variables of a tagged type (including class-wide ones), while
@code{class_wide_variable} controls only the declarations of variables
of a class-wide type.  @code{task_variable} and
@code{protected_variable} control task and protected objects
(respectively), whether given with a named or anonymous type.
@item
@code{variant_part} controls variant parts in record defintions.
@end itemize

Ex:
@example
-- 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);
@end example

@subsection Variable
The rule provides a variable that allows 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.

@need 800
@multitable @columnfractions .25 .10 .10 .55
@item
@b{Variable} @tab @b{Values} @tab @b{Default} @tab @b{Effect}
@item
Limited_Initialization
@tab off@*on
@tab off
@tab
@table @asis
@item off
uninitialized variables of a limited type are never reported.
@item 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.
@end table
@end multitable

@subsection Tips
Certain keywords are @i{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:
@example
check declarations (record_type, tagged_type);
@end example
tagged types will be reported both as ``record_type'' and
``tagged_type''.

There is no subrule for checking functions whose result type is from
an anonymous access type; these are controlled by the rule
@code{return_type (anonymous_access)}. @xref{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 @i{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
(@code{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 @i{visible} types are controlled normally.

@subsection Limitation
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''.  @xref{Uncheckable}.

@node Default_Parameter, Dependencies, Declarations, Rules reference
@section Default_Parameter
This rule checks usage (or non-usage) of defaulted parameters.
@subsection Syntax
@example
<control_kind> default_parameter (<place>, <formal>, <usage>);
<place>  ::= <entity> | calls | instantiations
<formal> ::= <formal name> | all
<usage>  ::= used | positional | not_used
@end example

@subsection Action
The rule controls subprogram calls or generic instantiations that use
the default value for the indicated parameter, or conversely don't use
it, either in positional notation or in any notation. If a subprogram
is called, or a generic instantiated, whose name matches <entity>, and
it has a formal whose name is <formal name>, then:
@itemize @bullet
@item
If the string @code{used} (case irrelevant) is given as the third
parameter, the rule reports when there is no corresponding actual
parameter (i.e. the default value is used for the parameter).
@item
If the string @code{positional} (case irrelevant) is given as the
third parameter, the rule reports when there is an explicit
corresponding actual parameter (i.e. the default is not used for the
parameter), and the actual uses positional (not named) notation.
@item
If the string @code{not_used} (case irrelevant) is given as the third
parameter, the rule reports when there is an explicit corresponding
actual parameter (i.e. the default is not used for the parameter),
independently of whether it uses positional or named notation.
@end itemize

As usual, the whole syntax for entities is allowed for
<entity>. @xref{Specifying an Ada entity name}. On the other hand,
<formal> is the simple name of the formal parameter.

Alternatively, the <entity> can be specified as @code{calls}, to
control all calls or @code{instantiations}, to control all
instantiations. The <formal name> can be replaced by @code{all}, in
which case all formals are controlled.

Ex:
@example
check default_parameter (P, X, used);
check default_parameter (P, Y, not used);
search default_parameter (calls, all, positional);
@end example

@subsection Tip
If the <entity> 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.

@node Dependencies, Derivations, Default_Parameter, Rules reference
@section Dependencies
This rule controls dependencies of units (i.e. @code{@b{with}}
clauses, parents, child units...), either according to a set of
allowed/forbidden units, or by count.

@subsection Syntax
@example
<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>
@end example

@subsection Action
The kind of action depends on the specified subrule.

The ``others'' subrule controls semantic dependencies to units other
than those indicated. This subrule can be specified only once, and at
least one unit must be given.

The ``with'' subrule controls with clauses that reference the
indicated units. At least one unit must be given.

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.

``public_child'' and ``private_child'' control units that depend on
their own public (respectively private) child units. Since these
subrules have no parameters, they can be given only once.

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.
@itemize @bullet
@item
``raw'' controls the number of units textually given in
@code{@b{with}} clauses. Redundant @code{@b{with}} clauses are
counted, and a child unit counts for one.
@item
``direct'' controls the number of different units that this unit
really depends on: if a unit is mentionned in several @code{@b{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.
@item
``parent'' counts the number of parents of the current unit. A root
unit has no parent, a child of a root unit has one parent, etc.
@end itemize

Ex:
@example
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);
@end example

@subsection Tips
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:
@example
 -- 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);
@end example

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 @code{@b{with}}
clauses. @xref{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 @code{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 rule file (or copy the content) if you want to disallow these
units. @xref{Rules files provided with AdaControl}.

@node Derivations, Directly_Accessed_Globals, Dependencies, Rules reference
@section Derivations
This rule controls various properties of the declaration of derived types.

@subsection Syntax
@example
<control_kind> derivations (from, <entity>|<category>
                               @{, <entity>|<category>@})
<control_kind> derivations (max_parents, <value>)
<category> ::= ()      | access    | array | delta  | digits | mod  |
               private | protected | range | record | tagged | task
@end example

@subsection Action
The ``from'' subrule controls derivations according to the parent
type and progenitors.

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 @i{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 a type
(or subtype) declared inside the given unit.  As usual, the whole
syntax for entities is allowed for <entity>. @xref{Specifying an Ada
entity name}.

If <category> is given, it controls derived types whose parent type
belongs to the corresponding category. The meaning of <category> is:
@itemize @bullet
@item
``()'': The parent is of an enumerated type.
@item
``access'':  The parent is of an access type.
@item
``array'': The parent is of an array type.
@item
``delta'': The parent is of a fixed point type (it is not currently
possible to distinguish ordinary fixed point types from decimal fixed
point types).
@item
``digits'': The parent is of a floating point type.
@item
``mod'': The parent is of a modular type.
@item
``private'': The parent is of a private type (including private
extensions).
@item
``protected'': The parent is of a protected type.
@item
``range'': The parent is of a signed integer type.
@item
``record'': The parent is of an (untagged) record type.
@item
``tagged'': The parent is of a tagged type (including type
extensions).
@item
``task'': The parent is of a task type.
@end itemize

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:
@enumerate
@item
Specific subtype
@item
Specific type
@item
Type or subtype from a compilation unit
@end enumerate
If a category also applies to the parent type, a separate message is
always issued.

Ex:
@example
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);
-- Types derived from an integer type
@end example

The ``max_parents'' subrule controls the maximum number of parents in
a derivation. The parents are the direct ancestor in a derived type
definition, plus all of the progenitors (the interfaces that are
implemented by the type). <n> is the maximum number of @i{allowed}
parents, i.e. the rule is triggered if the number of parents is
strictly greater than <n>.

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.

@example
check derivations (max_parents, 5);   -- error if more than 5 parents
search derivations (max_parents, 3);  -- warning if more than 3 parents
@end example

@node Directly_Accessed_Globals, Duplicate_Initialization_Calls, Derivations, Rules reference
@section Directly_Accessed_Globals
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.
@subsection Syntax
@example
<control_kind> directly_accessed_globals [(<kind> @{,<kind>@})];
<kind> ::= plain | accept | protected
@end example
@subsection Action
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 @code{@b{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 @code{@b{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.
@itemize @bullet
@item
Subprograms used to read/write the variables must be declared at the
same level as the variable itself (i.e. not nested), and must not be
generic.
@item
Protected subprograms used to read/write the variables must both be
part of the same single protected 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 protected @i{type}, since if there are
several protected objects of the same type, mutual exclusion would not
be enforced.
@item
@code{@b{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 @i{type}, since if there are several
task objects of the same type, mutual exclusion would not be enforced.
@end itemize
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:
@example
check directly_accessed_globals
@end example

@subsection Tips
Note that this rule controls global variables from package @i{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:
@example
check usage (variable, from_spec);
@end example
@pxref{Usage} for details.

@subsection Limitations
AdaControl cannot check entities accessed through dynamic names
(dynamic renaming, access on aliased variables). Use of such
constructs is detected by the rule ``uncheckable''.
@xref{Uncheckable}.

Due to a weakness in the ASIS standard, it is not possible to know the
mode (@b{in}, @b{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''.  @xref{Uncheckable}.

@node Duplicate_Initialization_Calls, Entities, Directly_Accessed_Globals, Rules reference
@section Duplicate_Initialization_Calls
This rule checks that some procedures (notably initialization
procedures) are not called several times in identical conditions.
@subsection Syntax
@example
<control_kind> duplicate_initialization_calls (<entity> @{, <entity>@});
@end example
@subsection Action
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>. @xref{Specifying an Ada entity name}.

More precisely, the initialization procedures must follow one of these
patterns:
@itemize @bullet
@item
The procedure only has @code{@b{in}} parameters. All actual parameters
used in calls are static, and not two calls have the same values for
all parameters.
@item
The procedure has exactly one @code{@b{out}} parameter (and no
@code{@b{in out}} parameter). Not two calls refer the same actual variable
for the @code{@b{out}} parameter.
@end itemize

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:
@example
check duplicate_initialization_calls (pack.init_proc);
@end example

@subsection Limitation
If a variable passed as an @code{@b{out}} parameter is not statically
determinable, it is not controlled by the rule. Such a case is
detected by the rule ``uncheckable''.  @xref{Uncheckable}.

@node Entities, Entity_Inside_Exception, Duplicate_Initialization_Calls, Rules reference
@section Entities
This rule is used to control usage of Ada entities, i.e. any declared
element (type, variables, packages, etc).
@subsection Syntax
@example
<control_kind> entities (@{[not] <location>@} [instance] <entity>
                      @{, @{[not] <location>@} [instance] <entity>@});
<location> ::= block   | library | local      | nested    | own |
               private | public  | in_generic | task_body

@end example

@subsection Action
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>. @xref{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.
@itemize @bullet
@item
@code{block}: the entity appears in a block statement.
@item
@code{library}: the entity appears at library level.
@item
@code{local}: the entity appears in a local scope (i.e. not in
(generic) packages, possibly nested)
@item
@code{own}: the entity appers in a (generic) package body.
@item
@code{public}: the entity appears in the visible part of a
(generic) package.
@item
@code{private}: the entity appears directly in a private
part.
@item
@code{in_generic}: the entity appears directly or indirectly in a generic
specification or body.
@item
@code{task_body}: the entity appears directly in a task body.
@end itemize

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 @code{instance} is given.

Note that this rules reports on the use of the @i{entity}, not the
@i{name}: if an entity has been renamed, it will be found under its
various names.

Ex:
@example
search entities (Debug.Trace);
check  entities (Ada.Text_IO.Float_IO.Put);
check  entities (instance Ada.Unchecked_Conversion);
@end example
The second line will report on any use of a @code{Put} from any
instantiation of @code{Float_IO}. The third one will report only
on uses of instances of @code{Ada.Unchecked_Conversion}.

@subsection Tips
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 ``@code{all <Attribute>}'' syntax. For example,
the following will report on any usage of @code{'Unchecked_Access}:
@example
check entities (all 'Unchecked_Access);
@end example

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 @code{@b{with}}
clauses (which is of course sufficient).

In certain contexts, it can be useful to forbid certain entities, like
those from @code{Standard}, @code{System}, or entities defined in
special needs annexes packages. The @code{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 rule file (or copy the
content) if you want to disallow these elements. @xref{Rules files
provided with AdaControl}.

@subsection Limitation
GNAT defines @code{Unchecked_Conversion} and
@code{Unchecked_Deallocation} as separate entities, rather than
renamings of @code{Ada.Unchecked_Conversion} and
@code{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.

@node Entity_Inside_Exception, Exception_Propagation, Entities, Rules reference
@section Entity_Inside_Exception
This rule controls entities that appear within exception handlers.
@subsection Syntax
@example
<control_kind> entity_inside_exception (<spec> @{, <spec>@});
<spec> ::= [not] <entity> | calls | entry_calls
@end example

@subsection Action
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:
@example
-- 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@});
@end example

@node Exception_Propagation, Expressions, Entity_Inside_Exception, Rules reference
@section Exception_Propagation
This rule controls that certain program units are guaranteed to never
propagate exceptions, or that local exceptions cannot propagate out of
their scope.
@subsection Syntax
@example
<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);
@end example

@subsection Action
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 @code{@b{others}}; this handler must
not reraise the exception; and no handler is allowed to raise
explicitely the exception. The subrule controls explicit
@code{@b{raise}} statements and calls to @code{Raise_Exception} and
@code{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 @emph{not} propagating if:
@enumerate
@item
it has an exception handler with a ``@code{@b{when others}}'' choice
@item
no exception handler contains a @code{@b{raise}} statement, nor any
call to @code{Ada.Exception.Raise_Exception} or
@code{Ada.Exception.Reraise_Occurrence}.
@item
no declaration from its own declarative part propagates exceptions.
@end enumerate

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:
@itemize @bullet
@item
0: expressions in declarative parts are not considered as propagating
(anything allowed, this is the default value for ``interface'',
``parameter'' and ``task''. Not allowed for ``declaration'').
@item
1: all function calls (including operators) in declarations are
considered as potentially propagating exceptions, except those
appearing in named number declarations or scalar types declarations,
since those are required by the language to be static.
@item
2: same as 1, plus every use of variables in expressions is considered
as potentially propagating.
@item
3: same as 2, plus any declaration of objects (constants or variables)
is considered potentially propagating (not very useful for
``declaration'').
@end itemize

These subrules serve several purposes:
@itemize @bullet
@item
The ``interface'' subrule  analyzes all subprograms to which an
@code{Interface} or @code{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.
@item
The ``parameter'' subrule accepts one or more fully qualified formal
parameter names (i.e. in the form of the parameter name prefixed by
the full name of its subprogram, see @ref{Specifying an Ada entity
name}). The subrule reports any subprogram that can propagate
exceptions and is used as the prefix of a @code{'Access} or
@code{'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.
@item
The ``task'' subrule reports any task that can propagate exceptions.

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.
@item
The ``declaration'' subrule reports
any declaration that can propagate exceptions, irrespectively of where
it appears.  In this case, the specification of <level> is required
and cannot be 0.

It is sometimes desirable to make sure that no declaration raises an
exception, ever.
@end itemize

Ex:
@example
-- 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);
@end example

The first example will report on any subprogram to which a
@code{@b{pragma} Interface (C,...)} applies that can propagate
exceptions.

If @code{Proc} is a procedure that can propagate exceptions, the
second example will report on every call like:
@example
Pack.Register (CB => Proc'Access);
@end example

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.

@subsection Tips
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:
@example
@b{package} Pack @b{is}
   @b{type} Acc_Proc @b{is} @b{access} @b{procedure};
   @b{type} Acc_Reg @b{is} @b{access} @b{procedure} (CB : Acc_Proc);
   ...
   Ptr : Acc_Reg := ...;
@end example

You can give a rule such as:
@example
check exception_propagation (parameter, Pack.Acc_Reg.CB);
@end example
All procedures registered by a call to @code{Pack.Ptr.@b{all}} will be considered.

The declaration of a @b{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:
@example
@b{for} I @b{in} Positive @b{range} 1 .. X @b{loop} ...
@end example
although formally the @i{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 @b{for} loop
@i{statement}.

@subsection Limitations
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:
@example
Pack.Register (CB => Pointer.@b{all}'Access);
@end example

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''. @xref{Uncheckable}.

@node Expressions, Generic_Aliasing, Exception_Propagation, Rules reference
@section Expressions
This rule controls usage of various kinds of expressions.
@subsection Syntax
@example
<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                |
   downward_conversion        | dispatching_function_calls       |
   dynamic_function_calls     | extendable_aggregate             |
   extension_aggregate        | explicit_dereference             |
   fixed_multiplying_op       | for_all                          |
   for_some                   | function_calls                   |
   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_partial_others      | record_aggregate                 |
   record_others              | redispatching_function_calls     |
   slice                      | static_membership                |
   type_conversion            | upward_conversion                |
   unconverted_multiplying_op | underived_conversion             |
   universal_range            | unqualified_aggregate            |
   xor                        | xor_array                        |
   xor_binary                 | xor_boolean
<category> ::=
   <>     | ()     | range  | mod | delta   | digits | array    |
   record | tagged | access | new | private | task   | protected
@end example
@subsection Action
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:
@itemize @bullet
@item
``<>'': Any type
@item
``()'': Enumerated types
@item
``range'': Signed integer types
@item
``mod'': Modular types
@item
``delta'': Fixed point types (no possibility to differentiate ordinary
and decimal fixed point types yet).
@item
``digits'': Floating point types
@item
``array'': Array types
@item
``record'': (untagged) record types
@item
``tagged'': Tagged types (including type extensions)
@item
``access'': Access types
@item
``new'': Derived types
@item
``private'': Private types
@item
``task'': Task types
@item
``protected'': Protected types
@end itemize

The subrule define the kind of expression being controlled:
@itemize @bullet
@item
@code{not}, @code{and}, @code{or}, @code{xor}, @code{and_then},
@code{or_else}, @code{in}, and @code{not_in} control usage of the
corresponding logical operator (or short circuit form, or membership
test).
@item
@code{and_array}, @code{or_array}, and @code{xor_array} do the same,
but only for operators whose result type is an array type.
@item
@code{and_binary}, @code{or_binary}, and @code{xor_binary} do the same,
but only for operators whose result type is a modular type.
@item
@code{and_boolean}, @code{or_boolean}, and @code{xor_boolean} do the same,
but only for operators whose result type is @code{Standard.Boolean}.
@item
@code{array_aggregate} and @code{record_aggregate} control array and
record aggregates, respectively, while @code{unqualified_aggregate}
controls aggregates (both arrays and records) that do not appear
directly within a qualified expression. @code{extension_aggregate}
controls extension aggregates, while @code{extendable_aggregate}
controls aggregates that are @i{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).
@item
@code{array_others} and @code{record_others} control the occurrence of
a @code{@b{others} =>} association in array and record
aggregates, respectively.
@item
@code{array_partial_others} and @code{record_partial_others} do the
same, but only if there are other associations in addition to the
@code{@b{others} =>} in the aggregate. @code{array_named_others} and
@code{array_positional_others} do the same, but only for named
(respectively positional) array aggregates.
@item
@code{array_range} controls array aggregates that include a range
(i.e. an association like @code{A .. B =>}).
@code{array_non_static_range} does the same, but only if (at least)
one of the bounds is not static.
@item
@code{case} controls @b{case} expressions (introduced in Ada 2012).
@item
@code{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.
@item
@code{explicit_dereference} controls explicit dereferences of access
values (i.e. with an explicit @code{.@b{all}}).
@item
@code{fixed_multiplying_op} controls calls to predefined fixed-point
multiplication and division (regular fixed-point or decimal-fixed
point). @code{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.
@item
@code{for_all} and @code{for_some} control the two forms of
quantifiers introduced by Ada 2012.
@item
@code{if} controls all @b{if} expressions (introduced in Ada 2012),
while @code{if_elsif} only controls those that have an @b{elsif} part,
and @code{if_no_else} only controls those that have no @b{else} part.
@item
@code{implicit_dereference} controls implicit dereferences of access
values (i.e. when the @code{.@b{all}} is omitted).
@item
@code{inconsistent_attribute_dimension} controls when no dimension is
explicitely given for a @code{'First}, @code{'Last}, @code{'Range} or
@code{'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.
@item
@code{function_call} controls all calls to functions, incuding user
defined operators, but not predefined operators (including the latter
would generate too much noise). @code{dispatching_function_call} does
the same, but only for dispatching calls while
@code{redispatching_function_call} does the same, but only for
dispatching calls that are (directly or indirectly) inside a primitive
operation of a tagged type. @code{dynamic_function_call} does the
same, but only for calls through
pointers. @code{inherited_function_call} controls calls to functions
that have been inherited by a derived type and not redefined.

For all @code{*_function_call} subrules, if a category is specified,
only calls whose result type belongs to the category are controlled.
Derived types are followed, i.e. the ``real'' category from the
original type is used for the matching; as a consequence, the ``new''
category cannot be specified for this subrule. In addition, the amount
of information displayed can be selected with the rule variable
``called_info'' (see below).

@item
@code{mixed_operators} controls expressions that involve several
different operators, without parentheses. In a sense, it extends the
language rule that forbids mixing @code{@b{and}} and @code{@b{or}} in
logical expressions to all other operators. Note that for the purpose
of this subrule, membership tests (@code{@b{in}}, @code{@b{not in}})
and short circuit forms (@code{@b{and then}}, @code{@b{or else}}) are
considered operators.
@item
@code{prefixed_operator} controls calls to operators that use prefixed
notation (i.e. @code{"+"(A, B)}). If a category is specified, only
calls whose result type belongs to the category are controlled.

Derived types are followed, i.e. the ``real'' category from the
original type is used for the matching; as a consequence, the ``new''
category cannot be specified for this subrule.
@item
@code{real_equality} controls usage of predefined exact equality or
inequality (``='' or ``/='') between real (floating point or fixed
point) values.
@item
@code{slice} controls usage of array slices.
@item
@code{static_membership} controls membership tests (@code{@b{in}} and
@code{@b{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 @code{@b{not in}}).
@item
@code{type_conversion} controls all (sub)type conversions, while
@code{underived_conversion} controls conversions between types that do
@i{not} belong to the same derivation
family. @code{downward_conversion} and @code{upward_conversion}
control conversions between types that belong to the same family,
converting away from the root or toward the root,
respectively. @code{parameter_view_conversion} controls conversions
that appear as @code{@b{out}} or @code{@b{in out}} actual parameters.

One or two categories can be specified; if only 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
belong to the second category are controlled.

Derived types are followed, i.e. the ``real'' category from the
original type is used for the matching; as a consequence, the ``new''
category cannot be specified for this subrule.
@item
@code{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.
@end itemize

Ex:
@example
search expressions (real_equality, slice);
check  expressions (mixed_operators);

-- Find logical operators that could be replaced by short-circuits forms:
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);
@end example

@subsection Variable
The rule provides a variable that allows to specify the amount of information
displayed with the various *_function_calls subrules.

@need 800
@multitable @columnfractions .12 .18 .10 .60
@item
@b{Variable} @tab @b{Values} @tab @b{Default} @tab @b{Effect}
@item
Called_Info
@tab none@*compact@*detailed@*root_detailed
@tab none
@tab

@table @asis
@item``none''
No extra information.
@item ``compact''
display the name of the called function.
@item ``detailed''
display the name of the called function with overloading
information.
@item ``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.
@end table
@end multitable

@subsection Tips
The @code{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 @code{entities} rule. @xref{Entities}.

This rule does not check the use of allocators (@code{@b{new}}), use
the rule @code{Allocators} instead. @xref{Allocators}.

``inherited_function_call'' controls only @i{function} calls. For
procedure calls, see rule @ref{Statements}.

Specifying @code{array_partial_others} is the same as specifying both
@code{array_named_others} and @code{array_positional_others}. It is
retained for compatibility, and also for symetry with
@code{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.

@subsection Limitations
``static_membership'' does not control the complex membership tests
with several choices that are possible with Ada 2012.

@node Generic_Aliasing, Global_References, Expressions, Rules reference
@section Generic_Aliasing
This rule controls instantiations where the same actual is given to
more than one formal.
@subsection Syntax
@example
<control_kind> generic_aliasing [(<subrule> @{, <subrule>@})];
<subrule>   ::= [<condition>] <entity>
<condition> ::= unlikely | possible | certain
<entity>    ::= all | variable | type | subprogram | package
@end example

@subsection Action
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 <entity> 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 @ref{Parameter_Aliasing} for a
more detailed description of these modifiers). Possible values are
(case irrelevant):
@itemize
@item
Certain (default): Only cases where aliasing is statically certain are
output.
@item
Possible: In addition, cases where aliasing may occur depending on the
value of an indexed component are output. This can be specified only
for variables.
@item
Unlikely: In addition, cases where aliasing may occur due to access
variables designating the same element are output. This can be
specified only for variables and subprograms.
@end itemize

Without any parameter, the rule is the same as ``certain all''. The
rule can be specified only once for each combination of <condition>
and <entity>.

Ex:
@example
check  generic_aliasing (certain  variable);
search generic_aliasing (possible variable, type, subprogram, package);
@end example

@subsection Limitations
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 @code{"+"} on Integer and
@code{"+"} on Float. This possibility of  false positives is detected
by the rule ``uncheckable''. @xref{Uncheckable}.

@node   Global_References, Header_Comments, Generic_Aliasing, Rules reference
@section Global_References
This rule controls accesses to global elements that may be subject to
race conditions, or otherwise shared.

@subsection Syntax
@example
<control_kind> global_references (<subrule> @{, <root>@});
<subrule> ::= all | read | written | multiple | multiple_non_atomic
<root>    ::=  <entity> | function | procedure | task | protected
@end example

@subsection Action
This rule controls access to global variables from several entities
(the roots). The @code{<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>.
@xref{Specifying an Ada entity name}. The special keywords
@code{function}, @code{procedure}, @code{task}, and @code{protected}
are used to refer to all functions, procedures, tasks, and protected
entities, respectively.

The <subrule> determines the kind of references that are
controlled. If it is @code{all}, all references to global elements
from the indicated entities are reported. If <subrule> is @code{read}
or @code{written}, only read (respectively write) accesses are
reported. If <subrule> is @code{multiple}, only global elements that
are accessed by more than one of the indicated entities (i.e. shared
elements) are reported. Note however that if a reference is found from
a task type or protected type, it is always reported, since there are
potentially several objects of the same type. If <subrule> is
@code{multiple_non_atomic}, references reported are the same as with
@code{multiple}, except that global variables that are @code{atomic}
or @code{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:
@example
-- 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);
@end example

This rule can be given several times, and conflicts (with
@code{multiple}) are reported on a per-rule basis, i.e. given:
@example
check global_references (multiple, P1, P2);
check global_references (multiple, P1, P3);
@end example

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.

@subsection Tips
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:

@example
@b{procedure} Outer @b{is}
   Inner_V : Integer;

   @b{procedure} Inner_P @b{is}
   @b{begin}
      Inner_V := 1;
   @b{end} Inner_P;
@b{begin}
   Inner_P;
@b{end} Outer;
@end example

The rule
@example
check global_references (all, outer);
@end example
will not report any global reference, while the rule
@example
check global_references (all, outer.inner_p);
@end example
will report a reference to @code{Inner_V}. This is as it should be,
since there is no race condition if several tasks call @code{Outer},
while there is a risk if several tasks (declared inside @code{Outer})
call @code{Inner_P}.

Specifying:
@example
check global_references (all, function);
@end example
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.

@subsection Limitations
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''. @xref{Uncheckable}.

@node Header_Comments, Improper_Initialization, Global_References, Rules reference
@section Header_Comments
This rule controls that every compilation unit starts with a
standardized comment.
@subsection Syntax
@example
<control_kind> header_comments (minimum, <comment lines>);
<control_kind> header_comments (model, "<file name>");
@end example
@subsection Action
If the keyword ``minimum'' is given as first parameter, this rule
controls that every compilation unit starts with at least the number
of comment lines indicated by the second parameter. If several forms
of headers are possible, checking that the headers follow the
project's standard requires manual inspection, but this rule is useful
to control that unit headers have not been inadvertantly forgotten.

If the keyword ``model'' is given as first parameter, the second
parameter is a string, interpreted as a file name. If the file name is
not an absolute path, it is interpreted as relative to the directory
of the file that contains the rule, or to the current directory if the
rule is given on the command line.  Each line of the indicated file is
a regular expression, and the rule controls that the corresponding
line of the source file matches the expression. @xref{Syntax of
regular expressions}. In addition, it is possible to specify a repetition
for a line. If the first character of a line is a @code{'@{'}, the line
must have the following syntax:
@example
@{<min>,[<max>]@}
@end example
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 @code{'*'}
it means that the next line is a pattern that can occur any number of
times (same as @code{@{0,@}}). If the first character is a
@code{'+'}, it means that the next line is a pattern that must occur
at least once (same as @code{@{1,@}}). If the first character is a
@code{'?'}, it means that the next line is an optional pattern (same
as @code{@{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 @code{'@}'}) 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:
@example
check header_comments (minimum, 10);
search header_comments (model, "header.pat");
count header_comments (minimum, 20);
@end example
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 @code{header.pat}. A count of units that start
with less than 20 comment lines is reported.

Example of a pattern file:
@example
@{1,3@} 1 to 3 occurrences of next line
^--$
^-- Author: .+$
^-- Date: \d@{2@}/\d@{2@}/\\d@{4@}$
@end example

@subsection Tips
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 @code{source} contains a
script file for sed named @code{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:
@itemize
@item
A comment with ``HISTORY''
@item
Any number of comment lines
@item
A comment with ``AUTHORS''
@item
Any number of comment lines
@end itemize
the following pattern will work as expected:
@example
^-- HISTORY$
*
^--
^-- AUTHORS
*
^--
@end example

@subsection Limitation
Since the ``model'' subrule analyzes the content of comments, there is
a conflict with the disabling mechanism of AdaControl that uses
special comments. @xref{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:
@example
?
--##
@end example
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.

@node  Improper_Initialization, Instantiations, Header_Comments, Rules reference
@section Improper_Initialization
This rule enforces a coding pattern that ensures that variables and
@code{@b{out}} parameters are properly initialized befor use.
@subsection Syntax
@example
<control_kind> improper_initialization [(<subrule> @{,<subrule>@})]
<subrule> ::= @{<extra>@} <target>
<extra>   ::= access | limited | package | return
<target>  ::= out_parameter | variable | initialized_variable
@end example
@subsection Action
This rule controls variables and/or @code{@b{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 @code{@b{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:
@itemize @bullet
@item
@code{null} statements;
@item
assignment statements;
@item
procedure calls;
@item
return statements;
@item
raise statements;
@item
extended return statements, unless they contain a nested non-trivial
statement.
@item
@code{@b{if}} and @code{@b{case}} statements, unless they contain a
nested non-trivial statement.
@end itemize
The <target> parameters determines what is to be checked:
@itemize @bullet
@item
@code{out_parameter} controls that @code{@b{out}} parameters are
safely initialized before the first non-trivial statement, and before
every (trivial) @code{@b{return}} statement. Note that  @code{@b{out}}
parameters are @i{not} checked before  @code{@b{raise}} statements,
since the language does not guarantee that  @code{@b{out}} parameters
are transmitted back in the case of exceptions.
@item
@code{variable} controls that local variables are safely initialized
before the first non-trivial statement. If the <extra> modifier
@code{return} is specified, only return objects of extended return
statements are controlled.
@item
@code{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 @code{return} is specified, only return
objects of extended return statements  are controlled.
@end itemize
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
@code{@b{out}} (but not @code{@b{in out}}) parameter of a procedure
call. Variables assigned in @code{@b{if}} or @code{@b{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 @i{not} controlled, unless the corresponding
<extra> modifier is given:
@itemize
@item
Variables declared immediately within a (generic) package
specification or body, since in general, package state variables are
initialized through calls to dedicated procedures. Use the ``package''
modifier to control also package variables.
@item
Variables of an access types, or arrays whose components are of an
access type, since these are always initialized by the compiler. Use
the ``access'' modifier to control also variables of an access type.
@item
Variables of a limited type, since global assignment is not available
for them. Use the ``limited'' modifier to control also variables of a
limited type.
@end itemize

This rule can be given only once for each value of <target>. Without
parameters, it is equivalent to giving all, without any <extra>.

Ex:
@example
check improper_initialization (out_parameter);
check improper_initialization (access limited variable);
search improper_initialization (initialized_variable);
@end example

@subsection Tips
@code{variable} and @code{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 @code{return}
modifier.

@subsection Limitations
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
@code{'Read} and @code{'Input} have an @code{@b{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''. @xref{Uncheckable}. It is then easy to disable the
rule for this variable. @xref{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
@code{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...

@node Instantiations, Insufficient_Parameters, Improper_Initialization, Rules reference
@section Instantiations
This rule controls all instantiations of a generic, or only
instantiations that are made with specific values of the
parameters. Control can be restricted to instantiations in specified
places.

@subsection Syntax
@example
<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
<category>     ::= ()      | access    | array | delta  | digits | mod |
                   private | protected | range | record | tagged | task
@end example

@subsection Action
The rule controls instantiations of the specified <entity>. As usual,
the whole syntax for entities is allowed for <entity>.
@xref{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''.
@itemize @bullet
@item
@code{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.
@item
@code{block}: only instantiations appearing in block statements are
controlled.
@item
@code{library}: only library level instantiations are controlled.
@item
@code{local}: only local instantiations are controlled (i.e. only
instantiations appearing in (generic) packages, possibly nested, are
allowed).
@item
@code{own}: only instantiations that are local to a (generic) package
body are controlled.
@item
@code{public}: only declarations appearing in the visible part of
(generic) packages are controlled.
@item
@code{private}: only instantiations appearing directly in a private
part are controlled.
@item
@code{in_generic}: only instantiations appearing directly or indirectly in a generic
specification or body are controlled.
@item
@code{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 @i{specifications}, since instantiations are
not allowed there.
@end itemize

An instantiation matches if it appears at a specified location (if
any) and either:
@enumerate
@item
No <formal_spec> is given in the rule
@item
The actual parameters of the instantiation match the corresponding
<formal_spec>, in order (there can be more actual parameters in the
instantiation than specified in the rule). An actual parameter matches
an <entity> at a given place if it is the same entity, or if the
<entity> designates a (sub)type and  the actual is a subtype of this
type. As usual, the whole syntax for entities is allowed for
<entity>. @xref{Specifying an Ada entity name}.  In addition, it
matches if the actual is a type name that belongs to the indicated
category:
@itemize @bullet
@item
``()'': The parameter is of an enumerated type.
@item
``access'':  The parameter is of an access type.
@item
``array'': The parameter is of an array type.
@item
``delta'': The parameter is of a fixed point type (it is not currently
possible to distinguish ordinary fixed point types from decimal fixed
point types).
@item
``digits'': The parameter is of a floating point type.
@item
``mod'': The parameter is of a modular type.
@item
``private'': The parameter is of a private type (including private
extensions).
@item
``protected'': The parameter is of a protected type.
@item
``range'': The parameter is of a signed integer type.
@item
``record'': The parameter is of an (untagged) record type.
@item
``tagged'': The parameter is of a tagged type (including type
extensions).
@item
``task'': The parameter is of a task type.
@end itemize

In addition, two special signs can be given instead of an <entity> (or
<category>): a box (@code{<>}) matches any actual parameter
(i.e. it stands for any value), and an equal sign (@code{=}) 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).
@end enumerate

Formal @code{@b{in}} parameters cannot be matched, since the actual
can be any expression and it is not clear how to specify it in the
rule; therefore, the rule should normally specify a box (@code{<>}) at
the place of such parameters.

Ex:
@example
-- 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, =, =);
@end example

@subsection Tips
The various forms of <formal_spec> make the rule quite powerful. For
example:
@example
-- Not two instantiations of Gen with the same first parameter:
check instantations (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);
@end example

Note that a generic actual wich is a subtype matches all types (and subtypes)
above it. Therefore,
@example
check instantiations (ada.unchecked_deallocation (standard.natural));
@end example
will find only instantiations that use @code{Natural}, while:
@example
check instantiations (ada.unchecked_deallocation (standard.integer));
@end example
will find instantiations that use either @code{Integer},
@code{Positive}, or @code{Natural}.

If an equal sign (@code{=}) is provided for a formal @code{@b{in}}
parameter, it is @i{not} part of the comparison of existing
instantiations (it behaves like a  box (@code{<>})), i.e.  given:
@example
generic
   type T1 is private;
   Val : String := "";
package Gen;

package body Gen is ...  end Gen;

package Inst1 is new Gen (Float, "Some Message");
package Inst2 is new Gen (Float, "Some Other Message");
@end example
and the rule:
@example
check instantiations (Gen, =, =);
@end example
Adacontrol will issue a message for Inst2 that it has already been
instantiated with the same parameters, although the second
(@code{@b{in}}) parameter is different.

@subsection Limitation
GNAT defines @code{Unchecked_Conversion} and
@code{Unchecked_Deallocation} as separate entities, rather than
renamings of @code{Ada.Unchecked_Conversion} and
@code{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.

@node  Insufficient_Parameters, Local_Access, Instantiations, Rules reference
@section Insufficient_Parameters
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.

@subsection Syntax
@example
<control_kind> insufficient_parameters (<max_allowed> @{, <entity>@});
@end example
@subsection Action
<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>. @xref{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
(@code{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:
@example
search Insufficient_Parameters (1, Standard.Boolean);
check  Insufficient_Parameters (2, Standard.Boolean);
@end example

@subsection Tips
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
@code{positional_associations}. @xref{Positional_Associations}.

Note also that this rules applies only to calls, while
@code{positional_associations} applies to all forms of associations.

@node Local_Access, Local_Hiding, Insufficient_Parameters, Rules reference
@section Local_Access
This rule controls the taking of access values (through the  @code{'Access},
 @code{'Unchecked_Access}, or the  GNAT specific  @code{'Unrestricted_Access}
attributes) of local (i.e. non global) entities.

@subsection Syntax
@example
<control_kind> local_access [(<subrule> @{,<subrule>@})];
<subrule>   ::= constant | variable | procedure | function |
                protected_procedure | protected_function
@end example

@subsection Action
Without parameters, the rule controls all entities given as prefixes
of  @code{'Access}, @code{'Unchecked_Access}, or
@code{'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:
@example
Dangerous_Objects: check local_access (Constant, Variable);
@end example

@subsection Tips
In Ada 95, accessibility rules make sure that taking the
@code{'Access} of an entity cannot create dangling pointers, but this
check can be circumvented by using @code{'Unchecked_Access} (but not
on subprograms), or in GNAT, by using
@code{'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.

@node Local_Hiding, Max_Blank_Lines, Local_Access, Rules reference
@section Local_Hiding
This rule controls declarations that hide an outer declaration with
the same name.

@subsection Syntax
@example
<control_kind> local_hiding [(<subrule> @{,"<allowed pattern>"@})];
<subrule>   ::= @{<exception>@}  strict | overloading
<exception> ::= not_operator           | not_enumeration       |
                not_identical_renaming | not_different_families
@end example

@subsection Action
If ``strict'' is given (or if there is no subrule), the rule controls
strict hiding (an inner subprogram that overloads an outer one is not
considered hiding). If ``overloading'' is given, only subprograms that
overload another subprogram in the same scope or in an outer scope are
controlled. Note that following the normal Ada model, the declarations
of enumeration literals are considered functions (and thus
controlled).

Modifiers are used to exclude some controls (i.e. to allow the corresponding hiding):
@itemize @bullet
@item
``not_operator'': the subrule does not apply to the declarations of
operators (i.e. things like ``@code{"+"}'').
@item
``not_enumeration'': the subrule does not apply to the
hiding/overloading of enumeration literals by other enumeration
literals (the  rule still applies to the hiding/overloading of
functions by enumeration litterals, for example).
@item
``not_identical_renaming'' (only allowed with ``strict''): the subrule
does not apply to renamings where the renaming name is the same as the
name of the renamed entity. Such renamings are commonly used to
provide visibility of identifiers in a controlled way.
@item
``not_different_families'' (only allowed with ``strict''): the subrule
does not apply  if the hiding identifier and the hidden one do not
belong to the same ``family''. Families are either data (constant,
variables, numbers, etc.), types, subprograms (including entries),
packages, generics, exceptions, and labels (including block and loop
names).
@end itemize
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. @xref{Syntax of regular
expressions}.

This rule can be given only once for ``strict'' and once for
``overloading''.

Ex:
@example
Hiding: check local_hiding (strict);
Overloading: search local_hiding (not_operator overloading);
@end example

@subsection Variable
The rule provides a variable that allows to adjust the verbosity
of messages for the subrule ``overloading''.

@need 800
@multitable @columnfractions .23 .15 .12 .50
@item
@b{Variable} @tab @b{Values} @tab @b{Default} @tab @b{Effect}
@item
Overloading_Report
@tab compact@*detailed
@tab detailed
@tab  when the ``overloading'' subrule encounters a construct that
overloads several other constructs:
@table @asis
@item detailed
issue a message for each overloaded construct
@item compact
issue a single message mentionning how many constructs are overloaded,
and a pointer to the last one.
@end table
@end multitable

@subsection Tips
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 ``@code{^instance$}'' as an allowed pattern will
prevent error messages for these declarations.

Note that the name is given between ``@code{^}'' and
``@code{$}''. Otherwise, following normal regexp syntax, any
identifier @i{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.

@node Max_Blank_Lines, Max_Call_Depth, Local_Hiding, Rules reference
@section Max_Blank_Lines
This rule controls excessive spacing in the program text.

@subsection Syntax
@example
<control_kind> max_blank_lines (<max allowed blank lines>);
@end example

@subsection Action
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:
@example
search max_blank_lines (2);
check max_blank_lines (5);
@end example

@node Max_Call_Depth, Max_Line_Length, Max_Blank_Lines, Rules reference
@section Max_Call_Depth
This rule controls the maximum depth of subprograms (or entry) calls.
@subsection Syntax
@example
<control_kind> max_call_depth (<allowed depth> | finite @{, <entity>@});
@end example
@subsection Action
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 (not 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 @i{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>. @xref{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:
@example
search max_call_depth (9);
check  max_call_depth (finite);
@end example

@subsection Variable
The rule provides a variable that allows to specify how to handle
expression functions (Ada 2012).

@need 800
@multitable @columnfractions .25 .10 .10 .55
@item
@b{Variable} @tab @b{Values} @tab @b{Default} @tab @b{Effect}
@item
Count_Expr_Fun_Calls
@tab on@*off
@tab on
@tab
@table @asis
@item on
calls to expression functions are counted like regular calls
@item off
calls to expression functions are assumed to be inlined and do not add
an extra depth level.
@end table
@end multitable

@subsection Tip
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.

@subsection Limitations
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''. @xref{Uncheckable}.

@node  Max_Line_Length, Max_Nesting, Max_Call_Depth, Rules reference
@section Max_Line_Length
This rule controls that no line exceeds a given length.

@subsection Syntax
@example
<control_kind> max_line_length (<max allowed length>);
@end example

@subsection Action
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:
@example
search max_line_length (80);
check max_line_length (120);
@end example

@node Max_Nesting, Max_Size, Max_Line_Length, Rules reference
@section Max_Nesting
This rule controls excessive nesting of declarations.

@subsection Syntax
@example
<control_kind> max_nesting ([<subrule>,] <max allowed depth>);
<subrule> ::= all | generic | separate | task
@end example

@subsection Action
If ``all'' (or no subrule) is given as the first parameter, this rule
controls the nesting of declarative constructs (like subprograms,
packages, generics, block statements@dots{}) that exceed a given
depth. Nesting of statements (@code{@b{loop}}, @code{@b{case}}) is not
considered.

If ``generic'' is given as the first parameter, this rule controls the
nesting of generics, ignoring all non-generic units.

If ``separate'' is given as the first parameter, this rule controls the
nesting of separate bodies.

If ``task'' is given as the first parameter, this rule controls the
nesting of tasks (task types and single task objects), ignoring all
non-task units.

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 @i{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:
@example
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
@end example

@node Max_Size, Max_Statement_Nesting, Max_Nesting, Rules reference
@section Max_Size
This rule controls the maximum size, in source lines of code, of
various statements and declarations.

@subsection Syntax
@example
<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
@end example
@subsection Action
The first parameter is a subrule keyword that determines which
elements are controlled:
@itemize @bullet
@item
``accept'' controls accept statements.
@item
``block'' controls all block statements, while ``simple_block''
controls only blocks without a @code{@b{declare}} part, and
``unnamed_block'' controls only blocks without a name.
@item
``loop'' controls all loop statement, while ``unnamed_loop'' controls
only loops without a name.
@item
``if_branch'' and ``case_branch'' control the length of each
alternative of an @code{@b{if}} (respectively @code{@b{case}})
statement.
@item
``package_spec'', ``package_body'', ``procedure_body'',
``function_body'', ``protected_spec'', ``protected_body'',
``entry_body'', ``task_spec'', and ``task_body'' control the length of
the declaration of the corresponding element.
@item
``unit'' controls the whole length of compilation units.
@end itemize

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 @code{@b{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:
@example
check Max_Size (if_branch, 30);
search Max_Size (if_branch, 50);
check Max_Size (unnamed_loop, 20);
@end example

@subsection Tip
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.

@node Max_Statement_Nesting, Movable_Accept_Statements, Max_Size, Rules reference
@section Max_Statement_Nesting
This rule controls the nesting of compound statements.

@subsection Syntax
@example
<control_kind> max_statement_nesting (<subrule>, <max allowed depth>);
<subrule> ::= block | case | if | loop | all
@end example
@subsection Action
If one of ``block'', ``case'', ``if'', or ``loop'' is specified, it
controls the nesting of statements of the same kind, i.e. an
@code{@b{if}} within a @code{@b{loop}} within an @code{@b{if}} counts
only 2 for the ``if'' keyword. If ``all'' is specified, all kinds of
compound statements are counted together, i.e. an @code{@b{if}} within
a @code{@b{loop}} within an @code{@b{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:
@example
check max_statement_nesting (loop, 3);
search max_statement_nesting (all, 5);
@end example

@node Movable_Accept_Statements, Naming_Convention, Max_Statement_Nesting, Rules reference
@section Movable_Accept_Statements
This rule controls statements that are inside accept statements and
could safely be moved outside.

@subsection Syntax
@example
<control_kind> movable_accept_statements (certain|possible @{, <entity>@})
@end example
@subsection Action
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>. @xref{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 @code{certain}, only statements
after the last non-movable statement are reported.  If the first
parameter is @code{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:
@example
check movable_accept_statements (possible, Log.Report_Rendezvous);
@end example

@subsection Tips
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.

@node Naming_Convention, No_Operator_Usage, Movable_Accept_Statements, Rules reference
@section Naming_Convention
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.

@subsection Syntax
@example
<control_kind> naming_convention
   ([root] [others] @{<location>@} [<type_spec>] <filter_kind>,
    [case_sensitive|case_insensitive] [not] "<pattern>"
    @{, ...@});
<location>  ::= global | local | unit
<type_spec> ::= <entity> | @{<category>@}
<category>  ::= ()      | access    | array | delta  | digits | mod |
                private | protected | range | record | tagged | task
<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
@end example

@subsection Action
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). @xref{Syntax of regular expressions}.

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:
@itemize @bullet
@item
``unit'': The identifier is the defining name of a compilation unit.
@item
``global'': The identifier is  declared in a package or a  generic
package, possibly nested in other packages or generic packages.
@item
``local'': All other cases.
@end itemize

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>
keywords. As usual, the whole syntax for entities is allowed for
<entity>. @xref{Specifying an Ada entity name}. The meaning of
<category> is:
@itemize @bullet
@item
``()'': The object is of an enumerated type.
@item
``access'':  The object is of an access type.
@item
``array'': The object is of an array type.
@item
``delta'': The object is of a fixed point type (it is not currently
possible to distinguish ordinary fixed point types from decimal fixed
point types).
@item
``digits'': The object is of a floating point type.
@item
``mod'': The object is of a modular type.
@item
``private'': The object is of a private type (including private
extensions).
@item
``protected'': The object is of a protected type.
@item
``range'': The object is of a signed integer type.
@item
``record'': The object is of an (untagged) record type.
@item
``tagged'': The object is of a tagged type (including type
extensions).
@item
``task'': The object is of a task type.
@end itemize

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 @i{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:

@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_");
@end example

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 @i{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, @i{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:
@example
-- 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_");
@end example

@subsection Variable
The rule provides a variable that allows to specify the default
casing.

@need 800
@multitable @columnfractions .25 .10 .10 .55
@item
@b{Variable} @tab @b{Values} @tab @b{Default} @tab @b{Effect}
@item
Default_Case_Sensitivity
@tab on@*off
@tab off
@tab
@table @asis
@item on
controls that do not explicitely specify case sensitivity are case sensitive.
@item off
controls that do not explicitely specify case sensitivity are not case sensitive.
@end table
@end multitable

@subsection Tips
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. @xref{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 @i{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''.
@xref{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. 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:
@example
check naming_convention (renaming, "");
@end example
This imposes no constraint on renamings, but since it is specified
explicitely, the implicit rule for the renamed entity won't apply.

The @code{rules} directory of Adacontrol contains two files named
@code{no_standard_entity.aru} and @code{no_system_entity.aru}. These
are files that contain a naming_convention rule that forbids the
declaration of names declared in packages @code{Standard} and @code{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:
@example
Rule1 : check naming_convention (constant, "^c_");
Rule2 : check naming_convention (constant, "^const_");
@end example
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
rule file; this is the label that must be mentionned in a disabling
comment, unless you simply disable ``naming_convention''.

@subsection Limitations
This rule does not support wide characters outside the basic Latin-1 set.

@node No_Operator_Usage, Non_Static, Naming_Convention, Rules reference
@section No_Operator_Usage
This rule controls integer types that do not use any arithmetic
operators, which indicates that they might be replaceable with other
kinds of types.
@subsection Syntax
@example
<control_kind> no_operator_usage [([<category>] <parameter>
                                              [,<parameter>])];
<category>  ::= range | mod
<parameter> ::= [<filter>] <observed>
<filter>    ::= not | ignore | report
<observed>  ::= relational | logical | indexing
@end example
@subsection Action
This rule controls integer types where no arithmetic operator of the
type is used in the program. If the <category> is @code{range}, the
control applies only to signed integer types; if it is @code{mod}, it
applies only to modular integer types; otherwise, it applies to both.

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 (@code{<}, @code{<=}, @code{>},
@code{>=}, @code{@b{in}}, @code{@b{not in}}) are used, ``logical''
means that logical operators (@code{@b{and}}, @code{@b{or}},
@code{@b{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 @i{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:
@example
-- 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);
@end example

@subsection Tips
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 canditate 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.

The rule applies also to private types whose full declaration is an
integer type.

@node Non_Static, Not_Elaboration_Calls, No_Operator_Usage, Rules reference
@section Non_Static
This rule controls that expressions used in certain contexts are
static.
@subsection Syntax
@example
<control_kind> non_static [(<subrule> @{, <subrule>@})];
<subrule> ::= constant_initialization | variable_initialization |
              index_constraint        | discriminant_constraint |
              instantiation           | index_check
@end example

@subsection Action
The <subrule> defines the elements that are required to be static:
@itemize @bullet
@item
``constant_initialization'': expressions used as initial value in
constant declarations.
@item
``variable_initialization'': expressions used as initial value in
variable declarations.
@item
``index_constraint'': expressions used in index constraints (aka array
sizes).
@item
``discriminant_constraint'': expressions used in discriminant
constraints
@item
``instantiation'': expressions used as generic actual parameters in
instantiations.
@item
``index_check'': expressions used as indices must satisfy statically
the index check. I.e., the expression needs not be static, but it
should be statically provable that the index check cannot fail.
@end itemize

If no keyword is given, all contexts are controlled.

Ex:
@example
check non_static (index_constraint);
@end example

@subsection Limitations
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
@code{@b{null}}. This may improve in future versions of AdaControl.

@subsection Tips
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.

@node Not_Elaboration_Calls, Not_Selected_Name, Non_Static, Rules reference
@section Not_Elaboration_Calls
This rule controls that certain subprograms (or allocators) are called
only during program initialization.
@subsection Syntax
@example
<control_kind> not_elaboration_calls (<entity>|new @{, <entity>|new@});
@end example

@subsection Action
The <entity> parameters are callable entities (procedure, function or
entry calls). As usual, the whole syntax for entities is allowed for
<entity>. @xref{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.

Ex:
@example
search not_elaboration_calls (Data.Initialize, new);
@end example

@subsection Limitations
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 @code{"+"} on @code{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.

@node Not_Selected_Name, Object_Declarations, Not_Elaboration_Calls, Rules reference
@section Not_Selected_Name
This rule controls that certain entities are always refered to using
selected notation, even in the presence of @code{@b{use}} clauses.
@subsection Syntax
@example
<control_kind> not_selected_name
   (<exception places>, <entity> @{, <entity>@});
<exception places> ::= none | unit | compilation | family
@end example
@subsection Action
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 @i{not}
enforced, i.e. where simple notation is allowed:
@itemize @bullet
@item
``none'': selected notation is always required.
@item
``unit'': selected notation is not required within the program unit
where the entity is declared.
@item
``compilation'': selected notation is not required within the
compilation unit where the entity is declared.
@item
``family'': selected notation is not required within the compilation
unit where the entity is declared, nor within its (direct or indirect)
children.
@end itemize

Other parameters indicate the <entity> to which the rule applies. As
usual, the whole syntax for entities is allowed for <entity>.
@xref{Specifying an Ada entity name}.

Ex:
@example
check not_selected_name (unit, all Instance);
search not_selected_name (none, Pack.T);
@end example

@subsection Tip
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 @code{Instance}, @code{Object},
@code{T}) and are intended to be always used with the name of the
enclosing package.

@node  Object_Declarations, Parameter_Aliasing, Not_Selected_Name, Rules reference
@section Object_Declarations
This rule controls various aspects of object (constants and variables)
declarations.

@subsection Syntax
@example
<control_kind> object_declarations (min_integer_span, <min_spec>
                                                   @{, <min_spec>@});
<control_kind> object_declarations (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>
@end example

@subsection Action
The action depends on the subrule.
@itemize @bullet
@item
``min_integer_span'': controls that every object of an integer type
has a subtype that covers at least the indicated number of
values. Different values can be specified for variables and constants;
if no modifier (``constant'' or ``variable'') is supplied, the value
applies to both.

This subrule can be given only once for each combination of
check/search/count and constant/variable.
@item
``type'': controls every object whose (sub)type matches <entity>. As usual,
the whole syntax for entities is allowed for
<entity>. @xref{Specifying an Ada entity name}.  If the <entity> is a
subtype, only objects of that exact subtype are controlled; if the
<entity> is a type, objects declared with the type or any subtype of
it are controlled. The control can be restricted to only variables or
only constants; if no modifier (``constant'' or ``variable'') is
supplied, both are controlled.

This subrule can be given only once for each combination of <entity>
and constant/variable.
@item
``volatile_no_address'': controls variables that are the target of a
pragma volatile, but have no address clause. Constants are not
controlled, since it would be very strange to have a volatile
constant...

Since this subrule has no parameters, it can be given only once.
@item
``address_not_volatile'': controls variables that have an address
clause, but are not the target of a pragma volatile. Constants are not
controlled, since it would be very strange to have a volatile
constant...

Since this subrule has no parameters, it can be given only once.
@end itemize

Ex:
@example
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);
@end example

@subsection Tip
The ``min_integer_span'' rule can be useful for detecting variables
that should use an enumerated type rather than an integer type.

@subsection Limitation
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''. @xref{Uncheckable}.

Declaring a class-wide @emph{type} as volatile seems very peculiar
anyway...

@node  Parameter_Aliasing, Parameter_Declarations, Object_Declarations, Rules reference
@section Parameter_Aliasing
This rule controls aliased use of variables in subprogram
calls.

@subsection Syntax
@example
<control_kind> parameter_aliasing [([with_in] <level>)];
<level> ::= Certain | Possible | Unlikely
@end example

@subsection Action
This rule identifies calls where the same variable is given as an
actual to more than one @code{@b{out}} or @code{@b{in out}} parameter,
like in the following example:
@example
@b{procedure} Proc (X, Y : @b{out} Integer);
   ...
Proc (X => V, Y => V);
@end example

If the modifier ``@code{with_in}'' is given, aliasing between
@code{@b{out}} or @code{@b{in out}} parameters and @code{@b{in}}
parameters is also considered (unless the @code{@b{in}} parameter is
of a user-defined by-copy type). Although aliasing of @code{@b{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):
@itemize
@item
Certain (default): Only cases where aliasing is statically certain are
output.
@item
Possible: In addition, cases where aliasing may occur depending on
the value of an indexed component are output. These may or may not be
true aliasing, depending on the algorithm. For example, given:
@example
Swap (Tab (I), Tab (J));
@end example
there is no aliasing, unless @code{I} equals @code{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:
@example
Swap (Tab (1), Tab (2));
@end example

@item
Unlikely: In addition, cases where aliasing may occur due to access
variables pointing to the same variable are output. These may or may
not be true aliasing, depending on the algorithm, but should normally
occur only as the result of very strange practices, like in the
following example:
@example
@b{type} R @b{is}
   @b{record}
      X : @b{aliased} Integer;
   @b{end} @b{record};
X : R;
Y : Access_All_Integer := R.X'access;
   ...
P (X, Y.all);
@end example
@end itemize
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:
@example
check parameter_aliasing (with_in certain);
search parameter_aliasing (Possible);
@end example

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.

@subsection Limitation
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''. @xref{Uncheckable}.

@node Parameter_Declarations, Positional_Associations, Parameter_Aliasing, Rules reference
@section Parameter_Declarations
This rule controls various characteristics of the declaration of parameters
for all callable entities (i.e. functions, procedures and entries).

@subsection Syntax
@example
<control_kind> parameter_declarations (<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
@end example

@subsection Action
The first parameter is a subrule keyword. ``single_out_parameter'' has
no parameter; all other subrules require one or two bounds.
@itemize @bullet
@item
``all_parameters'': Controls callable entities whose number of
parameters is less than the given ``min'' or greater than the given
``max''. ``min'' defaults to 0 and ``max'' to infinity.
@item
``in_parameters'', ``out_parameters'', ``in_out_parameters'': Do the
same, counting only parameters of modes @code{@b{in}},
@code{@b{out}}, or @code{@b{in out}} respectively.
@item
``defaulted_parameters'': Does the same, counting only parameters
declared with an explicit default expression.
@item
``access_parameters'': Does the same, counting only (anonymous) access
parameters.
@item
``tagged_parameters'': Does the same, counting only parameters of
a specific tagged type.
@item
``class_wide_parameters'': Does the same, counting only parameters of
a class-wide type.
@item
``single_out_parameter'': Controls callable entities that have exactly
one @code{@b{out}} parameter. Procedures with a single  @code{@b{out}}
parameter might be candidates to becoming functions.
@end itemize

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:
@example
-- 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);
@end example

@subsection Tips
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...

@node Positional_Associations, Potentially_Blocking_Operations, Parameter_Declarations, Rules reference
@section Positional_Associations
This rule controls the use of positional associations (as opposed to
named associations) in all kinds of associations.

@subsection Syntax
@example
<control_kind> positional_associations [(<subrule>, <max_allowed>
                                         [, <category> @{, <entity>@}])];
<subrule>  ::= all | all_positional | same_type
<category> ::= [not_operator] call | discriminant     | pragma        |
               array_aggregate     | record_aggregate | instantiation |
               enumeration_representation
@end example

@subsection Action
The rule controls pragmas, discriminants, calls, aggregates, or
instantiations that use too many positional associations. The
definition of ``too many'' depends on the subrule:
@itemize
@item
``all'': when positional associations are given in a place where there
is more than <max_allowed> associations (both positional and named).
@item
``all_positional'': when there is more than <max_allowed> positional
associations.
@item
``same_type'': when more than <max_allowed> positional parameters are
of the same type.
@end itemize

In addition, a <category> can be specified to restrict the rule to
specific kinds of associations; if not specified, all associations are
controlled. The categories 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. Note that the ``same_type'' subrule is not allowed for the
``pragma'' category. 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 @i{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. @code{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>,
<category>, 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
``@code{positional_associations (all, 0)}'', i.e. all positional
associations are controlled.

Ex:
@example
 -- 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);
@end example

@subsection Tips
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:
@xref{Insufficient_Parameters}.

@node  Potentially_Blocking_Operations, Pragmas, Positional_Associations, Rules reference
@section Potentially_Blocking_Operations
This rule controls usage of potentially blocking operations (as
defined in LRM 9.5.1 (8..16)) from within protected operations.

@subsection Syntax
@example
<control_kind> potentially_blocking_operations;
@end example

@subsection Action
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:
@example
check potentially_blocking_operation;
@end example

@subsection Tips
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.

@subsection Limitation
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''. @xref{Uncheckable}.

@node Pragmas, Record_Declarations, Potentially_Blocking_Operations, Rules reference
@section Pragmas
This rule controls usage of one or several specific pragmas.

@subsection Syntax
@example
<control_kind> pragmas (<pragma spec> @{, <pragma spec>@});
<pragma spec> ::= [multiple] all|nonstandard|<pragma name>
@end example

@subsection Action
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 spec (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.

Ex:
@example
check pragmas (elaborate_all, elaborate_body);

-- Search pragma Convention that apply to several entities:
search pragmas (multiple convention);
@end example

@subsection Tips
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:
@example
C1 : count pragmas (annotate);
C2 : count pragmas (nonstandard);
C3 : count pragmas (all);
@end example
Counter C1 will report the number of occurrences of @code{@b{pragma}
Annotate} (a non-standard GNAT pragma), counter C2 will report the
number of non-standard pragmas (including occurrences of
@code{Annotate}), and counter C3 will report the total number of
pragmas (including occurrences of @code{Annotate}).

@node Record_Declarations, Reduceable_Scope, Pragmas, Rules reference
@section Record_Declarations
This rule controls various aspects of the components of records.

@subsection Syntax
@example
<control_kind> record_declarations (component, <compo_kind>
                                            @{,<repr_cond>@});
<compo_kind> ::= <entity>|<category>
<category>   ::= ()      | access    | array | delta  | digits | mod |
                 private | protected | range | record | tagged | task
<repr_cond>  ::= [not] in_variant | aligned | initialized | packed |
                 sized
@end example

@subsection Action
The first parameter is a subrule keyword:
@itemize
@item
``Component'' controls record components whose type is the indicated
<entity>, or whose type belongs to the indicated <category>. If the
<entity> is a subtype, only record components that are of that subtype
are controlled. If the indicated <entity> is a type, all record
components that are of that type (including subtypes) are
controlled. The meaning of <category> is:
@itemize @bullet
@item
``()'': The component is of an enumerated type.
@item
``access'':  The component is of an access type.
@item
``array'': The component is of an array type.
@item
``delta'': The component is of a fixed point type (it is not currently
possible to distinguish ordinary fixed point types from decimal fixed
point types).
@item
``digits'': The component is of a floating point type.
@item
``mod'': The component is of a modular type.
@item
``private'': The component is of a private type (including private
extensions).
@item
``protected'': The component is of a protected type.
@item
``range'': The component is of a signed integer type.
@item
``record'': The component is of an (untagged) record type.
@item
``tagged'': The component is of a tagged type (including type
extensions).
@item
``task'': The component is of a task type.
@end itemize
If <repr_cond> are specified, the rule controls only record components
to which all the corresponding representation items apply:
@itemize @bullet
@item
``in_variant'': The component appears inside the variant part of the
record.
@item
``not in_variant'': The component appears inside the fixed part of the
record.
@item
``aligned'': Either no component clause applies to the component, or
the corresponding first bit is a multiple of @code{Storage_Unit}.
@item
``not aligned'': A component clause applies to the component, and the
corresponding first bit is not a multiple of @code{Storage_Unit}.
@item
``initialized'': The component has a default initialization
expression.
@item
``not initialized'': The component has no default initialization
expression.
@item
``packed'': A pragma Pack applies to the component type.
@item
``not packed'': No pragma Pack applies to the component type.
@item
``sized'': A component clause applies to the component (therefore
imposing the size).
@item
``not sized'': No component clause applies to the component.
@end itemize
@end itemize

This rule can be specified several times for the ``component''
subrule.

Ex:
@example
-- 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);
@end example

@subsection Tips
It may seem strange to have a rule with only one subrule, but we
expect to add more in the near future. Stay tuned...

@subsection Limitations
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''.
@xref{Uncheckable}.

@node Reduceable_Scope, Representation_Clauses, Record_Declarations, Rules reference
@section Reduceable_Scope
This rule controls declarations that could be moved to some inner
scope.

@subsection Syntax
@example
<control_kind> reduceable_scope [(<subrule> @{, <subrule>@})];
<subrule> ::= @{<restriction>@} all        | variable | constant |
                              subprogram | type     | package  |
                              exception  | generic  | use
<restriction> ::= no_blocks | to_body
@end example
@subsection Action
The rule reports on any declaration that is referenced only from a
single, inner scope, or in the case of @code{@b{use}} clauses, it will
report on packages named in a @code{@b{use}} clause whose elements are
used only in a single, inner scope. For entitities declared in package
specifications, the rule reports if they are used only from 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 @code{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 @code{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:
@example
-- 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 clause should be as restricted as possible:
search reduceable_scope (use);
@end example

@subsection Tips
If you think that @code{@b{use}} clauses are acceptable, but should be
limited to the smallest possible scope, you would generally specify:
@example
check unnecessary_use_clause;
check reduceable_scope (use);
@end example

@subsection Limitation
Currently, the rule does not report @code{@b{use}} clauses declared in
a package specification that could be moved to the body. Such clauses
appear as ``unused'' (but of course, the compiler will complain on the
body if the clause is removed).

@node Representation_Clauses, Return_Type, Reduceable_Scope, Rules reference
@section Representation_Clauses
This rule controls usage of representation clause.

@subsection Syntax
@example
<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
<category> ::=
   ()     | range     | mod    | delta | digits  | array | record   |
   tagged | extension | access | new   | private | task  | protected
@end example

@subsection Action
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 belonging to the categories (the type of the component for
the @code{non_aligned_component} subrule):
@itemize @bullet
@item
``()'': Enumerated types
@item
``range'': Signed integer types
@item
``mod'': Modular types
@item
``delta'': Fixed point types (no possibility to differentiate ordinary
and decimal fixed point types yet).
@item
``digits'': Floating point types
@item
``array'': Array types
@item
``record'': (untagged) record types
@item
``tagged'': Root tagged types
@item
``extension'': Type extensions (tagged derived types)
@item
``access'': Access types
@item
``new'': Derived types
@item
``private'': Private types
@item
``task'': Task types
@item
``protected'': Protected types
@end itemize

The meaning of the representation keywords is:
@itemize @bullet
@item
``at'' controls address clauses given in Ada 83 style (``for XXX use
at'').
@item
``at_mod'' controls alignment clauses given in Ada 83 style (``for T
use record at mod XX;'').
@item
``enumeration'' controls enumeration representation clauses.
@item
``fractional_size'' controls size clauses whose value is not an
integral multiple of @code{System.Storage_Unit}. ``non_power2_size''
controls size clauses whose value in @code{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).
@item
``incomplete_layout'' controls record representation clauses that miss
the specification of some components of the record's type.
@item
``layout'' controls all record representation clauses, while
``no_bit_order_layout'' controls record representation clauses whose
type is not also the target of a bit_order attribute specification
(such types have a non-portable representation).
@item
``non_aligned_component'' controls components that do not start on a
storage unit boundary. The message gives the offset (in bits) relative
to the closest storage unit boundary.
@item
``non_contiguous_layout'' controls record representation clauses where
there are unused bits between components (or before the first
component). A message is issued for each ``gap'' between
components. In addition, if a size clause is given for the type, the
rule will report if there are unused bits at the end of the component
(i.e. the size clause is bigger than the end of the last
component). In the case of variant records, there can be
overlapping fields; the rule will control only the bits that belong to
no variant at all.
@item
``overlay'' controls address clauses (given in either style), where the value
given is the @code{'Address} of some other element.
@end itemize

In addition to these keyword, any specifiable attribute can be given
(including the initial ``@code{'}''); 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 ``@code{'CLASS'INPUT}'') can be given, and are
considered different from the simple attribute (``@code{'INPUT}''). It
is of course possible to specify both.

Ex:
@example
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);
@end example

@subsection Limitation
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''. @xref{Uncheckable}.

@subsection Tips
The specifiable attributes (the ones that can be given as parameters
to this rule) are @code{'Address}, @code{'Size},
@code{'Component_Size}, @code{'Alignment}, @code{'External_Tag},
@code{'Small}, @code{'Bit_Order}, @code{'Storage_Pool},
@code{'Storage_Size}, @code{'Write},  @code{'Output}, @code{'Read},
@code{'Input}, and @code{'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.

@node Return_Type, Side_Effect_Parameters, Representation_Clauses, Rules reference
@section Return_Type
This rule controls that certain form of types are not used for
function results.

@subsection Syntax
@example
<control_kind> return_type [(<subrule> @{, <subrule>@})];
<subrule> ::= class_wide                  | limited_class_wide  |
              constrained_array           | protected           |
              task                        | unconstrained_array |
              unconstrained_discriminated | anonymous_access
@end example

@subsection Action
This rule controls functions whose return type belongs to one of the
indicated type kinds:
@itemize @bullet
@item
@code{class_wide} controls all class-wide types, while
@code{limited_class_wide} controls only limited class-wide types.
@item
@code{constrained_array} controls constrained array types
@item
@code{unconstrained_discriminated} controls types with discriminants
(but not constrained subtypes of such types)
@item
@code{unconstrained_array} controls unconstrained array types
@item
@code{task} controls task types, or composite types that include tasks
as subcomponents.
@item
@code{protected} controls protected types, or composite types that include protected
objects as subcomponents.
@item
@code{anonymous_access} controls anonymous access types.
@end itemize

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:
@example
check return_type (unconstrained_discriminated, unconstrained_array);
@end example

@node Side_Effect_Parameters, Silent_Exceptions, Return_Type, Rules reference
@section Side_Effect_Parameters
This rule controls calls that may depend on the order of evaluation of
parameters.

@subsection Syntax
@example
<control_kind> side_effect_parameters (<entity> @{, <entity>@});
@end example

@subsection Action
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>. @xref{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:
@example
check side_effect_parameters (F1);
check side_effect_parameters (G1, G2);
@end example

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.

@subsection Limitation
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.

@node Silent_Exceptions, Simplifiable_Expressions, Side_Effect_Parameters, Rules reference
@section Silent_Exceptions
This rule controls exception handlers that can cause exceptions to
silently disappear.

@subsection Syntax
@example
<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>
@end example

@subsection Action
The rule controls handlers that do @i{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. @xref{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.

``@code{@b{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 @emph{only} ``@code{@b{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. @xref{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
@code{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
@code{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 @emph{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 @code{@b{if}} or @code{@b{case}}
statements, but not in all possible paths, or if they appear only in
the body of @code{@b{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:
@example
-- 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);

@end example

@subsection Limitations
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:
@itemize @bullet
@item
inside a pragma
@item
in a representation clause
@item
in a code statement (i.e. as a field of a machine code instruction)
@end itemize
This limitation is intentional: these are such weird places to call a
reporting function that it seems better to draw attention to it...

@node Simplifiable_Expressions, Simplifiable_Statements, Silent_Exceptions, Rules reference
@section Simplifiable_Expressions
This rule controls expressions that can be simplified in various ways.

@subsection Syntax
@example
<control_kind> simplifiable_expressions [(<subrule> @{, <subrule>@})];
<subrule> ::= conversion   | logical     | logical_false | logical_not |
              logical_true | parentheses | range
@end example

@subsection Action
Without parameters, all kinds of simplifiable expressions are
controlled; otherwise, the controlled expressions depend on the
subrule:
@itemize @bullet
@item
``conversion'' controls type conversions where the expression is of a
universal type (a litteral or named number), or where the target
subtype is either the same as the expression's subtype, or the first
named subtype of the expression.
@item
``logical_true'' controls redundant boolean expressions of the form
@code{<expr> = True} (or @code{/=}), and ``logical_false'' does the
same for comparisons with @code{false}.
@item
``logical_not'' controls @code{@b{not}} operators whose argument is a
comparison (which could be inverted).
@item
 ``logical'' is the same as specifying ``logical_true'',
``logical_false'' and ``logical_not''.
@item
``parentheses'' controls unnecessary parentheses like those
surrounding the expression of an assignment, an ``if'' or a ``case''
statement, or those that are not required by operators precedence
rules.
@item
``range'' controls expressions of the form @code{T'First .. T'Last}
that should be @code{T'range} (or even simply @code{T}).
@end itemize

This rule can be given at most once for each subrule.

Ex:
@example
search simplifiable_expressions (parentheses);
check  simplifiable_expressions (range, logical);
@end example

@subsection Tips
There are cases where parentheses may seem unnecessary, but are
(purposedly) not reported by this rule. Consider for example:
@example
   X := A + (B + C);
@end example
Removing the parentheses would change the expression to mean:
@example
   X := (A + B) + C;
@end example
If the @code{"+"} 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:
@example
  X mod (A*B)
@end example
is @i{not} the same as:
@example
  X mod A * B
@end example
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.

@node Simplifiable_Statements, Statements, Simplifiable_Expressions, Rules reference
@section Simplifiable_Statements
This rule controls statements that can be removed or simplified in
various ways without changing the meaning of the program.

@subsection Syntax
@example
<control_kind> simplifiable_statements [(<subrule> @{, <subrule>@})];
<subrule> ::= block       | dead   | handler | if             |
              if_for_case | if_not | loop    | loop_for_while |
              nested_path | null
@end example
@subsection Action
Without parameter, all kinds of simplifiable statements are
controlled; otherwise, the controlled statements depend on the
subrule:
@itemize @bullet
@item
@code{block} controls block statements that have no labels, no
declarations, and no exception handlers.
@item
@code{dead} controls dead code, i.e. statements that are statically
known to be never executed. This includes statements that follow a
@code{@b{return}}, @code{@b{requeue}}, or @code{@b{goto}} statement,
or an @code{@b{exit}} statement that is either unconditional or whose
condition is statically known to be true. It includes also
@code{@b{while}} statements and @code{@b{if}} statements (including
@code{@b{elsif}} paths) whose condition is statically false, and
@code{@b{for}} loops whose range is statically empty.
@item
@code{handler} controls ``trivial'' exception handlers, i.e. handlers
whose sequence of statements includes only a single @code{@b{raise}}
statement without an exception name. However, a handler is not
reported if there is also a non trivial handler for @code{@b{others}}.
These examples show the situation:
@example
@b{exception}
  @b{when} Constraint_Error => --Reported (no when others)
    @b{raise};
@b{end};

@b{exception}
  @b{when} Constraint_Error => --Reported (trivial when others)
    @b{raise};
  @b{when} @b{others} =>            --Reported
    @b{raise};
@b{end};

@b{exception}
  @b{when} Constraint_Error =>  --Not reported (non trivial when others)
    @b{raise};
  @b{when} @b{others} =>
    Put_Line ("Error");
@b{end};
@end example
@item
@code{if} controls @code{@b{if}} statements with an @code{@b{else}}
path that contains only @code{@b{null}} statements (and can thus be
removed).
@item
@code{if_for_case} controls usage of @code{@b{if}} statements that
could be replaced by @code{@b{case}} statements. An  @code{@b{if}}
statement is assumed to be replaceable if it has at least one
@code{@b{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:
@example
   @b{if} X = 1 @b{then}
      ...
   @b{elsif} X = 2 or X = 3 or X = 4 @b{then}
      ...
   @b{elsif} X >= 5 and X <= 10 @b{then}
      ...
   @b{elsif} X in 11 .. 20 @b{then}
      ...
   @b{else}
      ...
   @b{end} @b{if};
@end example
@item
@code{if_not} controls @code{@b{if}} statements with an
@code{@b{else}} path and no @code{@b{elsif}} path, and where the
condition is given in negative form (i.e. it is a @code{@b{not}}, or a
@code{"/="} comparison). Such statements could be made positive (and
thus less error-prone) by interverting the @code{@b{if}} and
@code{@b{else}} paths.
@item
@code{nested_path} controls paths from @code{@b{if}} statements that
can be moved outside. This happens if the @code{@b{if}} has only
@code{@b{then}} and @code{@b{else}} paths, and either of them ends
with a ``breaking'' statement (@code{@b{raise}}, @code{@b{return}},
@code{@b{exit}} or @code{@b{goto}}); in this case, the other path
needs not be nested inside the @code{@b{if}} statement. However, if
both paths end with the @i{same} ``breaking'' statement, no error is
reported. In short, the rule signals the following examples:
@example
@b{if} Cond @b{then}
   @b{return};
@b{else}
   I := 1;
@b{end} @b{if};

@b{if} Cond @b{then}
   I := 1;
@b{else}
   @b{return};
@b{end} @b{if};
@end example
because they can be changed to:
@example
@b{if} Cond @b{then}
   @b{return};
@b{end} @b{if};
I := 1;

@b{if} @b{not} Cond @b{then}
   @b{return};
@b{end} @b{if};
I := 1;
@end example
The rule will not signal the following example, where both paths end
with the same ``breaking'' statement (@code{@b{return}}), because it
would break the symetry of the statement:
@example
@b{if} Cond @b{then}
   @b{return} 1;
@b{else}
   @b{return} 2;
@b{end} @b{if};
@end example
@item
@code{null} controls @code{@b{null}} statements that serve no purpose
and can be removed.  Note that if a @code{@b{null}} statement carries
a label, it is not considered  simplifiable.
@item
@code{loop} controls @code{while} loop statements where the condition
is a plain @code{True}, and can thus be changed to simple loops.
@item
@code{loop_for_while} controls simple loop statements whose first
statement is an @code{@b{exit}} (for the same loop), and which can
therefore be turned into a @code{while} loop.
@end itemize

This rule can be given at most once for each subrule.

Ex:
@example
check simplifiable_statements (block, null);
search simplifiable_statements (if);
@end example

@subsection Tips
@code{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...

@node Statements, Style, Simplifiable_Statements, Rules reference
@section Statements
This rule controls usage of certain Ada statements.

@subsection Syntax
@example
<control_kind> statements (<subrule> @{, <subrule>@};

<subrule> ::=
   any_statement          | abort                    |
   accept                 | accept_return            |
   assignment             | asynchronous_select      |
   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_of_loop            | function_return          |
   goto                   | if                       |
   if_elsif               | inherited_procedure_call |
   labelled               | loop_return              |
   multiple_exits         | named_exit               |
   no_else                | null                     |
   procedure_call         | procedure_return         |
   raise                  | raise_locally_handled    |
   raise_nonpublic        | raise_standard           |
   redispatching_call     | reraise                  |
   requeue                | selective_accept         |
   simple_block           | simple_loop              |
   terminate              | timed_entry_call         |
   unconditional_exit     | unnamed_block            |
   unnamed_exit           | unnamed_loop_exited      |
   unnamed_for_loop       | unnamed_multiple_loop    |
   unnamed_simple_block   | unnamed_simple_loop      |
   unnamed_while_loop     | untyped_for              |
   untyped_for_in         | untyped_for_of           |
   while_loop
@end example

@subsection Action
Subrules that are Ada keywords control the corresponding Ada
statements. The meaning of other subrules is as follows:
@itemize @bullet
@item
@code{any_statement} controls all statements. This is of course not
intended to forbid all statements in a program (!), but
@emph{counting} all statements can be quite useful.
@item
@code{accept_return} controls return statements that return from an
@code{@b{accept}} statement, @code{entry_return} controls return
statements that return from a (protected) entry body, and
@code{procedure_return} controls return statements that return from a
procedure. @code{loop_return} controls return statements (including
extended return statements) that appear inside a @code{@b{loop}}
statement.
@item
@code{assignment} controls all assignment statements.
@item
@code{asynchronous_select} controls the @code{@b{select}}
... @code{@b{then abort}} statement. @code{conditional_entry_call}
controls the @code{@b{select}} ... @code{@b{else}}
statement. @code{timed_entry_call} controls the @code{@b{select}}
... @code{@b{or delay}} statement. @code{selective_accept} controls
the regular @code{@b{select}} statement.
@item
@code{block} controls all block statements, while @code{unnamed_block}
controls blocks without a name, @code{declare_block} controls blocks
with an explicit @code{@b{declare}} (even if the declarative part is
empty), and @code{effective_declare_block} controls blocks with a
declarative part that includes anything else than @code{@b{use}}
clauses and pragmas. @code{simple_block} controls block statements
that have no declarative part (or an empty declarative part) and no
exception handlers, and @code{unnamed_simple_block}  does the same,
but only for blocks without a name.
@item
@code{case} controls all @code{case} statements.
@item
@code{case_others} controls any @code{@b{when others}} path in a
@code{@b{case}} statement, while @code{case_others_null} controls only
@code{@b{when others}} paths in a @code{@b{case}} statement that
contain only @code{@b{null}} statements.
@item
@code{code} controls code statements.
@item
@code{delay} controls only relative @code{@b{delay}} statements, while
@code{delay_until} controls absolute @code{@b{delay until}}
statements.
@item
@code{entry_call} controls all entry call statements, including those
that are part of a conditional or timed entry call statement.
@item
@code{exit} controls all exit statements, while @code{exit_for_loop},
@code{exit_while_loop}, and @code{exit_plain_loop} control
@code{@b{exit}} statements that terminate @code{@b{for}} loops,
@code{@b{while}} loops, and plain (neither @code{@b{for}} nor
@code{@b{while}}) loops, respectively. @code{unconditional_exit}
controls @code{@b{exit}} statements without a @code{@b{when}}
condition.  @code{multiple_exits} controls loop that have more than
one @code{@b{exit}} statement.  @code{unnamed_loop_exited} controls
exit statements that terminate an unnamed loop. @code{exit_outer_loop}
controls @code{@b{exit}} statements that exit from an outer loop
(i.e. not the innermost one). @code{exit_expanded_name} controls named
@code{@b{exit}} statements where the name is given as an expanded
name.
@item
@code{exception_others} controls any @code{@b{when others}} exception
handler, while @code{exception_others_null} controls only
@code{@b{when others}} exception handlers that contain only
@code{@b{null}} statements.
@item
@code{extended_return} controls extended return statements (i.e. the
Ada 2005 construct ``@code{@b{return} V : T @b{do} ... @b{end}
@b{return}}'').  @code{exited_extended_return} controls extended
return statements that can be left without actually returning due to
an @b{exit} or @b{goto} statement  within their sequence of
statements.
@item
@code{for_loop} controls all @code{@b{for}} loops, while
@code{for_in_loop} controls only the traditional form of
@code{@b{for}} loop (@code{@b{for} I @b{in} @i{range} @b{loop}}),
@code{for_iterator_loop} controls the iterator form (@code{@b{for} I
@b{in} @i{Iterator} @b{loop}}), and @code{for_of_loop} controls the
components form (@code{@b{for} V @b{of} ... @b{loop}}) (the three
latter forms are not available with the old gnat version of
AdaControl).
@item
@code{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.
@item
@code{if} controls all @code{@b{if}} statements.
@item
@code{if_elsif} controls @code{@b{if}} statements that have at least
one @code{@b{elsif}}.
@item
@code{labelled} controls statements with a label (true statement
labels, not block and loop names).
@item
@code{named_exit} controls @code{@b{exit}} statements with a loop
name.
@item
@code{no_else} controls @code{@b{if}} statements that have no @code{@b{else}}
path.
@item
@code{null} controls all @code{@b{null}} statements.
@item
@code{procedure_call} controls all calls to
procedures. @code{dispatching_call} does the same, but only for
dispatching calls, while @code{redispatching_call} does the same, but
only for dispatching calls that are (directly or indirectly) inside a
primitive operation of a tagged type. @code{dynamic_procedure_call}
does the same, but only for calls through pointers.
@code{inherited_procedure_call} controls calls to procedures that have
been inherited by a derived type and not redefined.
@item
@code{raise} controls all @code{@b{raise}} statements.
@item
@code{reraise} controls @code{@b{raise}} statements in exception
handlers that reraise the same exception, and calls to the
@code{Ada.Exceptions.Reraise_Occurrence} procedure.
@item
@code{raise_standard} controls @code{@b{raise}} statements that raise
one of the predefined exceptions (those declared in package
@code{Standard}). @code{raise_nonpublic} controls statements that
raise exceptions that are neither predefined nor defined in the
visible part of a package. @code{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.  @code{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
@code{@b{raise}} statement, or by a call to
@code{Ada.Exceptions.Raise_Exception} where the raised exception is
statically determinable.
@item
@code{simple_loop} controls simple loops, i.e. those that are neither
@code{@b{while}} nor @code{@b{for}} loops.
@item
@code{unnamed_exit} controls @code{@b{exit}} statements without a
loop name that exits from a named loop.
@item
@code{unnamed_for_loop}, @code{unnamed_simple_loop}, and
@code{unnamed_while_loop} control loops of the given kind that are not
named.
@item
@code{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, @code{@b{for}}, @code{@b{while}}) is not considered.
@item
@code{untyped_for_in} controls regular @code{@b{for} .. @b{in}} loops
that use a range without an explicitely named type (i.e. @code{@b{for}
I @b{in} 1..10 @b{loop}}). Using a @code{'Range} attribute is
OK. @code{untyped_for_of} controls @code{@b{for} .. @b{of}} loops that
have no subtype indication. @code{untyped_for} controls both. Note
that generalized iterators are @i{not} controlled, since the syntax
does not allow the specification of an explicit subtype for them.
@item
@code{while_loop} controls all @code{@b{while}} loops.
@end itemize

Ex:
@example
search statements (delay);
check  statements (goto, abort);
check  statements (case_others_null, exception_others_null);
@end example

@subsection Variable
The rule provides a variable that allows to specify the amount of information
displayed with the ``procedure_call'' and ``entry_call'' subrules.

@need 800
@multitable @columnfractions .12 .18 .10 .60
@item
@b{Variable} @tab @b{Values} @tab @b{Default} @tab @b{Effect}
@item
Called_Info
@tab none@*compact@*detailed@*root_detailed
@tab none
@tab

@table @asis
@item``none''
No extra information.
@item ``compact''
display the name of the called procedure or entry.
@item ``detailed''
display the name of the called procedure or entry with overloading
information.
@item ``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.
@end table
@end multitable

@subsection Tips
It may seem strange to control things like @code{@b{if}} or
@code{@b{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 @code{@b{if}} to
@code{@b{case}} statements.

The plain ``raise'' subrule controls the @code{@b{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:
@example
"all raise": check statements (raise),
             check entities   (Ada.Exceptions.Raise_Exception,
                               Ada.Exceptions.Reraise_Occurrence);
@end example

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 @code{Ada.Exceptions}.

``inherited_procedure_call'' controls only @i{procedure} calls. For
function calls, see rule @ref{Expressions}.

@node Style, Terminating_Tasks, Statements, Rules reference
@section Style
This rules controls usage of various ``general'' Ada coding style.

@subsection Syntax
@example
<control_kind> style;
<control_kind> style (casing_attribute,  <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_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 (negative_condition);
<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 | 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>       ::= constant    | exponent | index | number | pragma |
                  repr_clause | var_init | type
@end example

@subsection Action
The first parameter specifies which style aspect is to be checked:

@itemize @bullet
@item
``casing_attribute'', ``casing_keyword'', ``casing_identifier'', and
``casing_pragma'' control that attributes (respectively keywords,
identifiers, or pragmas) use the appropriate casing. ``original''
(which is allowed only for identifiers) means that identifiers must
use the same casing as in their declaration.

If more than one <casing_kw> is given, it means that any of them is
allowed.
@item
``compound_statement'' controls that compound statements span at least
a minimum number of lines: 3 for @code{@b{if}} statements,
@code{@b{loop}} statements, block statements, and @code{@b{accept}}
statements with a body; 4 for @code{@b{case}} statements, selective
@code{@b{accept}} statements, and timed entry call statements; and 5
for conditional entry call statements and asynchronous select
statements.
@item
``default_in'' controls subprograms, entries and generics declarations
that omit an explicit @code{in} mode for a parameter. Access
parameters are not reported, since an an explicit @code{in} is not
allowed in that case.
@item
``exposed_literal'' controls the usage of literals (aka ``magic
values''), that appear outside of allowed places. The second parameter
tells to which kind of literals the rule applies. The (optional)
indicated values that follow are allowed at any place; for integers, a
single value can be preceded by ``max'', to indicate that all literals
whose (absolute) value is less or equal are allowed; for strings, the
values are regular expressions. @xref{Syntax of regular
expressions}. Commonly allowed values are 0 and 1 for integer
literals, 1.0 and 0.0 for real literals and "^$" (the empty string)
for string literals. At most 20 values of each kind may be
specified. In addition, one or several <place> keyword can be used to
specify constructs where any literal is allowed: ``declaration''
stands for any declaration, ``constant'' for constant declarations,
``exponent'' for the right parameter of an exponentiation
(i.e. @code{"**"}) 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 @code{number, constant}, i.e. any literal is
allowed in named numbers and constant declarations.
@item
``multiple_elements'' controls clauses, declarations, statements, and
handlers that do not start on a line of their own (i.e. when there are
more than one of these on the same line). Similarly,
@code{@b{begin}}, @code{@b{end}}, @code{@b{then}} and @code{@b{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 @code{@b{is}}, @code{@b{loop}} or @code{@b{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
@code{@b{use}} clause to be on the same line as a @code{@b{with}}
clause, provided all packages named in the @code{@b{use}} clause are
also named in the preceding @code{@b{with}} clause.
@item
``negative_condition'' controls ``if'' statements with an ``else''
part and no ``elsif'', where the condition starts with a
@code{@b{not}}, and should therefore preferably be expressed
positively.
@item
``no_closing_name'' controls declarations, like package or subprograms,
that allow (but do not require) repeating the name at the end of the
declaration, and where the closing name is omitted (which is
considered bad style in general). However, it can be acceptable to
allow the omission of closing names for very short constructs;
therefore this rule has an optional parameter specifying the maximum
number of lines of a construct for which omitting the closing name is
allowed. This rule can be given only 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. If no length is specified, all occurrences of missing closing
names are signaled.
@item
``numeric_literal'' controls the presentation of numeric literals, depending
on the base (wich, as required by Ada rules, must be in the range
2..16). If ``not <base>'' is specified as the second parameter, the
given base may not be used for based literals. Otherwise, there must
be a third (integer) parameter to specify the size of blocks of digits
for that base, i.e. there must be an underscore character to separate
digits every <block_size> position. Typically, <block_size> is 3 for
base 10, 4 for base 2, etc.
@item
``parameter_order'' and ``formal_parameter_order'' control the order
of the declarations of parameters or generic formal parameters,
respectively. Each parameter of the rule consists in one or several of
the ``mode'' keywords, and describes, in order, which kind of
parameter is allowed. All modes not specified explicitely are allowed
after the ones that are specified.  See examples below.

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''.
@item
``renamed_entity'' controls occurrences of identifiers within the scope
of a renaming declaration for them; i.e. it enforces that when an entity
has been renamed, the original name should not be used anymore.
@end itemize

Ex:
@example
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);

@end example

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:
@example
style (no_closing_name);
style (casing_attribute, titlecase);
style (casing_keyword, lowercase);
style (casing_identifier, original);
style (casing_pragma, titlecase);
style (default_in);
style (negative_condition)
style (multiple_elements)
style (literal, 10, 3);
style (exposed_literal, integer, 0, 1)
style (exposed_literal, real, 0.0, 1.0);
@end example

@subsection Tips
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 @code{"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.

@subsection Limitations
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''. @xref{Uncheckable}.

@node Terminating_Tasks, Type_Initial_Values, Style, Rules reference
@section Terminating_Tasks
This rule controls tasks that can terminate.

@subsection Syntax
@example
<control_kind> terminating_tasks
@end example

@subsection Action
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
@code{@b{terminate}} alternative.

Since this rule has no parameters, it can be given only once.

Ex:
@example
check terminating_tasks;
@end example

@subsection Tips
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)''. @xref{Statements}.

@node  Type_Initial_Values, Type_Usage, Terminating_Tasks, Rules reference
@section Type_Initial_Values
This rule controls that a special constant is declared together with
each type, for example to serve as a default initial value.

@subsection Syntax
@example
<control_kind> type_initial_values [("<pattern>")];
@end example
@subsection Action
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:
@example
check type_initial_values ("^C_Init_");
@end example
The above example will ensure that every declared type features a
constant of the type whose name starts with ``C_Init_''.

@node Type_Usage, Uncheckable, Type_Initial_Values, Rules reference
@section Type_Usage
This rule controls usage of indicated types, either individually
or by category.

@subsection Syntax
@example
<control_kind> type_usage (<attribute>, <category> @{, <aspect>@}]);
<control_kind> type_usage (index, <entity>|<category> @{, <aspect>@}]);
<category> ::= ()  | access    | array | delta  | digits |
               mod | protected | range | record | tagged | task
<aspect>   ::= [not] representation | pack | size | component_size
@end example

@subsection Action
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>. @xref{Specifying an Ada entity
name}.

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 <category> is:
@itemize @bullet
@item
``()'': The type is an enumerated type.
@item
``access'':  The type is an access type.
@item
``array'': The type is an array type.
@item
``delta'': The type is a fixed point type (it is not currently
possible to distinguish ordinary fixed point types from decimal fixed
point types).
@item
``digits'': The type is a floating point type.
@item
``mod'': The type is a modular type.
@item
``protected'': The type is a protected type.
@item
``range'': The type is a signed integer type.
@item
``record'': The type is an (untagged) record type.
@item
``tagged'': The type is a tagged type (including type
extensions).
@item
``task'': The type is a task type.
@end itemize

The meaning of <aspect> is:
@itemize @bullet
@item
``representation'': the type has an enumeration representation clause
or a record representation clause.
@item
``pack'': the type is the target of a pack @code{@b{pragma}}.
@item
``size'' and ``component_size'': the type has the corresponding
attribute specified.
@end itemize

Ex:
@example
-- 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);
@end example

@subsection Tips
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''. @xref{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''.  @xref{Entities}.

@node  Uncheckable, Unit_Pattern, Type_Usage, Rules reference
@section Uncheckable
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.

@subsection Syntax
@example
<control_kind> uncheckable [(<subrule> [,<subrule>])];
<subrule> ::= false_positive | false_negative | missing_unit
@end example

@subsection Action
If the keyword ``missing_unit'' is given, this rule controls missing
units,  i.e. units given on the command line that are not found (and
therefore not controlled) will result in an usual error message.

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 the keyword ``false_negative'' is given, the rule will control
constructs that could result in false negatives, i.e. possible
violations that would go undected, while if the keyword
``false_positive'' is given, it will control constructs that could
result in false positives, i.e. error messages when the rule is not
really violated. If no keyword is given, both occurrences are
controlled.

As far as statistics are concerned (see @ref{Control kinds and 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 of value of the parameters.

Ex:
@example
check uncheckable (false_negative);
search uncheckable (false_positive);
check uncheckable (missing_unit);
@end example

@subsection Tips
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.

@subsection Limitation
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''!

@node Unit_Pattern, Units, Uncheckable, Rules reference
@section Unit_Pattern
This rule controls various usage patterns of program units and
elements declared in them.

@subsection Syntax
@example
<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 | pragma
<target>           ::= package_public | package_private | package_body |
                       subprogram
<decl_list>   ::= <declaration> @{| <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
@end example

@subsection Action
The checked pattern depends on the given subrule:
@itemize @bullet
@item
``single_tagged_type'' controls that at most one tagged type is
declared in any package.
@item
``tagged_type_hierarchy'' controls that tagged types follow packages
hierarchy, i.e. that the parent of a type extension (derivation of a tagged
type) is declared in the parent unit of the one that declared the
derivation.
@item
``context_clauses_order'' controls the order of context clauses (and
pragmas) given on top of the unit. Each parameter of the rule consists
in one or several of the <clause> keywords, and describes, in order,
which kind of clause is allowed. Note that ``use_type'' covers only
the regular @code{@b{use type}} clause, specify also ``use_all_type''
to include the Ada 2012 @code{@b{use all type}} clause as well. Note
that all <clause>s not specified explicitely have no place, and thus
are not allowed at all.
@item
``declarations_order'' controls the order of declarations (and use clauses)
given in various parts, depending on the second parameter:
@itemize
@item
``package_public'' controls elements in the visible part of a package specification;
@item
``package_private'' controls elements in the private part of a package
specification;
@item
``package_body'' controls elements in the body of a package;
@item
``subprogram'' controls elements in the body of subprograms
(procedures and functions) and entries.
@end itemize
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.
@end itemize
Ex:
@example
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);
@end example

@subsection Tips
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''. @xref{Declarations}.

@node Units, Unnecessary_Use_Clause, Unit_Pattern, Rules reference
@section Units
This rule controls that all necessary units, and only those, are
processed by AdaControl.

@subsection Syntax
@example
<control_kind> units [(<subrule> [,<subrule>])];
<subrule> ::= unreferenced | unchecked
@end example

@subsection Action
If the keyword @code{unreferenced} is given, the rule controls
compilation units that are part of the set of analyzed units, but
withed by no other unit. If the keyword @code{unchecked} is given, the
rule controls compilation units that are withed by other unit(s), but
not part of the set of controlled units (except standard units).

This rule can only be given once for each of the subrules.

Ex:
@example
check units (unchecked);
search units (unreferenced);
@end example

@subsection Tip
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:
@example
--## rule line off units
@end example
on the main program.

@node Unnecessary_Use_Clause, Unsafe_Elaboration, Units, Rules reference
@section Unnecessary_Use_Clause
This rule controls @code{@b{use}} clauses that do not serve any
purpose.

@subsection Syntax
@example
<control_kind> unnecessary_use_clause [(<subrule> @{,<subrule>@})];
<subrule> ::= unused | qualified | operator | nested | movable
@end example

@subsection Action
The rule controls  @code{@b{use}} clauses that can safely be removed,
moved, or changed to a @code{@b{use type}} clause. This happens in the
following cases:
@itemize
@item
``unused'': a @code{@b{use}} clause is given, but no element from the
corresponding package is mentionned in its scope. The message starts
with ``unused:''.

In this case, the @code{@b{use}} clause can safely be removed.
@item
``qualified'': a @code{@b{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). The message starts with
``all uses qualified:''.

In this case, the @code{@b{use}} clause can safely be removed, but you
may want to keep it for documentation purposes, since the package is
actually used within this scope.
@item
``operator'': a @code{@b{use}} clause is given, but the only elements
that do not use a qualified name are operators. The message starts
with ``only used for operators:''.

In this case, and except for some pathological cases (definition of
operators that are not primitive operations of the corresponding
type), the @code{@b{use}} clause can be replaced by one or several
@code{@b{use type}} clause(s).
@item
``nested'': a @code{@b{use}} clause is given within the scope of an
enclosing @code{@b{use}} clause for the same package. The message
tells the location of the other @code{@b{use}} clause.

If you also have a message that the outer @code{@b{use}} clause is
unnecessary, this means that all references to the package appear
inside the inner @code{@b{use}} clauses, and that the outer one can be
removed. If not, you can either remove the inner @code{@b{use}}
clauses, or remove the outer one and add more local @code{@b{use}}
clauses where necessary.
@item
``movable'': a @code{@b{use}} clause is given in a package
specification, but all uses are from the corresponding body. The
message starts with ``use clause can be moved to body:''.

In this case, the @code{@b{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.
@end itemize

If no parameter is given, all cases are controlled, otherwise only
cases corresponding to the specified keyword(s) are controlled. This
rule can be given only once for each value of  the parameters.

Ex:
@example
remove: search unnecessary_use_clause (unused);
use_type: check unnecessary_use_clause (operator);
@end example

@subsection Tip
This rule checks only usage of @code{@b{use}} clauses. The rule
``reduceable_scope'' can be used to check that @code{@b{use}} clauses
do not span unnecessarily to wide a scope. @xref{Reduceable_Scope}.

@subsection Limitations
There are some rare cases where the rule may signal that a
@code{@b{use}} clause is not necessary, where it actually is. There is
no risk associated to this since if you remove the @code{@b{use}}
clause, the program will not compile.

The first one comes from a limitation of the ASIS standard: if the
@i{only} use of the @code{@b{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 @i{only} use of the @code{@b{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:
@itemize
@item
the operation is the target of a renaming declaration;
@item
or the operation is passed as an actual to a generic instantiation;
@item
or all operands of the operation are universal (i.e. untyped).
@end itemize

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. @xref{Disabling controls}. Note that for the third alternative
of the second case, you can also qualify one of the parameters, so it
is not universal any more.

@node  Unsafe_Elaboration, Unsafe_Paired_Calls, Unnecessary_Use_Clause, Rules reference
@section Unsafe_Elaboration
This rule controls (generic) packages that may be subject to
elaboration order dependencies.

@subsection Syntax
@example
<control_kind> unsafe_elaboration;
@end example

@subsection Action
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 @code{@b{pragma}}
@code{Elaborate} or @code{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:
@example
check unsafe_elaboration;
@end example

@subsection Tips
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.

@node  Unsafe_Paired_Calls, Unsafe_Unchecked_Conversion, Unsafe_Elaboration, Rules reference
@section Unsafe_Paired_Calls
This rule controls usage of calls to operations that are normally
paired (like P/V operations) and do not follow a "safe" coding
pattern.

@subsection Syntax
@example
<control_kind> unsafe_paired_calls
   (<opening procedure>, <closing procedure> [, <lock type>]);
<opening procedure> ::= <entity>
<closing procedure> ::= <entity>
<lock type>         ::= <entity>
@end example

@subsection Action
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:
@itemize @bullet
@item
@i{abstract state machines}: There is no ``lock'' object, locking is
done directly inside the procedures. The <lock type> parameter of the
rule must not be provided in that case.
@item
@i{object abstract data types}: The procedure operates on an object
(generally of a private type) representing the ``lock'' object, passed
as an ``in out'' parameter. The third parameter must be the
corresponding type, and the rule will control that all matching pairs of
calls refer statically to the same variable.
@item
@i{reference abstract data types}: The procedure operates on a
reference that designates the ``lock'' object, passed as an
``in''parameter. The third parameter must be the corresponding type,
which must be discrete or access, and the rule will control that all
matching pairs of calls refer statically to the same value (for
discrete types) or to the same constant  (for access types).
@end itemize

As usual, the whole syntax for entities is allowed for
<entity>. @xref{Specifying an Ada entity name}.

An @i{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, possibly followed by @b{exit},
@b{return}, and @b{null} statements (and no others).

Similarly, a @i{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 @b{exit}, @b{return}, and @b{null} statements (and no
others).

An opening and a closing block match if:
@itemize @bullet
@item
corresponding calls to the
procedures of a pair use the appropriate value for the ``lock''
parameter (if any), as explained above
@item
if statements have their conditions refer to the
same constant, and their if and else paths contain matching blocks.
@end itemize

The "safe" coding pattern is defined as follows:
@itemize @bullet
@item
An opening block is the first statement of a
handled sequence of statements;
@item
A closing block is the last statement of the same handled sequence of
statements, except for possible @b{exit}, @b{return}, and @b{null}
statements following it.
@item
The opening and closing blocks match.
@item
There is no other call to either operation in the statements of the
handled sequence of statements, except in nested blocks or accept
statements; calls in such inner statements shall not reference the
same values or variables as outer ones.
@item
There is an exception handler for "others" in the
handled sequence of statements.
@item
Every exception handler of the handled sequence of statements includes
a single closing block matching the opening block at the top of the
sequence of statements.
@end itemize

Typically, the ``safe'' pattern corresponds to the following structures:
@example
-- Abstract state machine
@b{begin}
   P;
   -- Do something
   V;
@b{exception}
   @b{when} @b{others} =>
      V;
      -- handle exception
@b{end};

-- Object abstract data type
@b{declare}
   My_Lock : Lock_Type;
@b{begin}
   P (My_Lock);
   -- Do something
   V (My_Lock);
@b{exception}
   @b{when} @b{others} =>
      V (My_Lock);
      -- handle exception
@b{end};

-- Reference abstract data type
@b{declare}
   Lock_Ptr : @b{constant} Lock_Access := Get_Lock;
@b{begin}
   P (Lock_Ptr);
   -- Do something
   V (Lock_Ptr);
@b{exception}
   @b{when} @b{others} =>
      V (Lock_Ptr);
      -- handle exception
@b{end};

-- Conditional blocks
@b{declare}
   Lockable : @b{constant} Boolean := ...;
   Lock1    : @b{constant} Boolean := ...;
@b{begin}
   @b{if} Lockable @b{then}
      @b{if} Lock1 @b{then}
         Lock (V1);
      @b{else}
         Lock (V2);
      @b{end} @b{if};
   @b{end} @b{if};
   -- Do something
   @b{if} Lockable @b{then}
      @b{if} Lock1 @b{then}
         Unlock (V1);
         @b{return};
      @b{else}
         Unlock (V2);
         @b{exit};
      @b{end} @b{if};
   @b{end} @b{if};
@b{end};
@end example

Ex:
@example
check unsafe_paired_calls (Sema.P, Sema.V, Sema.Lock_Access);
@end example

@subsection Variable
The rule provides a variable that allows to control whether opening
and closing blocks can contain @b{if} statements, or just calls to the
procedures.

@need 800
@multitable @columnfractions .25 .10 .10 .55
@item
@b{Variable} @tab @b{Values} @tab @b{Default} @tab @b{Effect}
@item
Conditionals_Allowed
@tab off@*on
@tab on
@tab
@table @asis
@item off
only direct calls to the indicated procedures are allowed as opening
and closing blocks
@item on
calls can be nested in if statements as described above.
@end table
@end multitable

@subsection Tips
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 @code{Mask_Interrupt} procedure that should be matched by
either @code{Unmask_Interrupt} or @code{General_Reset} (all declared
in package @code{IT_Driver}), you can specify:
@example
check unsafe_paired_calls (IT_Driver.Mask_Interrupt,
                           IT_Driver.Unmask_Interrupt);
check unsafe_paired_calls (IT_Driver.Mask_Interrupt,
                           IT_Driver.General_Reset);
@end example

Normally, the legality of a rule is checked when the rules 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.

@subsection Limitation
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''.
@xref{Uncheckable}.

Due to a size limitation of internal data structures, this rule can be
specified at most 32 times.

@node Unsafe_Unchecked_Conversion, Usage, Unsafe_Paired_Calls, Rules reference
@section Unsafe_Unchecked_Conversion
This rule controls unchecked conversions between types which are not
statically known to have identical sizes.
@subsection Syntax
@example
<control_kind> unsafe_unchecked_conversion
@end example
@subsection Action
This rule controls instances of @code{Unchecked_Conversion} between
types where the following conditions are not met:
@itemize @bullet
@item
A size clause has been specified for both types
@item
Both sizes are equal
@end itemize

Moreover, a special message is given if any of the types is a class-wide
type (certainly a very questionable construct!).

Ex:
@example
check unsafe_unchecked_conversion
@end example

@subsection Limitation
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:
@example
@b{for} T'Size @b{use} Integer'size;
@end example

This can lead to false positives (i.e. detection of instantiations of
@code{Unchecked_Conversion} that are actually OK). Such cases are
detected by the rule ``uncheckable''. @xref{Uncheckable}.

@node  Usage, Use_Clauses, Unsafe_Unchecked_Conversion, Rules reference
@section Usage
This rule controls how certain entitities (variables, constants,
types, procedures, functions, exceptions, tasks, protected objects,
and generics) are used.
@subsection Syntax
@example
<control_kind> usage
   (variable|object @{,[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
@end example

@subsection Action
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. ``accessed'' (available
for subprograms only) restricts entities being checked to those that
appear as the prefix of a @code{'Access} or @code{'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
@code{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 @code{Raise_Exception} and tasks aborted by
calling @code{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. @xref{limitation}.

Note that usage of entities whose declaration is not processed (like,
typically, elements declared in standard packages like
@code{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:
@example
-- 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 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);
@end example

@subsection Tips
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.

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.:
@example
search usage (variable, from_spec, read, written);
@end example
is the same as:
@example
search usage (variable, from_spec, read, written, initialized);
search usage (variable, from_spec, read, written, not initialized);
@end example
Therefore, the following example will complain on the second line that
the rule has already been given for this combination of parameters:
@example
search usage (variable, from_spec, read, written);
search usage (variable, from_spec, read, written, not initialized);
@end example

Note that the notion of constants for this rule includes named numbers.

@anchor{limitation}
@subsection Limitations
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 @code{'Identity} to a
procedure that will in turn call @code{Raise_Exception} (and similarly
for @code{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 @code{'Identity} attribute
with the following rule:
@example
check entity (all 'Identity);
@end example

If an object is the prefix of a @code{'Access},
@code{'Unchecked_Access}, or @code{'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''. @xref{Uncheckable}.

Due to a weakness of the ASIS standard, it is not possible to know the
mode (@b{in}, @b{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''.  @xref{Uncheckable}.

@node Use_Clauses, With_Clauses, Usage, Rules reference
@section Use_Clauses
This rule controls usage of @code{@b{use}} clauses.

@subsection Syntax
@example
<control_kind> use_clauses
   [([<subrule>,] <package name> @{, <package name>@})];
<subrule> ::= package | local | global | type | type_local | type_global
@end example

@subsection Action
The rule controls every  @code{@b{use}} or @code{@b{use type}} clause,
@i{except} those that name one of the mentioned packages/types. It is
therefore possible to allow @code{@b{use}} or  @code{@b{use type}}
clauses just for certain packages/types.

If the keyword ``package'' is given (or no keyword at all), all
package @code{@b{use}} clauses are controlled. If the keyword
``global'' is given, only @code{@b{use}} clauses that appear in
context clauses (i.e. together with the @code{@b{with}} clauses) are
controlled; if the keyword ``local'' is given, only @code{@b{use}}
clauses that appear as declarations are controlled.

If the keyword ``type'' is given, all @code{@b{use type}} clauses are
controlled. If the keyword ``type_global'' is given, only @code{@b{use
type}} clauses that appear in context clauses (i.e. together with the
@code{@b{with}} clauses) are controlled; if the keyword ``type_local''
is given, only @code{@b{use type}} clauses that appear as declarations
are controlled.

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:
@example
-- 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 (type_global);
count (type);
@end example

@node With_Clauses,  , Use_Clauses, Rules reference
@section With_Clauses
This rule controls @code{@b{with}} clauses that should be removed or
moved to a better place.

@subsection Syntax
@example
<control_kind> with_clauses [(<subrule> [, <subrule>])];
<subrule> ::= multiple_names | reduceable | inherited
@end example

@subsection Action
The parameters are subrule keywords that determine which kind of
control is performed:
@itemize @bullet
@item
@code{multiple_names} controls any @code{@b{with}} clause that
mentions more than one unit name.
@item
@code{reduceable} reports:
@itemize @bullet
@item
Redundant @code{@b{with}} clauses, i.e. clauses given more than once
for the same unit. This includes the case where the same
@code{@b{with}} clause is given in a specification and the
corresponding body, and the case of renamings of a same unit
(i.e. @code{Text_IO} and @code{Ada.Text_IO}). Note that giving a
@code{@b{with}} clause in a unit, and repeating it in a child unit (or
subunit) is @i{not} considered redundant.
@item
Unused @code{@b{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 @code{@b{with}} clause is given on a package specification, the
message reminds that it migh be useful for child units.
@item
Moveable @code{@b{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 @code{@b{private}} @code{@b{with}}.
@end itemize
@item
@code{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 @code{@b{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.
@end itemize

Each of the keywords can be given at most once. If no keyword is
given, both @code{reduceable} and @code{inherited} are assumed.

Ex:
@example
check with_clauses (multiple_names, reduceable);
search with_clauses (inherited);
@end example

@subsection Variables
@multitable @columnfractions .25 .10 .10 .55
@item
@b{Variable} @tab @b{Values} @tab @b{Default} @tab @b{Effect}
@item
Check_Private_With
@tab off@*on
@tab on
@tab
@table @asis
@item on
issues a message when a @code{@b{with}} can be
replaced with a @code{@b{private}} @code{@b{with}}.
@item off
do not issue a message when a @code{@b{with}} can be replaced with a
@code{@b{private}} @code{@b{with}} (useful in Ada 95 mode).
@end table
@item
Ignore_Use_Clause
@tab off/on
@tab on
@tab
@table @asis
@item on
package names appearing in use clauses are not considered as a usage
of the package.
@item off
names appearing in use clauses are treated like any other identifier
(see tip below).
@end table
@end multitable

@subsection Tips
A @code{@b{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 @code{@b{use}} clause is @i{not}
considered a usage of the package; clearly, the @code{@b{with}} clause
can (and should) be removed (or moved) if the only use of the package
is in @code{@b{use}} clauses (removing or moving the @code{@b{use}}
clauses by the same token). However, some programming rules may require
placing @code{@b{use}} clauses in certain places, forcing the corresponding
@code{@b{with}} clause. Set the variable @code{Ignore_Use_Clause} to
@code{off} to make sure that a @code{@b{use}} clause does mark the
@code{@b{with}} clause as necessary.

@node Examples of using AdaControl for common programming rules, Specifying an Ada entity name, Rules reference, Top
@chapter Examples of using AdaControl for common programming rules

In most projects, there are @i{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.

@menu
* Migrating from Gnatcheck::
* Rules files provided with AdaControl::
* Automatically checkable rules::
* Rules that need manual inspection::
@end menu

@node  Migrating from Gnatcheck, Rules files provided with AdaControl, Examples of using AdaControl for common programming rules, Examples of using AdaControl for common programming rules
@section Migrating from Gnatcheck
The file @code{gnatcheck.aru} in directory @code{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.

@node Rules files provided with AdaControl, Automatically checkable rules, Migrating from Gnatcheck, Examples of using AdaControl for common programming rules
@section Rules files provided with AdaControl
The @code{rules} directory provides also rules files that can be
sourced to enforce some commonly encountered general rules.

@rule{Identifiers from Standard shall not be redefined}

Use file @code{no_standard_entity.aru}.

@rule{Identifiers from System shall not be redefined}

Use file @code{no_system_entity.aru}.

@rule{Predefined IO packages shall not be used}

Use file @code{no_io.aru}.

@rule{Standard package XXX shall not be used}

File @code{no_standard_unit.aru} controls usage of @i{all} standard
packages. Comment out those that you do want to allow.

@rule{Obsolescent features shall not be used}

Use file @code{no_obsolescent_features.aru}. Not all obsolescent features are
controlled, but most of them (those that are most worth checking) are.

@rule{Gnat specific attributes shall not be used}

Use file @code{no_gnat_attribute.aru}

@rule{Features from annex X shall not be used}

Use file @code{no_annex_X.aru}.

@rule{The Ravenscar profile shall be enforced}

Use file @code{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 rule file is
also slightly more restrictive than the profile; for example, the
restriction ``no_task_allocation'' only disallows task allocators,
while this rule file controls the declaration of access types on tasks.

@rule{NASA coding guidelines shall be enforced}

Use file @code{nasa.aru}. This file is an example of how to convert guidelines (available from @url{http://fsw.gsfc.nasa.gov/gds/code_standards_ada.pdf}) into an AdaControl rules file.

@rule{Ada 83 unit names shall not be used (i.e. use @code{Ada.Text_IO}, not @code{Text_IO})}

Use file @code{no_83_unit_name.aru}.

@rule{New reserved words of Ada 2005/2012 shall not be used}

Use file @code{reserved_2005.aru}. (the file name mentions only 2005,
but it checks also for 2012 - after all, there is only one extra
reserved word).

@rule{Measurements for the SQALE method}

AdaControl can provide measurements required by the SQALE quality
measurement method. The corresponding file is @code{SQALE.aru}.

For information about the SQALE method, please refer to J-P Rosen's paper at
@url{http://www.adalog.fr/publicat/sqale.pdf}

@node Automatically checkable rules, Rules that need manual inspection, Rules files provided with AdaControl, Examples of using AdaControl for common programming rules
@section Automatically checkable rules
Below are examples of rules that can be directly checked by AdaControl.

@rule{Goto statement shall not be used}
@example
check statements (goto);
@end example

@rule{Functions shall not have @code{@b{out}} or @code{@b{in out}} parameters (Ada 2012)}
@example
check parameter_declarations (out_parameters,    max 0, function);
check parameter_declarations (in_out_parameters, max 0, function);
@end example

@rule{Short circuit forms should be preferred over corresponding logical operators}
@example
Use_Short_Circuit: search expressions (and, or);
@end example

@rule{Aggregates should be used for full assignments to structured variables, unless it is a record with a single component}
@example
check multiple_assignments (groupable, given 2, ratio 100);
@end example

@rule{All loops that contain exit statements must be named, and the name must be given in the exit statement}
@example
check statements (unnamed_loop_exited);
check statements (unnamed_exit);
@end example

@rule{All type names must start with ``T_''}
@example
check naming_convention (type, "^T_");
@end example

@rule{All program units must repeat their name after the ``end''}
@example
check style (no_closing_name);
@end example

@rule{Pragma Suppress is not allowed}
@example
check pragmas (suppress);
@end example

@rule{Ada tasking must not be used}
@example
check declarations (task);
@end example

@rule{``='' and ``/='' shall not be used between real types}
@example
check expressions (real_equality);
@end example

@rule{All tasks must provide an exception handler that calls ``Failure'' in
the case of an unhandled exception}
@example
check exception_propagation (task);
check silent_exceptions (failure);
@end example

@rule{Unchecked_Conversion shall not be used}
@example
check entities (ada.unchecked_conversion);
@end example

@rule{No global variable shall be declared in the visible part of a package
specification}
@example
check usage (variable, from_spec);
@end example

@rule{Predefined numeric types of the language shall not be used}
@example
check entities (standard.Integer,
                standard.short_integer,
                standard.long_integer,
                standard.Float,
                standard.short_float,
                standard.long_float);
@end example

@rule{Access to subprograms shall not be used}
@example
check declarations (access_to_sp);
@end example

@rule{Abort statements shall not be used}
@example
check statements (abort);
@end example

@rule{There shall be only one instantiation of
Ada.Numerics.Generic_Elementary_Functions for each floating point type}
@example
-- Put a --##RULE LINE OFF GEF
-- for the one which is allowed
GEF: check Instantiations (Ada.Numerics.Generic_Elementary_Functions);
@end example

@rule{A local item shall not hide an outer one with the same name}
@example
check Local_Hiding;
@end example

@rule{There shall be no IOs in exception handlers}
@example
check entity_inside_exception (ada.Text_IO.put, ada.Text_IO.put_line,
                               ada.Text_IO.get, ada.Text_IO.get_line);
@end example
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:
@example
check entity_inside_exception (all get,      all put,
                               all get_line, all put_line);
@end example
This will check that no entity with the corresponding names appear in
exception handlers.

@rule{Exceptions shall not be used}
@example
No_Exception: check declarations (exception, handlers);
No_Exception: check statements (raise);
No_Exception: check entities (Ada.Exceptions);
@end example

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 @code{Ada.Exceptions}.

@rule{No procedure exported to C shall propagate exceptions}
@example
check exception_propagation (interface, C);
@end example

@rule{There shall be no Unchecked_Conversion to or from Address}
@example
check instantiations (ada.unchecked_conversion, system.address);
check instantiations (ada.unchecked_conversion, <>, system.address);
@end example

@rule{There shall be no use clause except for Text_IO}
@example
check use_clauses(ada.text_IO);
@end example

@rule{Use explicit list of values in case statements rather than ``when others''if the ``when others'' would cover less than 10 values}
@example
check Case_Statement(min_others_span, 10);
@end example

@rule{If a block is more than 20 lines long, it must be named}
@example
check Max_Size(unnamed_block, 20);
@end example

@rule{Exceptions shall not be handled except by main program}
@example
check declaration (handlers)
@end example
This check will be disabled for the exception handler of the main program.

@rule{Each unit has a header starting with a fixed format, and must contain at least 10 lines of comments}
@example
check header_comments (model, "header.txt");
check header_comments (minimum, 10);
@end example
The file @code{header.txt} contains the required header (as regexps), like:
@example
^--*@{50@}$
^-- This is a header$
@end example

@node Rules that need manual inspection,  , Automatically checkable rules, Examples of using AdaControl for common programming rules
@section Rules that need manual inspection
Below are examples of rules that require manual inspection, but where
AdaControl can be used to identify suspicious areas.

@rule{All usages of the 'ADDRESS attribute shall be justified and documented}
@example
search entities (all 'address);
@end example

@rule{Specifying an address for a variable shall be restricted to hardware interfacing}
@example
search representation_clauses(address);
@end example

@rule{There shall be no memory leakage}
@example
search Allocators;
@end example
This rule identifies all allocations, and thus can be used to check
that all allocated elements are properly deallocated.

@node Specifying an Ada entity name, Syntax of regular expressions, Examples of using AdaControl for common programming rules, Top
@appendix Specifying an Ada entity name

@menu
* General syntax::
* Overloaded names::
* Enumeration literals::
* Operators::
* Attributes::
* Anonymous constructs and extended return statements::
* Record and protected types components::
* Formals of access to subprogram types::
* Limitation::
@end menu

@node General syntax, Overloaded names, Specifying an Ada entity name, Specifying an Ada entity name
@section General syntax
Many rules can take Ada entities as parameters. Each time a rule uses
the category <entity>, it refers to an Ada entity that can be
specified with the following syntax:
@example
<entity> ::= <full_name> | "all" <simple_name> | "all" <attribute>
@end example
@code{<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 @code{Put_Line} must be given as
@code{Ada.Text_IO.Put_Line}, not as
@code{Text_IO.Put_Line}. Predefined elements (@code{Integer},
@code{Constraint_Error}) must be given in the form
@code{Standard.Integer} or @code{Standard.Constraint_Error}, since
they are logically declared in the package @code{Standard}.

@code{<simple_name>} is a single identifier, possibly followed by
overloading information. No qualification is allowed.

@code{<Attribute>} is an attribute name, including the quote. No
overloading information is allowed.

@code{<full_name>} designates a single entity or several overloaded
entities declared in the same place (as identified by the prefix),
while @code{all <simple_name>} designates all identifiers with the
given name in the program, irrespectively of where they
appear. @code{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. @xref{pfni}. If you are using GPS with AdaControl
plug-ins, it can be accessed directly from the contextual
menu. @xref{Contextual menu}.

@node Overloaded names, Enumeration literals, General syntax, Specifying an Ada entity name
@section Overloaded names
In Ada, names can be overloaded. This means that you can have several
procedures @code{P} in package @code{ Pack}, if they differ by the
types of the parameters. If you just give the name @code{Pack.P} as
the <entity>, the corresponding rule will be applied to all
elements named @code{P} from package @code{Pack}. If you want to
distinguish between overloaded names, you can specify a profile after
the element's name. A profile has the syntax:

@example
"@{" [ ["access"] <type-name>
     @{ ";" ["access"] <type-name> @} ]
     ["return" <type-name>] "@}"
@end example

You must specify the @i{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 @code{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
@code{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 @code{T} declared in
package @code{Pack}, you must specify it as @code{Pack.T}. As a
convenience, the @code{Standard.} is optional for predefined types, so
you can write @code{Standard.Integer} as @code{Integer}. There is no
ambiguity, since a type is always declared within some construct. Note
that omitting @code{Standard} works only for @i{types} that are part
of the profile used to distinguish between overloaded Ada entities but
that the @i{Ada entity name} must always contain Standard if it is a
predefined element.

Overloaded names can be also be used with the @code{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
@example
@b{procedure} P @b{is}
   @b{procedure} Q (I : Integer) @b{is}
      ...
   @b{end} Q;
   @b{procedure} Q (F : Float) @b{is}
      ...
   @b{end} Q;
@b{begin}
   ...
@b{end} P;
@end example

If you want to distinguish between the two procedures @code{Q}, you
must specify them as @code{P@{@}.Q@{Integer@}} and
@code{P@{@}.Q@{Float@}} (note the @code{P@{@}} which specifies an
overloaded name for a procedure @code{P} without parameters).

The names of entities which can not be overloaded (like package,
exception, @dots{}) must not  be suffixed by braces
(e.g. @code{Ada.Text_IO.Put_Line@{Standard.String@}}).

@node Enumeration literals, Operators, Overloaded names, Specifying an Ada entity name
@section Enumeration literals
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:
@example
@b{package} Pack @b{is}
   @b{type} T1 @b{is} (A, B);
   @b{type} T2 @b{is} (B, C);
@b{end} Pack;
@end example

Ada entities names are:
@itemize
@item
@code{Pack.B@{return Pack.T1@}}
@item
@code{Pack.B@{return Pack.T2@}}
@end itemize

@node Operators, Attributes, Enumeration literals, Specifying an Ada entity name
@section Operators
AdaControl handles operators (i.e. functions like @code{"+"})
correctly. Of course, you must specify such operations using normal
Ada syntax: if you define the integer type @code{T} in package
@code{Pack}, an overloaded name for the addition would be
@code{Pack."+"@{Pack.T; Pack.T return Pack.T@}}.

@node Attributes, Anonymous constructs and extended return statements, Operators, Specifying an Ada entity name
@section Attributes
It is also possible to designate attributes of entities, using the
normal notation (i.e. @code{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:

@example
@b{procedure} P (I : Integer) @b{is}
   @b{type} T @b{is} @b{range} 1 .. 10;
@b{begin}
   ...
@b{end} P;
@end example

You can designate the @code{'Image} attribute for type @code{T} as
@code{P@{Standard.Integer@}.T'Image} (the profile of the @code{'Image}
function is not given, as would be necessary for a normal function).

To designate all occurrences of an attribute, use @code{@b{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
@code{type'Attr} (i.e. the keyword ``type'' is put in front of the
quote).

@code{@b{all}} may be used in place of an attribute name to mean ``any
attribute''. See examples below.

@example
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
@end example

@node Anonymous constructs and extended return statements, Record and protected types components, Attributes, Specifying an Ada entity name
@section Anonymous constructs and extended return statements
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
@code{_anonymous_}. Therefore if you have the following program:
@example
@b{procedure} P @b{is}
@b{begin}
   @b{for} I @b{in} 1..10 @b{loop}
      @b{declare}
         J : Integer;
      @b{begin}
         ...
      @b{end};
   @b{end} @b{loop};
@b{end} P;
@end example
You can refer to @code{I} as @code{P._anonymous_.I}, and to @code{J}
as @code{P._anonymous_._anonymous_.J}.

Similarly, an extended return statement is considered ``named'' @code{return}.
 Therefore if you have the following program:
@example
@b{function} F @b{return} Integer @b{is}
   I : Integer;
@b{begin}
   @b{return} I : Integer @b{do}
      ...
   @b{end} @b{return};
@b{end} F;
@end example
You can refer to the @code{I} declared in @code{F} as @code{F.I}, and
to the return object @code{I} as @code{F.return.I}.

@node Record and protected types components, Formals of access to subprogram types, Anonymous constructs and extended return statements, Specifying an Ada entity name
@section Record and protected types components
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:
@example
@b{procedure} P @b{is}
   @b{type} T @b{is}
      @b{record}
         Name : Integer;
      @b{end} @b{record};
   ...
@end example

The Ada entity name is @code{P.T.Name}.

@node Formals of access to subprogram types, Limitation, Record and protected types components, Specifying an Ada entity name
@section Formals of access to subprogram types
Similarly, you can designate the formal of an access to subprogram
type by prefixing it by the access type. For example, given:
@example
@b{procedure} P @b{is}
   @b{type} T @b{is} @b{access} @b{procedure} (X : Integer);
   ...
@end example

The Ada entity name of the formal is @code{P.T.X}.

@node Limitation,  , Formals of access to subprogram types, Specifying an Ada entity name
@section Limitation
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.
@example
-- 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."<");
@end example

@node Syntax of regular expressions, Non upward-compatible changes, Specifying an Ada entity name, Top
@appendix Syntax of regular expressions
The following syntax gives the complete definition of regular
expressions, as used by several rules.  It is taken from the
specification of the package @code{gnat.regpat}, where additional
information is available.

@example
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)
@end example

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:
@example
 regexp="<.*>"   string="<h1>title</h1>"   matches="<h1>title</h1>"
 regexp="<.*?>"  string="<h1>title</h1>"   matches="<h1>"
@end example

'@{' 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
@code{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.

@node  Non upward-compatible changes,  , Syntax of regular expressions, Top
@appendix Non upward-compatible changes
This chapter is intended to users of a previous version of AdaControl,
who want to migrate rule 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.

@section Migrating from 1.17r3
@subsection Statements
The subrules @code{dispatching_call} and @code{redispatching_call} do
not control @i{function} calls anymore, since these are controlled (more
appropriately) by subrules of the @code{expressions} rule. In short, change:
@example
check statements (dispatching_call, redispatching_call);
@end example
to:
@example
check statements  (dispatching_call, redispatching_call);
check expressions (dispatching_function_call,
                   redispatching_function_call);
@end example

The subrule @code{raise_nonpublic} does not control any more the
raising of exceptions declared in visible parts of packages other than
the one that contains the @code{@b{raise}} statement; these are now
controlled by the subrule @code{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 @code{@b{raise}} statement.

@subsection Use of command line options -r and -s
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 @ref{Input units} and @ref{Generating a
units list}.

@section Migrating from 1.16r11
@subsection Declarations, Entities, Instantiations
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:
@example
check declarations (nested procedure);
@end example
to:
@example
check declarations (not library procedure);
@end example

@section Migrating from 1.15r5
@subsection Array_Declarations
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.

@subsection Multiple_Assignments
Due to new functionalities, and expecting more in the future, the rule
has been renamed to ``Assignments''.

@subsection No_Operator_Usage
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:
@example
-- (1)
check no_operator_usage (none);

-- (2)
check no_operator_usage (logical);

-- (3)
check no_operator_usage (none, logical)
                     -- or no parameters
@end example
to:
@example
-- (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);
@end example

@subsection Object_Declarations
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:
@example
count object_declarations (min_integer_span, all 8);
@end example
to:
@example
count object_declarations (min_integer_span, 8);
@end example

@subsection Statements
The subrule ``exit'' was documented as controlling all exit
statements, but it did not report exits from @code{@b{for}} and
@code{@b{while}} loops if ``exit_for_loop'' (respectively
``exit_while_loop'') was also specified. It now behaves as documented,
i.e. it controls all @code{@b{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.

@subsection Style
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:
@example
check style (parameter_association, call, 1);
@end example
to:
@example
check parameter_associations (all, 1, call);
@end example

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:
@example
check style (parameter_order, in defaulted_in, out in_out);
@end example
to:
@example
check style (parameter_order, in | defaulted_in, out | in_out);
@end example

@section Migrating from 1.14r9
@subsection Local_Hiding
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:
@example
check local_hiding (strict, overloading);
@end example
to:
@example
check local_hiding (strict);
check local_hiding (overloading);
@end example
The special subrule ``overloading_short'' has been replaced by a rule
variable to choose the report format.  Change:
@example
check local_hiding (overloading_short);
@end example
to:
@example
set local_hiding.overloading_report compact;
check local_hiding (overloading);
@end example

@subsection Max_Nesting
The value given is now the @i{nesting} level (consistent with the rule name),
no more the maximum @i{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:
@example
check Max_Nesting (5);
@end example
to:
@example
check Max_Nesting (4);
@end example

@subsection Parameter_Declarations
The subrules have been generalized, using the same syntax for bounds
as other rules. Change:
@example
check parameter_declarations (min_parameters, 1);
check parameter_declarations (max_parameters, 5);
check parameter_declarations (max_defaulted_parameters, 3);
@end example
to:
@example
check parameter_declarations (all_parameters, min 1, max 5);
check parameter_declarations (defaulted_parameters, max 3);
@end example

@section Migrating from 1.11r4
@subsection Expressions
The subrule @code{Real_Equality} does not control user-defined
equality operators any more. This is intended to be more of an
improvement than an incompatibily.

@subsection Special_Comments
Since the number of subrules is growing, and do not only address `special''
comments, this rule has been renamed to ``comments''.

@section Migrating from 1.10r10
@subsection GPS integration
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.

@subsection Representation_Clauses
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:
@example
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);
@end example
to:
@example
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);
@end example

@section Migrating from 1.9r4
@subsection Array_Declarations
The subrule ``Max_Length'' has been changed to ``Length'', with the possibility to specify both min and max
values. Change:
@example
check array_declarations (max_length, 100);
@end example
to:
@example
check array_declarations (length, max 100);
@end example

@subsection Declarations
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:
@example
check declarations (initialized_record_field,
                    uninitialized_record_field,
                    initialized_protected_field,
                    uninitialized_protected_field);
@end example
to:
@example
check declarations (initialized_record_component,
                    uninitialized_record_component,
                    initialized_protected_component,
                    uninitialized_protected_component);
@end example

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:
@example
check declarations (aliased);
@end example
to:
@example
check declarations (aliased_constant, aliased_variable);
@end example

@subsection Default_Parameter
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:
@example
My_label : check default_parameter (all, ...);
@end example
to:
@example
My_label : check default_parameter (calls, ...),
           check default_parameter (instantiations, ...);
@end example

@subsection Improper_Initialization
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:
@example
check improper_initialization (variable);
@end example
to:
@example
check improper_initialization (package variable);
@end example

@section Migrating from 1.8r8
@subsection CSV(X) format
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.

@subsection Default_Parameter
Due to the introduction of the ``positional'' keyword, ``not used'' is
now spelled ``not_used''.  Change:
@example
check default_parameter (proc, param, not used);
@end example
to:
@example
check default_parameter (proc, param, not_used);
@end example

@subsection Other_Dependencies
This rule has been changed into a subrule of the (new) rule
``Dependencies''. Change:
@example
check Other_Dependencies (pack1, pack2);
@end example
to:
@example
check Dependencies (others, pack1, pack2);
@end example

@subsection Special_Comments
Due to the introduction of another subrule, add ``pattern'' as the first parameter
to the rule. Change:
@example
check Special_Comments ("TBSL");
@end example
to:
@example
check Special_Comments (pattern, "TBSL");
@end example

@subsection Statements
The ``raise'' subrule now reports all occurrences of the @code{@b{raise}}
statement, even if another control is applicable to the same statement.

The ``reraise'' subrule now reports calls to
@code{Ada.Exceptions.Reraise_Occurrence}.

The ``raise_standard'' subrule now reports exceptions raised by calls to
@code{Ada.Exceptions.Raise_Exception}.

@section Migrating from 1.7r9
@subsection Case_Statement
This rule now allows the specification of both min and max values for
each subrule. Subrule names have been changed accordingly. Change:
@example
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);
@end example
to:
@example
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);
@end example

@subsection Max_Parameters
This rule has been changed into a subrule of the (new) rule
``Parameter_Declarations''. Change:
@example
check Max_Parameters (10);
@end example
to:
@example
check Parameter_Declarations (Max_Parameters, 10);
@end example

@section Migrating from 1.6r8
@subsection ``message'' command
The message is now syntactically a string, and must always be enclosed
in double quotes (quotes were optional in previous versions).

@subsection ``source'' command
If a ``source'' command is given in a rules 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.

@subsection Control_Characters
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:
@example
check control_characters;
@end example
to:
@example
check characters (control);
@end example

@subsection If_For_Case
This rule has been changed into a subrule of the (new) rule
``simplifiable_statements''. Change:
@example
check if_for_case;
@end example
to:
@example
check simplifiable_statements (if_for_case);
@end example

@subsection Instantiations
The rule does not print the number of instantiations any more, since the same
effect can be achieved with the ``count'' control kind.

@subsection Local_Instantiation
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:
@example
R1: check Local_Instantiation;
R2: search Local_Instantiation (Ada.Unchecked_Conversion);
@end example
to:
@example
R1: check  declarations   (local instantiation);
R2: search Instantiations (local Ada.Unchecked_Conversion);
@end example

@subsection Naming_Convention
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:
@example
check naming_convention (object, local "^L_", global "^G_");
@end example
to:
@example
check naming_convention (local object, "^L_");
check naming_convention (global object, "^G_");
@end example

@subsection No_Safe_Initialization
The name of this rule has been changed to ``improper_initialization'',
since it now controls other cases of improper initialization.

@subsection Special_Comments
Quotes are no more optional around patterns.

@subsection Statements
Two subrules of this rule have migrated to the new rule
``simplifiable_statements'' (with slightly different names). Change:
@example
check statements (unnecessary_null);
check statements (while_true);
@end example
to:
@example
check simplifiable_statements (null);
check simplifiable_statements (loop);
@end example

@section Migrating from 1.5r24
@subsection Declarations
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:
@example
check declarations (nested_generic_function);
@end example
to:
@example
check declarations (nested generic_function);
@end example

@subsection Naming_Convention
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:
@example
check naming_convention (variable, global "^G_");
check naming_convention (package, any "^Pack_");
@end example
to:
@example
check naming_convention (global variable, "^G_");
check naming_convention (package, "^Pack_");
@end example

@subsection Non_Static_Constraint
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:
@example
check non_static_constraint (index, discriminant);
@end example
to:
@example
check non_static (index_constraint, discriminant_constraint);
@end example

@subsection Positional_Parameters
This rule has been renamed to @code{Insufficient_Parameters}, since it does no more
handle the ``maximum'' subrule. Controlling positional parameters according to their number
is now done by the rule @code{style (positional_association)}. Change:
@example
check positional_parameters (maximum, 3);
check positional_parameters (insufficient, 2, Boolean);
@end example
to:
@example
check style (positional_association, call, 3);
check insufficient_parameters (2, Boolean);
@end example

@subsection Real_Operator
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:
@example
check Real_Operators;
@end example
to:
@example
check expressions (Real_Equality);
@end example

@subsection Style
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:
@example
check style (exposed_literal, 0, 1, 0.0, 1.0);
@end example
you must change it to:
@example
check style (exposed_literal, integer, 0, 1)
check style (exposed_literal, real, 0.0, 1.0);
@end example

The ``aggregate'' parameter of the subrule ``positional_association''
has been split into ``array_aggregate'' and ``record_aggregate''. For example,
change:
@example
check style (positional_association, aggregate);
@end example
into:
@example
check style (positional_association, record_aggregate, array_aggregate);
@end example


@section Migrating from 1.4r20
@subsection GPS integration
The XML file used to describe AdaControl features to GPS used to be
called @code{adactl.xml}. It is now called @code{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 @code{adactl.xml} file from the GPS
plug-ins directory before installing the new version.

@subsection Declarations
The parameters ``access'' and ``access_subprogram'' have been changed
to ``access_type'' and ``access_subprogram_type'', for consistency
with the new parameters.

@subsection Header_Comments
A keyword has been added to specify the required number of comment lines.
Change:
@example
check Header_Comments (10);
@end example
to:
@example
check Header_Comments (minimum, 10);
@end example

@subsection No_Closing_Name
This rule is now part of the ``style'' rule. Change:
@example
check|search|count No_Closing_Name;
@end example
to:
@example
check|search|count Style (No_Closing_Name);
@end example

@subsection Specification_Objects
This rule is now part of the ``usage'' rule. Change:
@example
check|search|count Specification_Objects (<parameters>);
@end example
to:
@example
check|search|count Usage (Object, From_Spec, <parameters>);
@end example

@subsection Statement
Name changed from ``statement'' to ``statements'' (added an 's'), to
be consistent with other rules.

@subsection When_Others_Null
This rule is now part of the ``statements'' rule. Change:
@example
check|search|count When_Others_Null (case);
check|search|count When_Others_Null (exception);
@end example
to:
@example
check|search|count Statements (case_others_null);
check|search|count Statements (exception_others_null);
@end example
@bye