Version 1.3 of ai05s/ai05-0294-1.txt

Unformatted version of ai05s/ai05-0294-1.txt version 1.3
Other versions for file ai05s/ai05-0294-1.txt

!standard N(1/2)          12-03-14 AI05-0294-1/02
!class presentation 12-02-15
!status ARG Approved 9-0-1 12-02-25
!status work item 12-02-15
!status received 12-02-10
!priority Low
!difficulty Easy
!subject Update the glossary
!summary
Additional terms are added to the glossary to help describe the new concepts in Ada 2012.
!question
The glossary does not mention a single Ada 2012 term. That seems wrong, there are many that conceivably should be there. Should we add terms to the glossary?
!wording
Add the following terms to the Glossary:
Predicate. A predicate is an assertion that is expected to be True for all objects of a given subtype.
Precondition. A precondition is an assertion that is expected to be True when a given subprogram is called.
Postcondition. A postcondition is an assertion that is expected to be True when a given subprogram returns normally.
Invariant. A invariant is an assertion that is expected to be True for all objects of a given private type when viewed from outside the defining package.
Assertion. An assertion is a boolean expression that appears in any of the following: a pragma Assert, a predicate, a precondition, a postcondition, an invariant, a constraint, or a null exclusion. An assertion is expected to be True at run time at certain specified places.
Aspect. An aspect is a specifiable property of an entity. An aspect may be specified by an aspect_specification on the declaration of the entity. Some aspects may be queried via attributes.
Iterator. An iterator is a construct that is used to loop over the elements of an array or container. Iterators may be user defined, and may perform arbitrary computations to access elements from a container.
Container. A container is an object that contain other objects all of the same type, which could be class-wide. Several predefined container types are provided by the children of package Ada.Containers (see A.18.1).
Reference type. A reference type is one that has user-defined behavior for ".all", defined by the Implicit_Dereference aspect.
Indexable container type. An indexable container type is one that has user-defined behavior for indexing, via the Constant_Indexing or Variable_Indexing aspects.
Iterable container type. An iterable container type is one that has user-defined behavior for iteration, via the Default_Iterator and Iterator_Element aspects.
Storage pool. Each access-to-object type has an associated storage pool object. The storage for an object created by an allocator comes from the storage pool of the type of the allocator. Some storage pools may be partitioned into subpools in order to support finer-grained storage management.
Stream. A stream is a sequence of elements that can be used, along with the stream-oriented attributes, to support marshalling and unmarshalling of values of most types.
!discussion
!ACATS Test
No tests needed.
!ASIS
No change needed.
!appendix

From: Randy Brukardt
Sent: Friday, February 10, 2012  8:08 PM

One of the NB comments is a query about why the Glossary does not include any
Ada 2012 terms [like predicate, precondition, postcondition, invariant, aspect
(which is really an Corrigendum 1 term), or assertion (which is really an Ada
2005 term)].

This seems like a valid concern. Do we have a victim, er, volunteer to develop
some Glossary entries to bring to the meeting? Without a volunteer, I don't
think this is going to happen.

Probably it would be good to skim over the annex to make sure that none of the
existing entries need correction, as well. (Although, two reviewers supposedly
did that.)

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

From: Bob Duff
Sent: Friday, February 10, 2012  8:49 PM

> One of the NB comments...

Which NB?  New Brunswick?

>.... is a query about why the Glossary does not include  any Ada 2012
>terms [like predicate, precondition, postcondition, invariant,  aspect
>(which is really an Corrigendum 1 term), or assertion (which is  really
>an Ada 2005 term)].
>
> This seems like a valid concern. Do we have a victim, ...

If you give me very specific instructions about how to format the text, so you
can easily insert it, and an exact list of terms, I might be willing to
volunteer to be the victim.

>...er, volunteer to
> develop some Glossary entries to bring to the meeting? Without a
>volunteer,  I don't think this is going to happen.
>
> Probably it would be good to skim over the annex to make sure that
> none of the existing entries need correction, as well. (Although, two
> reviewers supposedly did that.)

I'm not volunteering for that part.

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

From: Tucker Taft
Sent: Friday, February 10, 2012  8:59 PM

>> One of the NB comments...
>
> Which NB?  New Brunswick?

National Body.

>
> If you give me very specific instructions about how to format the
> text, so you can easily insert it, and an exact list of terms, I might
> be willing to volunteer to be the victim. ...

Major brownie point time!

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

From: Bob Duff
Sent: Friday, February 10, 2012  9:07 PM

...
> National Body.

