!standard 1.3                                          09-03-11  SI99-0037-1/07
!class binding interpretation 08-06-13
!status ARG Approved  6-0-3  09-02-21
!status work item 08-06-13
!status received 08-06-13
!priority Medium
!difficulty Easy
!qualifier Error
!subject Review standard for problematic wording.

!summary

Correct problematic wording in the Standard.

!question

Should we correct existing but problematic wording in the standard? (Yes.)

!recommendation

(See Summary.)

!wording

Foreword section:

Replace entire clause with current ISO boilerplate text [from the 2004 directives]
(and also add the necessary description of this edition):

  ISO (the International Organization for Standardization) and IEC (the
  International Electrotechnical Commission) form the specialized system for
  worldwide standardization. National bodies that are members of ISO or IEC
  participate in the development of International Standards through technical
  committees established by the respective organization to deal with
  particular fields of technical activity. ISO and IEC technical committees
  collaborate in fields of mutual interest. Other international organizations
  governmental and non-governmental, in liaison with ISO and IEC, also take
  part in the work. In the field of information technology, ISO and IEC have
  established a joint technical committee, ISO/IEC JTC 1.

  International Standards are drafted in accordance with the rules given in
  the ISO/IEC Directives, Part 2.

  The main task of the joint technical committee is to prepare International
  Standards. Draft International Standards adopted by the joint technical
  committee are circulated to national bodies for voting. Publication as an
  International Standard requires approval by at least 75% of the national
  bodies casting a vote.

  International Standard ISO/IEC 15291 was prepared by Joint Technical Committee
  ISO/IEC JTC 1, Information technology, Subcommittee 22, Programming
  languages, their environments and system software interfaces.

  This second edition cancels and replaces the first edition (ISO/IEC 15291:1999),
  of which it constitutes a technical revision.

  Annexes A, B, C, D, and E of this International Standard are for
  information only. Annex F forms an integral part of this International Standard.

1.1.2

The latter part of this clause were rewritten to reflect the current structure
of the standard:

In addition to the basic description of each entity that makes up the ASIS interface,
text of various types is labeled with headers.

The various headers and their meaning are:

Implementation Permissions

These items describe permissions given an implementor when implementing the
associated type or query. 

Implementation Requirements

These items describe additional requirements for conforming implementations. 

NOTE   These notes describe notes of interest to ASIS applications. 

Examples

These items give examples of use of ASIS interfaces. 

1.1.3.1

Replace the last sentence of item B):

An implementation shall not change package specifications in this International
Standard except by:

* Adding with clauses, pragmas, representation specifications, comments, and
  allowable pragmas. Allowable pragmas are those which do not change the semantics
  of the interface (e.g., List, Optimize, Page).

* Replacing instances of the words <implementation-defined> with appropriate value(s).

* Adding or changing private parts.

* Making any other changes that are lexically transparent to Ada compilers. 

by:

An implementation shall not add any declarations to the visible part of logical packages
defined in the following clauses of this International Standard.

