!ASIS Issue #054
!topic  Queries having Context as additional parameter
!reference  ASIS 95-10.15
!from  Sergey Rybin  97-03-03
!keywords  Context
!discussion

ASIS contains a number of pairs of queries, in each of these pairs,
both queries have the same name, they have similar functionality, the
first query in the pair has one parameter, but the second one contains
additional parameter of a Context type. There are two groups of these
pairs - one contains queries from Asis.Compilation_Units, another
contains semantic queries from Asis.Declarations working on Elements.

Some time ago I sent to the ASIS forum the question about the semantic
of Compilation unit queries having a Context as an additional
parameter.  We had a short discussion with Steve about these queries
resulting with some kind of "semi-formalization" of the semantic of
this additional parameter (Steve, correct me if I'm wrong,
unfortunately I've failed to find the corresponding messages in my
archive).

For example, for the Corresponding_Parent_Declaration query (its
definition is appended to this message), the semantic of the second
"version" of the query may be expressed in Ada pseudo-code as:

function Corresponding_Parent_Declaration
  (Library_Unit : in Asis.Compilation_Unit;
   The_Context  : in Asis.Context)
   return Asis.Compilation_Unit
is
begin
   if Is_Identical (Enclosing_Context (Library_Unit), The_Context) then
      --  no difference with the "first version" of
      --  Corresponding_Parent_Declaration, therefore

      return Corresponding_Parent_Declaration (Library_Unit);

   else
      if (there exists a unit Library_Unit_1 in the context The_Context
          such that Is_Equal (Library_Unit_1, Library_Unit)
      then
         return Corresponding_Parent_Declaration (Library_Unit_1);
      else
         return Nil_Compilation_Unit;
      end if;

   end if;
end Corresponding_Parent_Declaration;

Now let's consider some example of a query working on Elements and
having a Context as an additional parameter:

------------------------------------------------------------------------------
-- Section 15.13  function Corresponding_Type_Declaration
------------------------------------------------------------------------------
    function Corresponding_Type_Declaration
                (Declaration : in Asis.Declaration) return Asis.Declaration;

    function Corresponding_Type_Declaration
                (Declaration : in Asis.Declaration;
                 The_Context : in Asis.Context) return Asis.Declaration;
------------------------------------------------------------------------------
--  Declaration - Specifies the type declaration to query
--  The_Context - Specifies the program Context to use for obtaining package
--                body information
--
-- Returns the corresponding full type declaration when given a private or
-- incomplete type declaration.  Returns the corresponding private or
-- incomplete type declaration when given a full type declaration.
--
-- These two function calls will always produce identical results:
--
--   Decl2 := Corresponding_Type_Declaration( Decl1 );
--   Decl2 := Corresponding_Type_Declaration
--              ( Decl1,
--                Enclosing_Context( Enclosing_Compilation_Unit( Decl1 )));
--
-- Returns a Nil_Element when a full type declaration is given that has no
-- corresponding private or incomplete type declaration, or when a
-- corresponding type declaration does not exist within The_Context.
--
-- The parameter The_Context is used whenever the corresponding full type of
-- an incomplete type is in a corresponding package body.  See RM 95 3.10.1(3).
-- Any non-Nil result will always have the given Context as its
-- Enclosing_Context.
--
-- Appropriate Declaration_Kinds:
--      An_Ordinary_Type_Declaration
--      A_Task_Type_Declaration
--      A_Protected_Type_Declaration
--      An_Incomplete_Type_Declaration
--      A_Private_Type_Declaration
--      A_Private_Extension_Declaration
--
-- Returns Declaration_Kinds:
--      Not_A_Declaration
--      An_Ordinary_Type_Declaration
--      A_Task_Type_Declaration
--      A_Protected_Type_Declaration
--      An_Incomplete_Type_Declaration
--      A_Private_Type_Declaration
--
------------------------------------------------------------------------------

First, I would say, that the definition of all the queries from
Asis.Declarations, which have a Context as an additional parameter,
is not very clear.

Second, I would suggest the following interpretation of this query:

function Corresponding_Type_Declaration
  (Declaration : in Asis.Declaration;
   The_Context : in Asis.Context)
   return Asis.Declaration
is
   Arg_Enclosing_Context : Asis.Context :=
      Enclosing_Context (Enclosing_Compilation_Unit (Declaration));
begin
   if Is_Identical (Arg_Enclosing_Context, The_Context) then
      --  no difference with the "first version" of
      --  Corresponding_Type_Declaration, therefore

      return Corresponding_Type_Declaration (Declaration);

   else
      if (there exists a unit Library_Unit_1 in the context The_Context
          such that
          Is_Equal (Library_Unit_1, Enclosing_Compilatin_Unit (Declaration))

         and then

         (there exists an Element Declaration_1 in Library_Unit_1 such that
          Is_Equal (Declaration, Declaration_1)  )
      then
         return Corresponding_Type_Declaration (Declaration_1);
      else
         return Nil_Element;
      end if;

   end if;
end Corresponding_Type_Declaration;

And, the most important: if both these interpretations are correct
(look reasonable), I would definitely say, that all the queries having
a Context as an additional parameter are *SECONDARY QUERIES*, and as
being secondary, they should be *MOVED* from the official ASIS
definition into the corresponding ASIS secondary layer.

I do not think, that something really important for applications would
be lost, even if we would simply delete all these queries, but
deleting these queries would definitely make ASIS more clear (and
shorter, of course :-)

!resolution  Accepted, with Modifications.
!date
!Notes

The following rationale for queries with an additional Context
parameter appears in Annex D.4.8, titled "Queries with an Additional
Context Parameter".

Several queries, including Corresponding_Declaration and
Corresponding_Body, are overloaded with an additional parameter,
Context.  The additional queries are there for flexibility and power,
if an ASIS implementation can take advantage of it.

Some ASIS implementations may be able to support multiple open
Contexts at the same time.  Tools that would make use of more than one
Context could be severely limited if they do not have the control
provided by the Context parameter.  An example of such a tool would be
one that compared two contexts, identifying units appearing in both
and ensuring their semantic dependent units were consistent, perhaps
for some configuration management purpose.

The Corresponding_Declaration in a different context should always be
the declaration upon which the body depends semantically in that
context, not just an unrelated declaration of the same name.

ASIS implementations that only allow one open Context can implement
these pairs of queries in tandem, with one simply calling the other
and providing the current Context as a parameter.

See also Issue #033.