Yeah, I know, but which one?

...
> Major brownie point time!

;-)

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

From: Randy Brukardt
Sent: Friday, February 10, 2012  9:15 PM

> > One of the NB comments...
>
> Which NB?  New Brunswick?

I went and looked it up, the National Body involved was Canada. So "New
Brunswick" might even be right! :-)

> >.... is a query about why the Glossary does not include any Ada 2012
> >terms [like predicate, precondition, postcondition, invariant, aspect
> >(which is really an Corrigendum 1 term), or assertion (which is
> >really an Ada 2005 term)].
> >
> > This seems like a valid concern. Do we have a victim, ...
>
> If you give me very specific instructions about how to format the
> text, so you can easily insert it, and an exact list of terms, I might
> be willing to volunteer to be the victim.

The list of terms mentioned in the comment (and expanded a bit by me) is above.
Most of the other things are too specific to bother including (like
"predicate-static" and "statically unevaluated").

Looking through the standard, we probably ought to include "iterator".
"Container" might be a good idea as well (we didn't include that in Ada 2005,
but it is a large part of the standard these days).

There are some new things that are on the cusp: "conditional expression",
"quantified expression", "reference type", "indexable type", the various kinds
of containers, "locale", "string encoding". There's probably others that never
made it to the Glossary in the past. Use your judgment, the things in question
have to be fairly high level.

The format I'll need is as follows (taking an example from the Ada 2005
text):

@ChgToGlossary{Version=[3],Kind=[Added],Term=<Evaluation>,
Text=<@ChgAdded{Version=[3],Text=[The process by which an expression achieves
its run-time effect is called evaluation. Evaluation is one of the forms of
execution.]}>}

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

From: Randy Brukardt
Sent: Friday, February 10, 2012  9:23 PM

> Yeah, I know, but which one?

As I mentioned in the other message, it was Canada. Each country sent a handful
of comments - except Canada, which sent what appears to be more than 30 formal
comments (a 16K file), along with an equal-sized file of editorial comments
(which was more dense). Dealing with the Canadian comments has been somewhat
like getting an entire extra ARG review. Not necessarily a bad thing for the
Standard, but way beyond what I'd budgeted time for. I've worked my way through
the entire set of editorial comments, but I haven't done anything with the
formal comment yet. (I'm taking a bit of a break to get some of the AIs for the
upcoming meeting together first, mainly so I can respond to most of the formal
comments with the AI number where we either will or already have discussed the
issue.)

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

From: Brad Moore
Sent: Friday, February 10, 2012  10:19 PM

New Brunswick, is actually the correct answer. Or at least it's not incorrect,
in fact one of the reviewers is from New Brunswick, and still has family there,
though currently she resides here in Alberta. I suppose the correct answer is
Canada, unless other NB's made the same comment.

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

From: John Barnes
Sent: Saturday, February 11, 2012  5:56 AM

NB (nota bene) I will be happy to review the outcome.

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

From: Bob Duff
Sent: Saturday, February 11, 2012  11:37 AM

> There are some new things that are on the cusp: "conditional
> expression", "quantified expression", "reference type", "indexable
> type", the various kinds of containers, "locale", "string encoding".
> There's probably others that never made it to the Glossary in the
> past. Use your judgment, the
                                                           ^^^^^^^^
> things in question have to be fairly high level.

I asked for "an exact list of terms" so I wouldn't have to use my judgment.  I have only a limited supply of the stuff, you know.  ;-)

OK, I used up some judgement, and the result follows.

I suppose all these terms belong in the index, as well.

John Barnes wrote:

> NB (nota bene) I will be happy to review the outcome.

NW (note well) that I thank you.
Here you go:

@ChgToGlossary{Version=[3],Kind=[Added],Term=<predicate>,
Text=<@ChgAdded{Version=[3],Text=[A predicate is a condition that is intended to
be True for all objects of a given subtype.]}>}

@ChgToGlossary{Version=[3],Kind=[Added],Term=<precondition>,
Text=<@ChgAdded{Version=[3],Text=[A precondition is a condition that must be
True when a given subprogram is called.]}>}

@ChgToGlossary{Version=[3],Kind=[Added],Term=<postcondition>,
Text=<@ChgAdded{Version=[3],Text=[A postcondition is a condition that must be
True when a given subprogram returns normally.]}>}

@ChgToGlossary{Version=[3],Kind=[Added],Term=<invariant>,
Text=<@ChgAdded{Version=[3],Text=[A invariant is a condition that is intended to
be True for all objects of a given private type when viewed from outside the
enclosing package.]}>}

