Style Checking (GNAT User’s Guide for Native Platforms)

#### 4.3.7 Style Checking ¶

The `-gnaty` switch causes the compiler to enforce specified style rules. A limited set of style rules has been used in writing the GNAT sources themselves. This switch allows user programs to activate all or some of these checks. If the source program fails a specified style check, an appropriate message is given, preceded by the character sequence ‘(style)’. This message does not prevent successful compilation (unless the `-gnatwe` switch is used).

Note that this is by no means intended to be a general facility for checking arbitrary coding standards. It is simply an embedding of the style rules we have chosen for the GNAT sources. If you are starting a project which does not have established style standards, you may find it useful to adopt the entire set of GNAT coding standards, or some subset of them.

The string `x` is a sequence of letters or digits indicating the particular style checks to be performed. The following checks are defined:

`-gnaty0`

  ‘Specify indentation level.’

  If a digit from 1-9 appears in the string after `-gnaty` then proper indentation is checked, with the digit indicating the indentation level required. A value of zero turns off this style check. The rule checks that the following constructs start on a column that is one plus a multiple of the alignment level:

  - beginnings of declarations (except record component declarations) and statements;
  - beginnings of the structural components of compound statements;
  - `end` keyword that completes the declaration of a program unit declaration or body or that completes a compound statement.

  Full line comments must be aligned with the `--` starting on a column that is one plus a multiple of the alignment level, or they may be aligned the same way as the following non-blank line (this is useful when full line comments appear in the middle of a statement), or they may be aligned with the source line on the previous non-blank line.

`-gnatya`

  ‘Check attribute casing.’

  Attribute names, including the case of keywords such as `digits` used as attributes names, must be written in mixed case, that is, the initial letter and any letter following an underscore must be uppercase. All other letters must be lowercase.

`-gnatyA`

  ‘Use of array index numbers in array attributes.’

  When using the array attributes First, Last, Range, or Length, the index number must be omitted for one-dimensional arrays and is required for multi-dimensional arrays.

`-gnatyb`

  ‘Blanks not allowed at statement end.’

  Trailing blanks are not allowed at the end of statements. The purpose of this rule, together with h (no horizontal tabs), is to enforce a canonical format for the use of blanks to separate source tokens.

`-gnatyB`

  ‘Check Boolean operators.’

  The use of AND/OR operators is not permitted except in the cases of modular operands, array operands, and simple stand-alone boolean variables or boolean constants. In all other cases `and then`/or else are required.

`-gnatyc`

  ‘Check comments, double space.’

  Comments must meet the following set of rules:

  - The `--` that starts the column must either start in column one, or else at least one blank must precede this sequence.
  - Comments that follow other tokens on a line must have at least one blank following the `--` at the start of the comment.
  - Full line comments must have at least two blanks following the `--` that starts the comment, with the following exceptions.
  - A line consisting only of the `--` characters, possibly preceded by blanks is permitted.
  - A comment starting with `--x` where `x` is a special character is permitted. This allows proper processing of the output from specialized tools such as `gnatprep` (where `--!` is used) and in earlier versions of the SPARK annotation language (where `--#` is used). For the purposes of this rule, a special character is defined as being in one of the ASCII ranges `16#21#...16#2F#` or `16#3A#...16#3F#`. Note that this usage is not permitted in GNAT implementation units (i.e., when `-gnatg` is used).
  - A line consisting entirely of minus signs, possibly preceded by blanks, is permitted. This allows the construction of box comments where lines of minus signs are used to form the top and bottom of the box.
  - A comment that starts and ends with `--` is permitted as long as at least one blank follows the initial `--`. Together with the preceding rule, this allows the construction of box comments, as shown in the following example:

        ---------------------------
        -- This is a box comment --
        -- with two text lines.  --
        ---------------------------

`-gnatyC`

  ‘Check comments, single space.’

  This is identical to `c` except that only one space is required following the `--` of a comment instead of two.

`-gnatyd`

  ‘Check no DOS line terminators present.’

  All lines must be terminated by a single ASCII.LF character (in particular the DOS line terminator sequence CR/LF is not allowed).

`-gnatyD`

  ‘Check declared identifiers in mixed case.’

  Declared identifiers must be in mixed case, as in This_Is_An_Identifier. Use -gnatyr in addition to ensure that references match declarations.

`-gnatye`

  ‘Check end/exit labels.’

  Optional labels on `end` statements ending subprograms and on `exit` statements exiting named loops, are required to be present.

