13.2.4 Name Casing

gnatpp always converts the usage occurrence of a (simple) name to the same casing as the corresponding defining identifier.

You control the casing for defining occurrences via the -n switch. With -nD (“as declared”, which is the default), defining occurrences appear exactly as in the source file where they are declared. The other values for this switch — -nU, -nL, -nM — result in upper, lower, or mixed case, respectively. If gnatpp changes the casing of a defining occurrence, it analogously changes the casing of all the usage occurrences of this name.

If the defining occurrence of a name is not in the source compilation unit currently being processed by gnatpp, the casing of each reference to this name is changed according to the value of the -n switch (subject to the dictionary file mechanism described below). Thus gnatpp acts as though the -n switch had affected the casing for the defining occurrence of the name.

Some names may need to be spelled with casing conventions that are not covered by the upper-, lower-, and mixed-case transformations. You can arrange correct casing by placing such names in a dictionary file, and then supplying a -D switch. The casing of names from dictionary files overrides any -n switch.

To handle the casing of Ada predefined names and the names from GNAT libraries, gnatpp assumes a default dictionary file. The name of each predefined entity is spelled with the same casing as is used for the entity in the Ada Reference Manual. The name of each entity in the GNAT libraries is spelled with the same casing as is used in the declaration of that entity.

The -D- switch suppresses the use of the default dictionary file. Instead, the casing for predefined and GNAT-defined names will be established by the -n switch or explicit dictionary files. For example, by default the names Ada.Text_IO and GNAT.OS_Lib will appear as just shown, even in the presence of a -nU switch. To ensure that even such names are rendered in uppercase, additionally supply the -D- switch (or else, less conveniently, place these names in upper case in a dictionary file).

A dictionary file is a plain text file; each line in this file can be either a blank line (containing only space characters and ASCII.HT characters), an Ada comment line, or the specification of exactly one casing schema.

A casing schema is a string that has the following syntax:

     

       casing_schema ::= identifier | [*]simple_identifier[*]
     
       simple_identifier ::= letter{letter_or_digit}
     

(The [] metanotation stands for an optional part; see Ada Reference Manual, Section 2.3) for the definition of the identifier lexical element and the letter_or_digit category).

The casing schema string can be followed by white space and/or an Ada-style comment; any amount of white space is allowed before the string.

If a dictionary file is passed as the value of a -Dfile switch then for every simple name and every identifier, gnatpp checks if the dictionary defines the casing for the name or for some of its parts (the term “subword” is used below to denote the part of a name which is delimited by “_” or by the beginning or end of the word and which does not contain any “_” inside):

• if the whole name is in the dictionary, gnatpp uses for this name the casing defined by the dictionary; no subwords are checked for this word
• for the first subword (that is, for the subword preceding the leftmost “_”), gnatpp checks if the dictionary contains the corresponding string of the form simple_identifier*, and if it does, the casing of this simple_identifier is used for this subword
• for the last subword (following the rightmost “_”) gnatpp checks if the dictionary contains the corresponding string of the form *simple_identifier, and if it does, the casing of this simple_identifier is used for this subword
• for every intermediate subword (surrounded by two'_') gnatpp checks if the dictionary contains the corresponding string of the form *simple_identifier*, and if it does, the casing of this simple_identifier is used for this subword
• if more than one dictionary file is passed as gnatpp switches, each dictionary adds new casing exceptions and overrides all the existing casing exceptions set by the previous dictionaries
• when gnatpp checks if the word or subword is in the dictionary, this check is not case sensitive

For example, suppose we have the following source to reformat:

     

     procedure test is
        name1 : integer := 1;
        name4_name3_name2 : integer := 2;
        name2_name3_name4 : Boolean;
        name1_var : Float;
     begin
        name2_name3_name4 := name4_name3_name2 > name1;
     end;
     

And suppose we have two dictionaries:

     

     dict1:
        NAME1
        *NaMe3*
        *NAME2
     
     
     

     dict2:
       *NAME3*
     

If gnatpp is called with the following switches:

     gnatpp -nM -D dict1 -D dict2 test.adb

then we will get the following name casing in the gnatpp output:

     

     procedure Test is
        NAME1             : Integer := 1;
        Name4_NAME3_NAME2 : integer := 2;
        Name2_NAME3_Name4 : Boolean;
        Name1_Var         : Float;
     begin
        Name2_NAME3_Name4 := Name4_NAME3_NAME2 > NAME1;
     end Test;