@ChgToGlossary{Version=[3],Kind=[Added],Term=<aspect>,
Text=<@ChgAdded{Version=[3],Text=[An aspect is any of a miscellaneous set of
properties of entities. An aspect may be specified by an aspect_specification on
the declaration of the entity. Some aspects may be queried via attributes.]}>}

@ChgToGlossary{Version=[3],Kind=[Added],Term=<assertion>,
Text=<@ChgAdded{Version=[3],Text=[An assertion is any of the following: a pragma
Assert, a predicate, a precondition, a postcondition, an invariant, a
constraint, or a null exclusion. Assertions may be used to specify conditions
that must be True at run time at certain places.]}>}

@ChgToGlossary{Version=[3],Kind=[Added],Term=<iterator>,
Text=<@ChgAdded{Version=[3],Text=[An iterator may be used to loop over the
elements of an array or container. Generalized iterators may be user defined,
and may perform arbitrary computations.]}>}

@ChgToGlossary{Version=[3],Kind=[Added],Term=<container>,
Text=<@ChgAdded{Version=[3],Text=[A container type is one whose objects contain
other objects. Several predefined container types are provided by the children
of package Ada.Containers (see A.18.1).]}>}

@ChgToGlossary{Version=[3],Kind=[Added],Term=<reference type>,
Text=<@ChgAdded{Version=[3],Text=[A reference type is one that has user-defined
semantics for ".all", defined by the Implicit_Dereference aspect.]}>}

@ChgToGlossary{Version=[3],Kind=[Added],Term=<indexable type>,
Text=<@ChgAdded{Version=[3],Text=[An indexable type is one that has user-defined
semantics for indexing, via the Constant_Indexing or Variable_Indexing
aspects.]}>}

"conditional expression" and "quantified expression" are just syntactic
categories; I don't think they need glossary entries.  There's no glossary entry
for "case_statement".

"various kinds of containers": too lazy.  And probably not that useful.

"locale", "string encoding": obscure features; not useful enough to put in the
glossary.

"probably others": too lazy.

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

From: Jeff Cousins
Sent: Monday, February 13, 2012  5:56 AM

At first sight the glossary is a simple 4 page affair.  But when I read it
alongside glossaries for other languages it became evident that it goes quite
deep into what the underlying concepts of the language are.  Possibly it should
have been written first not last.  So it is important to get right, and thanks
Bob for your suggested additions.

I think I suggested a few more to John Barnes about 4-5 years ago when I
commented on his book, for where glossaries for other languages had definitions
of the equivalent terms, but I can't find my comments anywhere.

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

From: Randy Brukardt
Sent: Wednesday, February 15, 2012  7:19 PM

No problem, your comments are filed in AI95-00437-1 [mail of October 27, 2005].
(Which I happened to see when checking on the classification of that AI, which
needs to be the same for the new one. John had forwarded them to the ARG list
back then.) The easiest way to get to it is to click on the AI number on
paragraph N(1/2) in the HTML AARM (any Ada 2005 or 2012 version). If you aren't
using the HTML version (why not? :-), you'll have to find it yourself on
Ada-auth.org.

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

From: Bob Duff
Sent: Monday, February 13, 2012  9:24 AM

> and thanks Bob for your suggested additions.

You're welcome.

I think we added the Ada 95 ones toward the end of the project, too.

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

From: John Barnes
Sent: Monday, February 13, 2012  9:39 AM

I assume I have to review this Chg stuff!  Chugg chugg. Some thoughts below.
John

> Here you go:
>
> @ChgToGlossary{Version=[3],Kind=[Added],Term=<predicate>,
> Text=<@ChgAdded{Version=[3],Text=[A predicate is a condition that is
> intended to be True for all objects of a given subtype.]}>}
>
> @ChgToGlossary{Version=[3],Kind=[Added],Term=<precondition>,
> Text=<@ChgAdded{Version=[3],Text=[A precondition is a condition that
> must be True when a given subprogram is called.]}>}

Why must here and intended above? I would say "is assumed to be True" or is
expected to be True

>
> @ChgToGlossary{Version=[3],Kind=[Added],Term=<postcondition>,
> Text=<@ChgAdded{Version=[3],Text=[A postcondition is a condition that
> must be True when a given subprogram returns normally.]}>}

that is promised to be true perhaps