`-gnatyf`

  ‘No form feeds or vertical tabs.’

  Neither form feeds nor vertical tab characters are permitted in the source text.

`-gnatyg`

  ‘GNAT style mode.’

  The set of style check switches is set to match that used by the GNAT sources. This may be useful when developing code that is eventually intended to be incorporated into GNAT. Currently this is equivalent to `-gnatyydISuxz`) but additional style switches may be added to this set in the future without advance notice.

`-gnatyh`

  ‘No horizontal tabs.’

  Horizontal tab characters are not permitted in the source text. Together with the b (no blanks at end of line) check, this enforces a canonical form for the use of blanks to separate source tokens.

`-gnatyi`

  ‘Check if-then layout.’

  The keyword `then` must appear either on the same line as corresponding `if`, or on a line on its own, lined up under the `if`.

`-gnatyI`

  ‘check mode IN keywords.’

  Mode `in` (the default mode) is not allowed to be given explicitly. `in out` is fine, but not `in` on its own.

`-gnatyk`

  ‘Check keyword casing.’

  All keywords must be in lower case (with the exception of keywords such as `digits` used as attribute names to which this check does not apply). A single error is reported for each line breaking this rule even if multiple casing issues exist on a same line.

`-gnatyl`

  ‘Check layout.’

  Layout of statement and declaration constructs must follow the recommendations in the Ada Reference Manual, as indicated by the form of the syntax rules. For example an `else` keyword must be lined up with the corresponding `if` keyword.

  There are two respects in which the style rule enforced by this check option are more liberal than those in the Ada Reference Manual. First in the case of record declarations, it is permissible to put the `record` keyword on the same line as the `type` keyword, and then the `end` in `end record` must line up under `type`. This is also permitted when the type declaration is split on two lines. For example, any of the following three layouts is acceptable:

      type q is record
         a : integer;
         b : integer;
      end record;

      type q is
         record
            a : integer;
            b : integer;
         end record;

      type q is
         record
            a : integer;
            b : integer;
      end record;

  Second, in the case of a block statement, a permitted alternative is to put the block label on the same line as the `declare` or `begin` keyword, and then line the `end` keyword up under the block label. For example both the following are permitted:

      Block : declare
         A : Integer := 3;
      begin
         Proc (A, A);
      end Block;

      Block :
         declare
            A : Integer := 3;
         begin
            Proc (A, A);
         end Block;

  The same alternative format is allowed for loops. For example, both of the following are permitted:

      Clear : while J < 10 loop
         A (J) := 0;
      end loop Clear;

      Clear :
         while J < 10 loop
            A (J) := 0;
         end loop Clear;

`-gnatyL`

  ‘Set maximum nesting level.’

  The maximum level of nesting of constructs (including subprograms, loops, blocks, packages, and conditionals) may not exceed the given value ‘nnn’. A value of zero disconnects this style check.

`-gnatym`

  ‘Check maximum line length.’

  The length of source lines must not exceed 79 characters, including any trailing blanks. The value of 79 allows convenient display on an 80 character wide device or window, allowing for possible special treatment of 80 character lines. Note that this count is of characters in the source text. This means that a tab character counts as one character in this count and a wide character sequence counts as a single character (however many bytes are needed in the encoding).

`-gnatyM`

  ‘Set maximum line length.’

  The length of lines must not exceed the given value ‘nnn’. The maximum value that can be specified is 32767. If neither style option for setting the line length is used, then the default is 255. This also controls the maximum length of lexical elements, where the only restriction is that they must fit on a single line.

`-gnatyn`

  ‘Check casing of entities in Standard.’

  Any identifier from Standard must be cased to match the presentation in the Ada Reference Manual (for example, `Integer` and `ASCII.NUL`).

`-gnatyN`

  ‘Turn off all style checks.’

  All style check options are turned off.

`-gnatyo`

  ‘Check order of subprogram bodies.’

  All subprogram bodies in a given scope (e.g., a package body) must be in alphabetical order. The ordering rule uses normal Ada rules for comparing strings, ignoring casing of letters, except that if there is a trailing numeric suffix, then the value of this suffix is used in the ordering (e.g., Junk2 comes before Junk10).

`-gnatyO`

  ‘Check that overriding subprograms are explicitly marked as such.’

  This applies to all subprograms of a derived type that override a primitive operation of the type, for both tagged and untagged types. In particular, the declaration of a primitive operation of a type extension that overrides an inherited operation must carry an overriding indicator. Another case is the declaration of a function that overrides a predefined operator (such as an equality operator).

