Annotated Ada Reference Manual — Legal Information
Contents   Index   References   Search   Previous   Next 

8.4 Use Clauses

1
[A use_package_clause achieves direct visibility of declarations that appear in the visible part of a package; a use_type_clause achieves direct visibility of the primitive operators of a type.] 

Language Design Principles

1.a
{equivalence of use_clauses and selected_components} If and only if the visibility rules allow P.A, "use P;" should make A directly visible (barring name conflicts). This means, for example, that child library units, and generic formals of a formal package whose formal_package_actual_part is (<>), should be made visible by a use_clause for the appropriate package.
1.b
{Beaujolais effect} The rules for use_clauses were carefully constructed to avoid so-called Beaujolais effects, where the addition or removal of a single use_clause, or a single declaration in a "use"d package, would change the meaning of a program from one legal interpretation to another. 

Syntax

2
use_clause ::= use_package_clause | use_type_clause
3
use_package_clause ::= use package_name {, package_name};
4
use_type_clause ::= use type subtype_mark {, subtype_mark};

Legality Rules

5/2
{AI95-00217-06} A package_name of a use_package_clause shall denote a nonlimited view of a package. 
5.a
Ramification: This includes formal packages.

Static Semantics

6
{scope (of a use_clause)} For each use_clause, there is a certain region of text called the scope of the use_clause. For a use_clause within a context_clause of a library_unit_declaration or library_unit_renaming_declaration, the scope is the entire declarative region of the declaration. For a use_clause within a context_clause of a body, the scope is the entire body [and any subunits (including multiply nested subunits). The scope does not include context_clauses themselves.]
7
For a use_clause immediately within a declarative region, the scope is the portion of the declarative region starting just after the use_clause and extending to the end of the declarative region. However, the scope of a use_clause in the private part of a library unit does not include the visible part of any public descendant of that library unit. 
7.a
Reason: The exception echoes the similar exception for “immediate scope (of a declaration)” (see 8.2). It makes use_clauses work like this: 
7.b
package P is
    type T is range 1..10;
end P;
7.c
with P;
package Parent is
private
    use P;
    X : T;
end Parent;
7.d
package Parent.Child is
    Y : T; -- Illegal!
    Z : P.T;
private
    W : T;
end Parent.Child;
7.e
The declaration of Y is illegal because the scope of the “use P” does not include that place, so T is not directly visible there. The declarations of X, Z, and W are legal. 
7.1/2
 {AI95-00217-06} A package is named in a use_package_clause if it is denoted by a package_name of that clause. A type is named in a use_type_clause if it is determined by a subtype_mark of that clause.{named (in a use clause)}
8/2
{AI95-00217-06} {potentially use-visible} For each package named in a use_package_clause whose scope encloses a place, each declaration that occurs immediately within the declarative region of the package is potentially use-visible at this place if the declaration is visible at this place. For each type T or T'Class named in a use_type_clause whose scope encloses a place, the declaration of each primitive operator of type T is potentially use-visible at this place if its declaration is visible at this place. 
8.a
Ramification: Primitive subprograms whose defining name is an identifier are not made potentially visible by a use_type_clause. A use_type_clause is only for operators.
8.b
The semantics described here should be similar to the semantics for expanded names given in 4.1.3, “Selected Components” so as to achieve the effect requested by the “principle of equivalence of use_clauses and selected_components.” Thus, child library units and generic formal parameters of a formal package are potentially use-visible when their enclosing package is use'd.
8.c
The "visible at that place" part implies that applying a use_clause to a parent unit does not make all of its children use-visible — only those that have been made visible by a with_clause. It also implies that we don't have to worry about hiding in the definition of "directly visible" — a declaration cannot be use-visible unless it is visible.
8.d
Note that "use type T'Class;" is equivalent to "use type T;", which helps avoid breaking the generic contract model. 
9
{use-visible} {visibility (use clause)} A declaration is use-visible if it is potentially use-visible, except in these naming-conflict cases:
10
A potentially use-visible declaration is not use-visible if the place considered is within the immediate scope of a homograph of the declaration.
11
Potentially use-visible declarations that have the same identifier are not use-visible unless each of them is an overloadable declaration.
11.a
Ramification: Overloadable declarations don't cancel each other out, even if they are homographs, though if they are not distinguishable by formal parameter names or the presence or absence of default_expressions, any use will be ambiguous. We only mention identifiers here, because declarations named by operator_symbols are always overloadable, and hence never cancel each other. Direct visibility is irrelevant for character_literals.

Dynamic Semantics

12
{elaboration (use_clause) [partial]} The elaboration of a use_clause has no effect. 

Examples

13
Example of a use clause in a context clause: 
14
with Ada.Calendar; use Ada;
15
Example of a use type clause: 
16
use type Rational_Numbers.Rational; -- see 7.1
Two_Thirds: Rational_Numbers.Rational := 2/3;
16.a
Ramification: In “use X, Y;”, Y cannot refer to something made visible by the “use” of X. Thus, it's not (quite) equivalent to “use X; use Y;”.
16.b
If a given declaration is already immediately visible, then a use_clause that makes it potentially use-visible has no effect. Therefore, a use_type_clause for a type whose declaration appears in a place other than the visible part of a package has no effect; it cannot make a declaration use-visible unless that declaration is already immediately visible.
16.c
"Use type S1;" and "use type S2;" are equivalent if S1 and S2 are both subtypes of the same type. In particular, "use type S;" and "use type S'Base;" are equivalent. 
16.d
Reason: We considered adding a rule that prevented several declarations of views of the same entity that all have the same semantics from cancelling each other out. For example, if a (possibly implicit) subprogram_declaration for "+" is potentially use-visible, and a fully conformant renaming of it is also potentially use-visible, then they (annoyingly) cancel each other out; neither one is use-visible. The considered rule would have made just one of them use-visible. We gave up on this idea due to the complexity of the rule. It would have had to account for both overloadable and non-overloadable renaming_declarations, the case where the rule should apply only to some subset of the declarations with the same defining name, and the case of subtype_declarations (since they are claimed to be sufficient for renaming of subtypes). 

Extensions to Ada 83

16.e
{extensions to Ada 83} The use_type_clause is new to Ada 95. 

Wording Changes from Ada 83

16.f
The phrase “omitting from this set any packages that enclose this place” is no longer necessary to avoid making something visible outside its scope, because we explicitly state that the declaration has to be visible in order to be potentially use-visible.

Wording Changes from Ada 95

16.g/2
{AI95-00217-06} Limited views of packages are not allowed in use clauses. Defined named in a use clause for use in other limited view rules (see 10.1.2).
Contents   Index   References   Search   Previous   Next 
Ada-Europe Sponsored by Ada-Europe