> @ChgToGlossary{Version=[3],Kind=[Added],Term=<assertion>,
> Text=<@ChgAdded{Version=[3],Text=[An assertion is any of the following:
> a pragma Assert, a predicate, a precondition, a postcondition, an
> invariant, a constraint, or a null exclusion. Assertions may be used
> to specify conditions that must be True at run time at certain
> places.]}>}

not must but expected to tbe true perhaps

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

From: Bob Duff
Sent: Monday, February 13, 2012  10:50 AM

> I assume I have to review this Chg stuff!  Chugg chugg.

;-)

Chg stands for "change", as I recall.  You see, we're writing a "program" in a bowdlerized version of Scribe that generates the RM and AARM in PDF, text, HTML, &c.  The commands you see below cause the glossary entries to be alphabetized and change-barred 
and so on.

>... Some thoughts below.

Thanks for reviewing.

> John
>
> > Here you go:
> >
> > @ChgToGlossary{Version=[3],Kind=[Added],Term=<predicate>,
> > Text=<@ChgAdded{Version=[3],Text=[A predicate is a condition that is
> > intended to be True for all objects of a given subtype.]}>}
> >
> > @ChgToGlossary{Version=[3],Kind=[Added],Term=<precondition>,
> > Text=<@ChgAdded{Version=[3],Text=[A precondition is a condition that
> > must be True when a given subprogram is called.]}>}
>
> Why must here and intended above?

Because predicates have loopholes (which you have ranted against in the past).

>... I would say "is assumed to be True" or is  expected to be True

I could live with "expected".  I don't like "assumed", because to me that would
imply that the compiler doesn't need to check the precondition, but can optimize
based on the assumption that it's true.

Or:

A subprogram's precondition is a condition that is required of the caller.

Let Randy decide.

> > @ChgToGlossary{Version=[3],Kind=[Added],Term=<postcondition>,
> > Text=<@ChgAdded{Version=[3],Text=[A postcondition is a condition
> > that must be True when a given subprogram returns normally.]}>}
> >
> that is promised to be true perhaps

"Promised" is OK.  So is "expected".

Or:

A subprogram's postcondition is a condition that is ensured by the subprogram
body.

Randy: not "insured"!  ;-)

> > @ChgToGlossary{Version=[3],Kind=[Added],Term=<assertion>,
> > Text=<@ChgAdded{Version=[3],Text=[An assertion is any of the following:
> > a pragma Assert, a predicate, a precondition, a postcondition, an
> > invariant, a constraint, or a null exclusion. Assertions may be used
> > to specify conditions that must be True at run time at certain
> > places.]}>}
>
> not must but expected to tbe true perhaps

OK.  I still think "must" is also OK, here and above -- if these things aren't
True (at certain places), then something's wrong.

"You must not divide by zero, or your program will crash."
is false, but is approximately true -- good enough for informal stuff.

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

From: Randy Brukardt
Sent: Wednesday, February 15, 2012  7:35 PM

...
> > > @ChgToGlossary{Version=[3],Kind=[Added],Term=<predicate>,
> > > Text=<@ChgAdded{Version=[3],Text=[A predicate is a condition that
> > > is intended to be True for all objects of a given subtype.]}>}
> > >
> > > @ChgToGlossary{Version=[3],Kind=[Added],Term=<precondition>,
> > > Text=<@ChgAdded{Version=[3],Text=[A precondition is a condition
> > > that must be True when a given subprogram is called.]}>}
> >
> > Why must here and intended above?
>
> Because predicates have loopholes (which you have ranted against in
> the past).
>
> >... I would say "is assumed to be True" or is  expected to be True
>
> I could live with "expected".  I don't like "assumed", because to me
> that would imply that the compiler doesn't need to check the
> precondition, but can optimize based on the assumption that it's true.
>
> Or:
>
> A subprogram's precondition is a condition that is required of the
> caller.
>
> Let Randy decide.

I think I'll go with "expected"; it's what I said naturally. I don't mind the alternative precondition description, but the postcondition one is confusing (who's "ensuring" what?). These ought to be understandable by near-idiots, and I think I'm a good jud
ge of that right now -- after several marathon AI creation sessions :-).

...
> > > @ChgToGlossary{Version=[3],Kind=[Added],Term=<assertion>,
> > > Text=<@ChgAdded{Version=[3],Text=[An assertion is any of
> the following:
> > > a pragma Assert, a predicate, a precondition, a postcondition, an
> > > invariant, a constraint, or a null exclusion. Assertions
> may be used
> > > to specify conditions that must be True at run time at certain
> > > places.]}>}
> >
> > not must but expected to tbe true perhaps
>
> OK.  I still think "must" is also OK, here and above -- if these
> things aren't True (at certain places), then something's wrong.
>
> "You must not divide by zero, or your program will crash."
> is false, but is approximately true -- good enough for informal stuff.