[Drafting note: Since we removed the package specifications from the standard, so we
ought to remove the text talking about it, too. It's silly to be talking about lexical
changes in any case. We don't have to mention aspect clauses, and it would be odd to
allow Size clauses but not pragma Pack (which the old wording did.]

1.1.5

Replace:

A set of exceptions shall be raised for the following circumstances:

By:

ASIS defines a set of global exceptions. These exceptions are raised 
under the circumstances listed:

[Drafting Note: You can only raise one exception at a time, so raising "a set of
exceptions" is not possible. There is no reason to use "shall" here, as the
exceptions to raise are described for each routine individually (other than
ASIS_Failed, which we aren't requiring to be raised in any particular
circumstances.]

1.2

Add the following:

ISO/IEC 8652:1995/Cor.1:2001(E), Information technology - Programming languages
 - Ada - Technical Corrigendum 1

ISO/IEC 8652:1995/AMD 1:2007(E), Information technology - Programming languages
 - Ada - Amendment 1

Section 3.8 lists items alphabetically with Elements and Element_List subtypes interspersed,
These should be rearranged to list them as Elements and Element_List subtypes separately.
(Careful: Defining_Name and Defining_Name_List out of alphabetical order originally!)

3.9.21

Add a separator between the example and the type definition:

The type definition is:

[Drafting Note: We need a separator here, or it isn't possible to tell where the
introductory example ends and the definition begins.]

Section 3.10 has an instance of "before before", remove one "before".

Section 3.10 Modify (some) paragraph of Section 3.10 to:

The context clause contains zero or more with clauses, use clauses, {and
pragmas}[pragma elaborates, and possibly other pragmas].

[Drafting note: There are more kinds of pragmas than just Elaborate allowed here,
including Elaborate_All. No sense in listing what is allowed.]

3.12.4 (middle of section) says:

For example:
If A withs B and B withs C
then A directly depends on A, B directly depends on C,

Replace this by:
If A mentions B and B mentions C in with_clauses
then A directly depends on B, B directly depends on C,

(Note that this includes a bug fix and a rewording).

Similarly, replace the second occurrence with

If A mentions B and B mentions C and C.Y in with_clauses and C does not
have a with_clause, then...


10.3:

Change paragraph 2:

Returns the Unit_Origins value of the unit. Returns
Not_An_Origin for a compilation_unit whose Unit_Kind is Not_A_Unit,
A_Nonexistent_Declaration, or A_Nonexistent_Body or possibly An_Unknown_Unit.

Add an Implementation permission:

ASIS queries on the private part and bodies of Compilation_Units whose Unit_Origin
is other than An_Application_Unit may have limitations that are implementation-defined.
Operations of package Asis.Text on Compilation_Units whose Unit_Origin is other than
An_Application_Unit may have limitations that are implementation-defined.

[Drafting note: We want to allow implementations that do not have access
to the source code for predefined and implementation-defined units (it may not
even exist), and that do not have access to the bodies or private parts. Thus
we do not guarentee that such queries work.]

10.17:

Index "same physical compilation unit"; italicize text; change "have"
to "has".

[Drafting note: This is a technical term used elsewhere, such as 21.6.]

10.18: Delete duplicate definition of "same physical compilation unit".

10.25 and 10.27

Returns the Form parameter (as for {Ada.}Text_Io.Open)

11.3

Returns a duration of {Ada.Calendar.Day_Duration'Last}[86_400.0] if the CPU
duration for the last compilation is greater than 1 day.

[Drafting note: Replace magic number by a named value.]

12.1

Fix confusion:

"If a leftmost units is consistent..." should read "If a unit that is the
leftmost of a pair is consistent..."

Near end of clause, formatting problem, smaller font used.

12.2

There is no description of this constant in the section.  Add the below to
designate the use of this constant throughout the section:

A Nil_Relationship is returned by all Compilation_Units.Relations functions
when there is no relationship between the specified units.

13.1

Delete:

"Gateway queries between Compilation_Units and Elements."

as this seems to be a junk sentence fragment.

13.3

Modify:

All pragma Elaborate elements for this unit will appear in this list.
[Other pragmas will appear in this list, or in the Compilation_Pragmas list, or both. ]

[Drafting note: This same ground is covered by the implementation permission, no sense
in saying it twice.]

Delete the paragraph about Standard. (It is now covered by the permission
in 3.12.3.)

** TBD ** coming back here.

13.6

Correct the parameter name:

{Element}[Compilation_Unit] expects any kind of element.

13.37

[Drafting note: The two column format of this clause does not work well in HTML.
Moreover, the format caused nasty word wrapping in Word/PDF. Therefore, each item was
separated with spaces and a mdash.]


15.25

Remove exception statement, returns false for any un expected element.


15.27: Put A_Pragma above A_Declaration (so it doesn't get lost after the nested items)

15.28 (parameter and return), 15.29 (parameter), 15.32 (parameter), 16.31
(return): Remove the extra nesting (the outer item only contains a single kind
and thus provides no information).


15.36, 16.4, 16.21, 16.22, 16.33, 16.34, 18.2: Drop "one of" when there is only
a single element.


15.44:

Move the first three paragraphs and the two associated bulleted lists to a new
subclause "2.4.5.3 Processing instantiations".

16.12: Change to:

Definition expects an element that has one of the following Definition_Kinds:
  A_Constraint that has the following Constraint_Kinds:
    A_Digits_Constraint
  A_Type_Definition that has one of the following Type_Kinds:
    A_Floating_Point_Definition
    A_Decimal_Fixed_Point_Definition

16.13: Change to:

Definition expects an element that has one of the following Definition_Kinds:
  A_Constraint that has the following Constraint_Kinds:
    A_Delta_Constraint
  A_Type_Definition that has one of the following Type_Kinds:
    An_Ordinary_Fixed_Point_Definition
    A_Decimal_Fixed_Point_Definition


16.14: Change to:

Definition expects an element that has one of the following Definition_Kinds:
 A_Constraint that has one of the following Constraint_Kinds:
    A_Digits_Constraint
    A_Delta_Constraint
  A_Type_Definition that has one of the following Type_Kinds:
    A_Floating_Point_Definition
    An_Ordinary_Fixed_Point_Definition
    A_Decimal_Fixed_Point_Definition

16.30: Drop "one of" from the first and third items in the "Returns" list.


17.8 Modify the description of the parameter:

[Reference expects an element that has one of the following Element_Kinds:
   An_Expression
Raises ASIS_Inappropriate_Element with a Status of Value_Error for any element
that does not have one of these expected kinds.]
Reference expects an element that has one of the following Expression_Kinds:
   An_Identifier
   An_Operator_Symbol
   A_Character_Literal
   An_Enumeration_Literal

[Drafting note: The first part here is redundant.]

17.17 Modify the second paragraph as follows:

Returns a list of the Array_Component_Associations in an array aggregate. {If the
aggregate is a positional array aggregate, the Array_Component_Associations consist
of an expression of the aggregate with Array_Component_Choices that are each a
Nil_Element_List for all positional expressions except for the others choice, if any.} 

Delete second sentence of the note.

[Drafting note: This must be normative text, as this is a place where ASIS does not
follow the synatx of the Ada Standard.]


18.2: Remove the outer level (as in 15.28) and "one of".


18.3, 18.7, 18.11: Remove the outer level from the parameter (as in 15.28) and "one of" from
both the parameter and return.

18.8: Drop "one of" from the parameter. Correct the spelling of "follwing" and drop
extra "of" in the return.


20.1: Delete the first sentence (but keep the index entries). Add "The type
Line represents ..." The third sentence of the second paragraph is junk
and should be deleted (of course it is supported). Replace the last sentence:
"Nil_Line is the value of a default-initialized Line object."
Delete the paragraph about undiscriminated private type.


20.7: Drop "Span is" and "that" from the first sentence, italicize
"single text position" and index that. (It is a definition.) The "position within
the compilation unit" in this sentence should be "location within the compilation."
"Type {S}[s]pan..." in the third paragraph.

20.13 - 20.17:

Add "; otherwise returns False." to all of these.

20.28:

Add after the second paragraph:

Raises ASIS_Inappropriate_Line if Is_Nil (The_Line).

[Drafting note: This wording is identical to that in 20.18.]


21.1:

Delete the first sentence.

"Nil_Id is the value of a default-initialized Id object."

Delete the last paragraph. The second paragraph should start:
"The type Id represents permanent ...".

21.2

Add:

Returns an implementation-defined value which is a function of the value of The_Id.
If A and B are ids such that Is_Identical (A, B) is true, Hash(A) equals Hash(B).

AASIS Implementation Note: This function should produce a result (not raise an
exception) when passed Nil_Id.

21.3

Add:

Defines a total ordering on Ids.

21.4

Add:

Equivalent to Right < Left.

21.8:

Modify the second paragraph:

Returns the Element value corresponding to The_Id. The_Id shall correspond to
an Element available from a Compilation_Unit contained by
({can be referenced}[referencible] through) The_Context.

Modify the last paragraph:

"not available th{r}ough The_Context"

Add:

Is_Identical (Create_Element (Create_Id(E),
Enclosing_Context(Enclosing_Compilation_Unit(E))), E) is True for any element E.

If Create_Element is called twice with the same Id and context, the two results
are Is_Identical.


21.9:

Correct the title to (id), not (ids).

Modify the second paragraph:

...associated with the Id{ including for Nil_Id}.



22:

Modify the first paragraph:

{Support for data decomposition is optional. }The library package
Asis.Data_Decomposition {shall}[may] exist{ for an implementation that
supports data decomposition}. If it exists, the package shall provide
interfaces equivalent to those described in the following subclauses.

Delete "This package is optional."

Change "representation and length clauses" to "aspect clauses".

22.20, 22.21, 22.23, 22.28: Drop "one of" from the Type_Definition list.

22.26, 22.27: Drop "one of" from the returns list.

D.2.3:

Replace the references to old standards by their appropriate ISO references:

(the original Ada Standard, ISO 8652:1987[12], or its more recent version
ISO/IEC 8652:1995[7])


!discussion


!appendix

From: Pascal Leroy
Sent: Monday, June 16, 2008, 2:43 AM

> Global:
>
> Many chapters say "The library package Asis.XXX shall exist. The package shall
> provide interfaces equivalent to those described in the following subclauses."
>
> Section 4:
>
> (Of course it exists! It's the required next chapter.)
>
>The package shall provide interfaces equivalent to those described in the
> following subclauses. (Why equivelent?)

Beware, the weird wording "shall exist, shall provide equivalent" was very
carefully worded by WG9, to address copyright concerns. See WG9 document N468.
It should not be changed lightly as part of an editorial cleanup, lest you run
into problems down the road.

> For example:
> If A withs B and B withs C

I am hoping that we won't be using the verb "to with" in normative text.


****************************************************************

From: Greg Gicca
Sent: Tuesday, January 20, 2009, 9:44 AM

 From my notes on this section of the SI99-0037-1, section on 3.12.3:

Probably should be "An_Application_Unit".

Added the Implementation Permission as:

Units with an Origin of other than An_Application_Unit are
implementation-defined. This will effect the return value of function
Asis.Compilation_Units.Unit_Origin.


However I disagree with this advise.  I think it would be better to add
An_Unknown_Unit to the type. Predefined_Unit should return this value (these may
or may not have source associated with them) Implementation_Unit should be used
for exactly these types of units (same as above) An_Unknown_Unit should be added
to cover the case for any unit that Origin is unknown, but is An_Origin. Then
this is pretty much already stated using Not_An_Origin in 10.3 (that would need
updating)


Same SI says:

21.6: Replace 2nd paragraph by:

"Returns True if Left and Right represent the same Id, from the same version of
a compilation unit."

[Greg: Search for other remaining occurrences of "physical", and try to replace
that wording by something meaningful. Either drop it, say something about
"version", or ask the ARG for help.]


Physical shows up in a variety of locations in mostly different contexts than
what is being referred to here. Section 10.18 defines "physical compilation
unit" and references RM E.3(5). This is then implementation defined (perhaps to
avoid saying "file").

I did not make the suggested change above.  I suggest the below text for here
(21.6):

"Returns True if Left and Right represent the same Id, representing the same
physical compilation unit (as defined in section 10.18). The two Ids convert to
Is_Identical Elements when converted with the same open ASIS Context. "

Please do a quick scan for the use of "physical" and let me know the groups
decision on this SI.

****************************************************************

From: Sergey I. Rybin
Sent: Tuesday, January 20, 2009, 10:03 AM

>  From my notes on this section of the SI99-0037-1, section on 3.12.3:
>
> Probably should be "An_Application_Unit".

Yes it should.

>
> Added the Implementation Permission as:
>
> Units with an Origin of other than An_Application_Unit are
> implementation-defined.
> This will effect the return value of function
> Asis.Compilation_Units.Unit_Origin.
>
>
>
> However I disagree with this advise.  I think it would be better to
> add An_Unknown_Unit to the type.
> Predefined_Unit should return this value (these may or may not have
> source associated with them) Implementation_Unit should be used for
> exactly these types of units (same as above) An_Unknown_Unit should be
> added to cover the case for any unit that Origin is unknown, but is
> An_Origin.
> Then this is pretty much already stated using Not_An_Origin in 10.3
> (that would need updating)

May be I've missed something, but I cannot understand what is wrong with the
existing definition of Unit_Origins type. (I've read si99-0037-1 but I cannot
get what is wrong with the existing classification of unit origins and why do we
need this new An_Unknown_Unit kind.

****************************************************************

From: Greg Gicca
Sent: Tuesday, January 20, 2009, 11:07 AM

It's the recommended new implementation permission I don't agree with and was
therefor offering an alternative solution.  I think implementations should
return the correct value for the existing type values.  Then I suggested the
above change to account for when the origin can not be determined to try and
accommodate the recommendation.

****************************************************************

From: Sergey I. Rybin
Sent: Tuesday, January 20, 2009, 11:21 AM

Thank you for the explanation. Now I see the point and do not have any
objection.

****************************************************************

From: Randy Brukardt
Sent: Tuesday, January 20, 2009, 12:19 PM

> It's the recommended new implementation permission I don't agree with
> and was therefor offering an alternative solution.
>  I think implementations should return the correct value for the
> existing type values.  Then I suggested the above change to account
> for when the origin can not be determined to try and accommodate the
> recommendation.

I don't think that your suggested implementation permission has anything
whatsoever to do with the topic of the minutes. In private mail, you said
"source availability is a separate issue" -- no, I totally disagree with that,
it's the *whole* issue. There is nothing wrong with Unit_Origin (of if there is,
I don't know what it is).

Here's what the minutes say (in reference to 13.3):

"Tucker would like to delete the existing paragraph (which is far more general
than just this place) and put an Implementation Permission into 3.12.3, that
says that for units with an Origin of other than Application_Defined_Unit, the
results of some ASIS queries is implementation-defined. Better have an actual
list of what it meant by "some queries". Greg has the short stick on this one."

The point is that for units that have an Origin of other than
An_Application_Unit, many ASIS queries (especially those having to do with
source, but ones like 13.3 as well) are not well-defined. You don't need to
change the definition of Origin to handle that (indeed it doesn't help at all),
but you do need either a global implementation permission (that was the original
suggestion, although it would have to specify the set of queries that it applied
to), or permissions in all of the queries that aren't necessarily meaningful for
predefined and implementation-defined units.

So I don't think either your proposed permission nor your "An_Unknown_Unit"
does anything whatsoever to solve the problem.

****************************************************************

From: Greg Gicca
Sent: Wednesday, January 21, 2009, 9:40 AM

> I don't think that your suggested implementation permission has
> anything whatsoever to do with the topic of the minutes. In private
> mail, you said "source availability is a separate issue" -- no, I
> totally disagree with that, it's the *whole* issue. There is nothing
> wrong with Unit_Origin (of if there is, I don't know what it is).
>

In using the type or function the goal is to know where the unit came from.  If
the unit is A_Predefined_Unit or An_Implementation_Unit then the user will know
that source (or any information) may or may not be available.  I was offering a
third option where source may not be available, since Not_An_Origin may not be
truly correct.  It may have an Origin (it came from somewhere if you have a
Compilation_Unit) but the compile system did not store where it came from.

I fully understand that predefined or run-time units may not be provided in a
manner that is accessible to ASIS.  However Not_An_Origin does not seem to me to
be an appropriate response to this query.  Hell if we are talking about a source
file in a binary library model, you might have a Compilation_Unit that ASIS sees
but the source file has since been moved or deleted.  So Unknown again seems to
be missing from the type.

I am commenting that I think this type and function appear wrong to me (somewhat
separate from the SI).

> Here's what the minutes say (in reference to 13.3):
>
> "Tucker would like to delete the existing paragraph (which is far more
> general than just this place) and put an Implementation Permission
> into 3.12.3, that says that for units with an Origin of other than
> Application_Defined_Unit, the results of some ASIS queries is
> implementation-defined. Better have an actual list of what it meant by
> "some queries". Greg has the short stick on this one."
>
> The point is that for units that have an Origin of other than
> An_Application_Unit, many ASIS queries (especially those having to do
> with source, but ones like 13.3 as well) are not well-defined. You
> don't need to change the definition of Origin to handle that (indeed
> it doesn't help at all), but you do need either a global
> implementation permission (that was the original suggestion, although
> it would have to specify the set of queries that it applied to), or
> permissions in all of the queries that aren't necessarily meaningful
> for predefined and implementation-defined units.
>
> So I don't think either your proposed permission nor your "An_Unknown_Unit"
> does anything whatsoever to solve the problem.
>

ASIS provides semantically equivalent information and never guarantied to
provide an actual representation of the source.  Stub generators, pretty
printers, debuggers, etc. can not be written with ASIS (without convoluted
source traversal approaches) .  As 13.3 shows you might get:  "with A, B, C;" or
"with A; with B; with C;" for the same source depending on the implementation.
Actually you get a list, but whatever.  This is not wrong but just the way the
standard operates (is generally defined).

I am not complaining about listing the effected functions that use this type,
only a single one directly uses it, or the recursive list you are referencing in
13.3, but that the type definition examined because of this SI appears to have a
missing value, then the ramifications appear far reaching.

****************************************************************

From: Randy Brukardt
Sent: Wednesday, February  4, 2009, 11:57 PM

...
> > I don't think that your suggested implementation permission has
> > anything whatsoever to do with the topic of the minutes. In private
> > mail, you said "source availability is a separate issue" -- no, I
> > totally disagree with that, it's the *whole* issue. There is nothing
> > wrong with Unit_Origin (of if there is, I don't know what it is).
>
> In using the type or function the goal is to know where the unit came
> from.  If the unit is A_Predefined_Unit or An_Implementation_Unit then
> the user will know that source (or any information) may or may not be
> available.  I was offering a third option where source may not be
> available, since Not_An_Origin may not be truly correct.  It may have
> an Origin (it came from somewhere if you have a
> Compilation_Unit) but the compile system did not store where it came
> from.
>
> I fully understand that predefined or run-time units may not be
> provided in a manner that is accessible to ASIS.  However
> Not_An_Origin does not seem to me to be an appropriate response to
> this query.  Hell if we are talking about a source file in a binary
> library model, you might have a Compilation_Unit that ASIS sees but
> the source file has since been moved or deleted.  So Unknown again
> seems to be missing from the type.

OK, I guess I see that. But the problem we were talking about in Portland (well,
at least the problem *I* was talking about in Portland, and recorded) is that
nothing in the ASIS standard seems to allow information to be unavailable for
A_Predefined_Unit or An_Implementation_Unit (or "An_Unknown_Unit" if you add
that). That has to be explicitly specified somewhere, if, as you say, it is the
model that such information may not be available.

There is some text (looks like an incorrectly formatted note to me) in 13.3 that
discusses this in terms of Context_Clauses, but that needs to be said for *any*
query that might not have complete information for a predefined unit. Is there
some normative wording to that effect somewhere? (If so, please give us a
reference!) (And Tucker's point was that this text in 13.3 is either redundant
and uninteresting, or in the wrong place.)

I really don't see how your intended changes address this, because you are still
assuming that ASIS may not be able to see predefined units -- but that cannot be
assumed, it has to be explicitly stated.

> I am commenting that I think this type and function appear wrong to me
> (somewhat separate from the SI).

Fine enough.

...
> > So I don't think either your proposed permission nor your "An_Unknown_Unit"
> > does anything whatsoever to solve the problem.
> >
>
> ASIS provides semantically equivalent information and never guarantied
> to provide an actual representation of the source.
>  Stub generators, pretty printers, debuggers, etc. can not be written
> with ASIS (without convoluted source traversal
> approaches) .  As 13.3 shows you might get:
> "with A, B, C;" or "with A; with B; with C;" for the same source
> depending on the implementation.  Actually you get a list, but
> whatever.  This is not wrong but just the way the standard operates
> (is generally defined).

But we're talking about cases where ASIS doesn't provide any information at all
(such as that for the context clauses of predefined units). "Semantically
equivalent" surely doesn't mean no such information at all! But we *do* want to
allow no information at all for some queries for predefined units; that was the
point of the existing note and the point of the discussion.

BTW, don't forget that we've made an effort to make writing source transforming
tools easier. (ASIS implementers told us that was important, and that real ASIS
implementations would never make building such tools hard.) To that end, we
removed a lot of the permissions that allowed providing "semantically
equivalent" information, specifically so that source transforming tools would be
more portable. For instance, its no longer allowed to always return normalized
lists for parameters. Remember that we polled the ASIS implementers and
essentially removed every such permission that they were not using. But I don't
think we looked at this one in 13.3 (we only looked at the lengthy list in
chapter 7). I suspect that we wanted to remove it as well - so it is kinda silly
to use that as an excuse for not having a more clear rule.


----

An unrelated point about this SI:

I recently noticed that we never did anything about the formatting issues that I
called out years ago (they have bold italic text ending with "- RLB" in the
standard). We ought to deal with those ASAP; it would be fine to stick any
needed changes into SI-37 (no point in opening another formatting SI). (I just
searched the ASIS document with the web search facility and found 9 such
comments that need changing.) Can you do that??

****************************************************************