2.122 Pragma Obsolescent

Syntax:

pragma Obsolescent;

pragma Obsolescent (
  [Message =>] static_string_EXPRESSION
[,[Version =>] Ada_05]]);

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

This pragma can occur immediately following a declaration of an entity, including the case of a record component. If no Entity argument is present, then this declaration is the one to which the pragma applies. If an Entity parameter is present, it must either match the name of the entity in this declaration, or 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 reference to an entity thus marked that the subprogram is obsolescent if the appropriate warning option in the compiler is activated. If the Message parameter is present, then a second warning message is given containing this text. In addition, a reference to the entity is considered to be 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 withing such a package violates the restriction, and the with clause is flagged with warnings if the warning option is set.

If the Version 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 (p, Message => "use pp instead of p");
end p;

package q is
   procedure q2;
   pragma Obsolescent ("use q2new instead");

   type R is new integer;
   pragma Obsolescent
     (Entity  => R,
      Message => "use RR in Ada 2005",
      Version => Ada_05);

   type M is record
      F1 : Integer;
      F2 : Integer;
      pragma Obsolescent;
      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;

Note that, as for all pragmas, if you use a pragma argument identifier, then all subsequent parameters must also use a pragma argument identifier. So if you specify Entity => for the Entity argument, and a Message argument is present, it must be preceded by Message =>.