Ada '83 Language Reference Manual

Copyright 1980, 1982, 1983 owned by the United States Government. Direct reproduction and usage requests to the Ada Information Clearinghouse.

8.4. Use Clauses

A use clause achieves direct visibility of declarations that appear in the visible parts of named packages.

    use_clause ::= use package_name {, package_name}; 

For each use clause, there is a certain region of text called the scope of the use clause. This region starts immediately after the use clause. If a use clause is a declarative item of some declarative region, the scope of the clause extends to the end of the declarative region. If a use clause occurs within a context clause of a compilation unit, the scope of the use clause extends to the end of the declarative region associated with the compilation unit.

In order to define which declarations are made directly visible at a given place by use clauses, consider the set of packages named by all use clauses whose scopes enclose this place, omitting from this set any packages that enclose this place. A declaration that can be made directly visible by a use clause (a potentially visible declaration) is any declaration that occurs immediately within the visible part of a package of the set. A potentially visible declaration is actually made directly visible except in the following two cases:

• A potentially visible declaration is not made directly visible if the place considered is within the immediate scope of a homograph of the declaration.
  
  
• Potentially visible declarations that have the same identifier are not made directly visible unless each of them is either an enumeration literal specification or the declaration of a subprogram (by a subprogram declaration, a renaming declaration, a generic instantiation, or an implicit declaration).

The elaboration of a use clause has no other effect.

Note:

The above rules guarantee that a declaration that is made directly visible by a use clause cannot hide an otherwise directly visible declaration. The above rules are formulated in terms of the set of packages named by use clauses.

Consequently, the following lines of text all have the same effect (assuming only one package P).

    use P;
    use P; use P, P; 

Example of conflicting names in two packages:

    procedure R is
       package TRAFFIC is
          type COLOR is (RED, AMBER, GREEN);
          ...
       end TRAFFIC; 

       package WATER_COLORS is                    
          type COLOR is (WHITE, RED, YELLOW, GREEN, BLUE, BROWN, BLACK);
          ...
       end WATER_COLORS; 

     use TRAFFIC;       --  COLOR, RED, AMBER, and GREEN are directly visible
     use WATER_COLORS;  --  two homographs of GREEN are directly visible
                        --  but COLOR is no longer directly visible

     subtype LIGHT is TRAFFIC.COLOR;      -- Subtypes are used to resolve
     subtype SHADE is WATER_COLORS.COLOR; -- the conflicting type name COLOR

       SIGNAL : LIGHT;
       PAINT  : SHADE;
    begin
       SIGNAL := GREEN;  --  that of TRAFFIC
       PAINT  := GREEN;  --  that of WATER_COLORS
    end R; 

Example of name identification with a use clause:

       package D is
          T, U, V : BOOLEAN;
       end D; 

       procedure P is
          package E is
             B, W, V : INTEGER;
          end E; 

          procedure Q is
             T, X : REAL;
             use D, E;
          begin
             --  the name T means Q.T, not D.T
             --  the name U means D.U
             --  the name B means E.B
             --  the name W means E.W
             --  the name X means Q.X
             --  the name V is illegal : either D.V or E.V must be used
             ...  
          end Q;
       begin
          ...
       end P;                                                                       

References: compilation unit, context clause, declaration, declarative item, declarative region, direct visibility, elaboration, and 3.9, elaboration has no other effect, enumeration literal specification, extends, hiding, homograph, identifier, immediate scope, name, occur immediately within, package, scope, subprogram declaration, visible part.

Rationale references: 11.3.2 Naming Conventions: Expanded Names and Use Clauses

Style Guide references: 5.6.9 Blocks, 5.7.1 The Use Clause, 5.7.2 The Renames Clause

Address any questions or comments to adainfo@sw-eng.falls-church.va.us.