`-gnatyp`

  ‘Check pragma casing.’

  Pragma names must be written in mixed case, that is, the initial letter and any letter following an underscore must be uppercase. All other letters must be lowercase. An exception is that SPARK_Mode is allowed as an alternative for Spark_Mode.

`-gnatyr`

  ‘Check references.’

  All identifier references must be cased in the same way as the corresponding declaration. No specific casing style is imposed on identifiers. The only requirement is for consistency of references with declarations.

`-gnatys`

  ‘Check separate specs.’

  Separate declarations (‘specs’) are required for subprograms (a body is not allowed to serve as its own declaration). The only exception is that parameterless library level procedures are not required to have a separate declaration. This exception covers the most frequent form of main program procedures.

`-gnatyS`

  ‘Check no statements after then/else.’

  No statements are allowed on the same line as a `then` or `else` keyword following the keyword in an `if` statement. `or else` and `and then` are not affected, and a special exception allows a pragma to appear after `else`.

`-gnatyt`

  ‘Check token spacing.’

  The following token spacing rules are enforced:

  - The keywords `abs` and `not` must be followed by a space.
  - The token `=>` must be surrounded by spaces.
  - The token `<>` must be preceded by a space or a left parenthesis.
  - Binary operators other than `**` must be surrounded by spaces. There is no restriction on the layout of the `**` binary operator.
  - Colon must be surrounded by spaces.
  - Colon-equal (assignment, initialization) must be surrounded by spaces.
  - Comma must be the first non-blank character on the line, or be immediately preceded by a non-blank character, and must be followed by a space.
  - If the token preceding a left parenthesis ends with a letter or digit, then a space must separate the two tokens.
  - If the token following a right parenthesis starts with a letter or digit, then a space must separate the two tokens.
  - A right parenthesis must either be the first non-blank character on a line, or it must be preceded by a non-blank character.
  - A semicolon must not be preceded by a space, and must not be followed by a non-blank character.
  - A unary plus or minus may not be followed by a space.
  - A vertical bar must be surrounded by spaces.

  Exactly one blank (and no other white space) must appear between a `not` token and a following `in` token.

`-gnatyu`

  ‘Check unnecessary blank lines.’

  Unnecessary blank lines are not allowed. A blank line is considered unnecessary if it appears at the end of the file, or if more than one blank line occurs in sequence.

`-gnatyx`

  ‘Check extra parentheses.’

  Unnecessary extra levels of parentheses (C-style) are not allowed around conditions (or selection expressions) in `if`, `while`, `case`, and `exit` statements, as well as part of ranges.

`-gnatyy`

  ‘Set all standard style check options.’

  This is equivalent to `gnaty3aAbcefhiklmnprst`, that is all checking options enabled with the exception of `-gnatyB`, `-gnatyd`, `-gnatyI`, `-gnatyLnnn`, `-gnatyo`, `-gnatyO`, `-gnatyS`, `-gnatyu`, and `-gnatyx`.

`-gnatyz`

  ‘Check extra parentheses (operator precedence).’

  Extra levels of parentheses that are not required by operator precedence rules are flagged. See also `-gnatyx`.

`-gnaty-`

  ‘Remove style check options.’

  This causes any subsequent options in the string to act as canceling the corresponding style check option. To cancel maximum nesting level control, use the `L` parameter without any integer value after that, because any digit following ‘-’ in the parameter string of the `-gnaty` option will be treated as canceling the indentation check. The same is true for the `M` parameter. `y` and `N` parameters are not allowed after ‘-’.

`-gnaty+`

  ‘Enable style check options.’

  This causes any subsequent options in the string to enable the corresponding style check option. That is, it cancels the effect of a previous -, if any.

In the above rules, appearing in column one is always permitted, that is, counts as meeting either a requirement for a required preceding space, or as meeting a requirement for no preceding space.

Appearing at the end of a line is also always permitted, that is, counts as meeting either a requirement for a following space, or as meeting a requirement for no following space.

If any of these style rules is violated, a message is generated giving details on the violation. The initial characters of such messages are always ‘(style)’. Note that these messages are treated as warning messages, so they normally do not prevent the generation of an object file. The `-gnatwe` switch can be used to treat warning messages, including style messages, as fatal errors.

The switch `-gnaty` on its own (that is not followed by any letters or digits) is equivalent to the use of `-gnatyy` as described above, that is all built-in standard style check options are enabled.

The switch `-gnatyN` clears any previously set style checks.