Pragma Obsolescent

Syntax:

     pragma Obsolescent
       [(Entity => NAME [, static_string_EXPRESSION [,Ada_05]])];

This pragma can occur immediately following a declaration of an entity, including the case of a record component, and usually the Entity name must match the name of the entity declared by this declaration. Alternatively, the pragma can immediately follow an enumeration type declaration, where the entity argument names one of the enumeration literals.

This pragma is used to indicate that the named entity is considered obsolescent and should not be used. Typically this is used when an API must be modified by eventually removing or modifying existing subprograms or other entities. The pragma can be used at an intermediate stage when the entity is still present, but will be removed later.

The effect of this pragma is to output a warning message on a call to a program thus marked that the subprogram is obsolescent if the appropriate warning option in the compiler is activated. If the string parameter is present, then a second warning message is given containing this text. In addition, a call to such a program is considered a violation of pragma Restrictions (No_Obsolescent_Features).

This pragma can also be used as a program unit pragma for a package, in which case the entity name is the name of the package, and the pragma indicates that the entire package is considered obsolescent. In this case a client with'ing such a package violates the restriction, and the with statement is flagged with warnings if the warning option is set.

If the optional third parameter is present (which must be exactly the identifier Ada_05, no other argument is allowed), then the indication of obsolescence applies only when compiling in Ada 2005 mode. This is primarily intended for dealing with the situations in the predefined library where subprograms or packages have become defined as obsolescent in Ada 2005 (e.g. in Ada.Characters.Handling), but may be used anywhere.

The following examples show typical uses of this pragma:

     package p is
        pragma Obsolescent
          (Entity => p, "use pp instead of p");
     end p;
     
     package q is
        procedure q2;
        pragma Obsolescent
          (Entity => q2, "use q2new instead");
     
        type R is new integer;
        pragma Obsolescent
          (Entity => R, "use RR in Ada 2005", Ada_05);
     
        type M is record
           F1 : Integer;
           F2 : Integer;
           pragma Obsolescent (Entity => F2);
           F3 : Integer;
        end record;
     
        type E is (a, bc, 'd', quack);
        pragma Obsolescent (Entity => bc)
        pragma Obsolescent (Entity => 'd')
     
        function "+"
          (a, b : character) return character;
        pragma Obsolescent (Entity => "+");
     end;

In an earlier version of GNAT, the Entity parameter was not required, and this form is still accepted for compatibility purposes. If the Entity parameter is omitted, then the pragma applies to the declaration immediately preceding the pragma (this form cannot be used for the enumeration literal case).