I think you're right, but we're not supposed to use "must" in an ISO standard,
and I forget if the Glossary is included in the ISO version or not. So I'd
rather not use "must", and surely "shall" would be wrong here.

I was wondering if the "precondition" and other definitions should somehow
mention that they're "assertions". With our Denver changes to the normative
wording, that should put to rest any misconceptions (say, by your editor :-) on
this point.

I tried:

A predicate is an assertion that is intended to be True for all objects of a
given subtype.

But I've lost the "condition" part of it. Maybe that doesn't matter;
"assertions" say that they can specify a condition. Any better idea?

BTW, when you said "condition", did you mean the syntax term? There isn't any
@nt{} markup in your definitions, but you clearly referenced some syntax terms.

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

From: Randy Brukardt
Sent: Wednesday, February 15, 2012  7:44 PM

...
> I tried:
>
> A predicate is an assertion that is intended to be True for all
> objects of a given subtype.

Pressing "Send" almost always works; a better idea appears immediately. :-)

I used:

A predicate is an assertion that gives a @nt{condition} that is intended to be
True for all objects of a given subtype.

[I think we want "condition" to be the syntax term, so we don't have to put it
into the Glossary itself.]

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

From: Randy Brukardt
Sent: Wednesday, February 15, 2012  7:48 PM

Darn.

I said:
> I used:
>
> A predicate is an assertion that gives a @nt{condition} that is
> intended to be True for all objects of a given subtype.
>
> [I think we want "condition" to be the syntax term, so we don't have
> to put it into the Glossary itself.]

No assertions actually use "condition", so we better not talk about that!
They all use a boolean_expression (which is given the name "assertion
expression", but that would confuse things more here).

So:

A predicate is an assertion that gives a boolean expression that is intended to
be True for all objects of a given subtype.

P.S. I recall we spent nearly as long wordsmithing the Glossary as any other
text for Ada 2005. The above series of messages is why...

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

From: Randy Brukardt
Sent: Wednesday, February 15, 2012  7:54 PM

Arghh!

After smartly using a block substitution to replace "condition" with "boolean
expression", now I have glossary entries for "Preboolean expression" and
"Postboolean expression"! I'm definitely looking forward to finishing this off
(done or not!).

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

From: Bob Duff
Sent: Wednesday, February 15, 2012  7:54 PM

> Pressing "Send" almost always works; a better idea appears
> immediately. :-)

;-)

> I used:
>
> A predicate is an assertion that gives a @nt{condition} that is
> intended to be True for all objects of a given subtype.

That's fine.  Or you could put a new sentence after my wording, "A predicate is
one kind of assertion."

Your call.  Let's not spend too much time futzing around with the glossary.

> I think you're right, but we're not supposed to use "must" in an ISO
> standard, and I forget if the Glossary is included in the ISO version
> or not.

I think we can use whatever we like (including "must") in nonnormative text.

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

From: Bob Duff
Sent: Wednesday, February 15, 2012  8:06 PM

> Darn.

You're overthinking this.

> I said:
> > I used:
> >
> > A predicate is an assertion that gives a @nt{condition} that is
> > intended to be True for all objects of a given subtype.
> >
> > [I think we want "condition" to be the syntax term, so we don't have
> > to put it into the Glossary itself.]
>
> No assertions actually use "condition", so we better not talk about that!
> They all use a boolean_expression (which is given the name "assertion
> expression", but that would confuse things more here).
>
> So:
>
> A predicate is an assertion that gives a boolean expression that is
> intended to be True for all objects of a given subtype.

That's fine, but "condition" in it's normal English sense is fine, too.  I don't
care about the font.  Just do what you see fit.

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

From: Randy Brukardt
Sent: Wednesday, February 15, 2012  8:19 PM

> You're overthinking this.

Maybe, but I know our merry band of nitpickers, too. If I don't pick the nits,
someone else will, and probably when it is too late to fix.

And I fully expect to have to completely redo this after the meeting. I
encourage you to do everything you can to limit the discussion on the glossary
to 30 seconds. :-) (But I doubt you'll succeed.)

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

From: Jeff Cousins
Sent: Thursday, February 16, 2012  3:37 AM

> No problem, your comments are filed in AI95-00437-1 [mail of October 27, 2005].
...

Thanks Randy, that worked!

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

Questions? Ask the ACAA Technical Agent