CVS difference for ai12s/ai12-0009-1.txt

Differences between 1.4 and version 1.5
Log of other versions for file ai12s/ai12-0009-1.txt

--- ai12s/ai12-0009-1.txt	2015/10/12 20:44:31	1.4
+++ ai12s/ai12-0009-1.txt	2016/03/22 22:47:27	1.5
@@ -119,7 +119,7 @@
      (Listing : Directory_Listing)
       return Directory_Iterators.Forward_Iterator'Class;
       Iterate returns a forward iterator object (see 5.5.1) that will generate a
-      value for a loop parameter (see 5.5.2) designating each directory entry in Listing, 
+      value for a loop parameter (see 5.5.2) designating each directory entry in Listing,
       starting with the first directory entry and moving the cursor as per the
       Next function. The iterator object needs finalization.
 
@@ -135,7 +135,7 @@
     the current state of the generalized iterator or container element iterator.
     It is implementation-defined as to whether the results returned by this
     subprogram are altered if the contents of the directory are altered during
-    the current iteration of the loop (for example, by another program). The 
+    the current iteration of the loop (for example, by another program). The
     exception Use_Error is propagated if the external environment does not
     support continued searching of the directory represented by Entries.
 
@@ -230,7 +230,7 @@
    function Iterate
      (Variables : Environment_Variable_Listing)
       return Environment_Variable_Iterators.Forward_Iterator'Class;
- 
+
    Iterate returns a forward iterator object (see 5.5.1) that will generate a
    value for a loop parameter (see 5.5.2) designating each environment variable
    in Variables, starting with the first environment variable and moving the
@@ -335,7 +335,7 @@
    begin
       for Dir_Entry in Listing.Iterate loop
          Put_Line
-           (Directories.Simple_Name 
+           (Directories.Simple_Name
               (Directories.Current_Entry (Entries => Listing,
                                           EP      => Dir_Entry)));
       end loop;
@@ -343,7 +343,7 @@
 
 It was also considered whether the container and the iterator type should
 be the same type. This seemed more confusing and would have required exposing
-more of the iterator interface in the public part of the package. It also 
+more of the iterator interface in the public part of the package. It also
 would have been less clear whether one could restart an iteration on the
 same container object a second time.
 
@@ -1299,8 +1299,8 @@
 For now, disregard my comment in my previous email about providing a
 User_Callable aspect. I don't think it is warranted here.
 
-I think we want to expose Iterate and Current_Entry as user callable. 
-This allows one to write both forms of generalized iterator loops. 
+I think we want to expose Iterate and Current_Entry as user callable.
+This allows one to write both forms of generalized iterator loops.
 (Using "in" or "of" in the loop iterator_specification)
 
 ****************************************************************
@@ -1309,21 +1309,256 @@
 Sent: Monday, October 12, 2015  3:43 PM
 
 > Here is an updated version to replace what I submitted yesterday.
-> This version eliminates the "bug" where I was assuming I could defer 
-> the Contant_Indexing function and Default_Iterator functions to the 
+> This version eliminates the "bug" where I was assuming I could defer
+> the Contant_Indexing function and Default_Iterator functions to the
 > private part of the packages.
 
 I corrected a couple of typos in this as I was posting it. Specifically,
 
 ...
-> I also renamed Identity to Iterate, as Identity is no longer true and 
-> Iterate is more consistent with the naming we use on other existing 
+> I also renamed Identity to Iterate, as Identity is no longer true and
+> Iterate is more consistent with the naming we use on other existing
 > containers.
 
 The Default_Iterator aspect was still set to Identity in A.16(36/3). You
 certainly meant that to be Iterate as well.
 
 Also, !question should be !problem in an !Amendment class AI.
+
+****************************************************************
+
+From: Jeff Cousins
+Sent: Sunday, January 3, 2016  1:59 PM
+
+> Jeff Cousins: AI12-0009-1 (check wording in /03 version)
+
+There seems to have been a generalised replacement of key-words by their bold
+lower-case version, this has resulted in some sentences beginning with a
+lower-case letter, e.g.:
+
+for generalized loop iteration
+
+if Pattern is the null string
+
+when Start_Search propagates
+
+At the meeting we said that type Entry_Presence should be private not new
+Boolean.  Presumably the same for type Variable_Presence too.
+
+type Directory_Listing
+
+The description of this seems a bit short compared with that for type
+Environment_Variable_Listing.  Maybe insert a middle sentence "For generalized
+loop iteration (see 5.5.2), an object of the type Directory_Listing can be an
+iterable container object for the loop that will generate a forward container
+element iterator as the loop iterator and a loop cursor designating each
+environment variable of the execution environment."  Otherwise it looks a bit
+odd referring to a cursor in the descriptions of Entries and Iterate when the
+cursor hasn't yet been introduced to the reader.
+
+function Current_Entry
+
+There are rather a lot of "and"s and "or"s in the first sentence, maybe it needs
+a few commas.
+
+type Environment_Variable_Listing is tagged limited private
+
+   with Constant_Indexing => Current_Entry,
+
+should be
+
+type Environment_Variable_Listing is tagged limited private
+
+   with Constant_Indexing => Current_Variable,
+
+Personally, I would prefer All_Environment_Variables to All_Variables.
+
+function Current_Variable
+
+Presumably the return type should be Name_Value_Pair_Type not Name_Value_Pair.
+
+type Name_Value_Pair_Type
+
+Spurious } in the description.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Thursday, January 7, 2016  10:39 PM
+
+Like Jeff, I had an action item to review the wording in AI12-0009-1.
+Presumably Brad will use our comments to create his next update. I'm not going
+to look too carefully at Jeff's comments; Brad can get to reconcile them (that's
+a lot of fun and I'm glad I don't have to do it here). [BTW, when I say "you" in
+here, I'm talking about the AI author, that is, Brad.]
+
+As discussed, Entry_Presence should be private. Replace:
+
+   type Entry_Presence is new Boolean;
+
+   function Has_Element
+     (EP : in Entry_Presence) return Boolean is (Boolean (EP));
+
+By:
+
+   type Entry_Presence is private;
+
+   function Has_Element
+     (EP : in Entry_Presence) return Boolean;
+
+Note that we'll need a definition of what Has_Element does somewhere. BTW, I'd
+rename it to Has_Entry, since there is nothing named "Element" around here, just
+a bunch of Entries.
+
+Later, you have:
+
+   function Entries
+     (Directory : in String;
+      Pattern   : in String;
+      Filter    : in Filter_Type := (others => True))
+       return Directory_Listing;
+
+   For generalized loop iteration (see 5.5.2), Entries returns an iterable
+   container object for the loop that will generate a forward container element
+   iterator as the loop iterator and a loop cursor designating each available
+   directory entry in the return object. ...
+
+I don't understand this sentence. Entries does whatever it does in any context,
+so I don't see what "generalized loop iteration" has to do with anything.
+Directory_Listing is an iterable container object by definition, and how that
+works is defined by the Ada language (Iterate is called, etc.). So this is the
+sort of "says nothing" sentence that we're trying to get rid of in the Standard.
+I think you want to say something introductory rather than normative to start
+with, maybe something like:
+
+   Function Entries returns an object that can be used in generalized loop
+   iteration (see 5.5.2) to visit each available directory entry.
+
+And then continue with the details of how that gets done.
+
+I see Jeff suggested going in the other direction. I don't agree with that, but
+he might be right that the introductory text is better put on the type
+Directory_Listing. That is, something like:
+
+   An object of type Directory_Listing can be used in generalized loop iteration
+   (see 5.5.2) to visit each available directory entry for a particular
+   directory search.
+
+We certainly don't need to say anything about how that happens; that's obvious
+from the aspects declared on the type declaration (at least if you're familiar
+with 5.5.1 and 5.5.2, and we can assume that in the RM).
+
+Then the description of Entries should echo that of Start_Search:
+
+   Returns an object that represents the result of a search in the directory
+   named by Directory for entries matching Pattern and Filter.
+
+As always, Simplify! (That's a lot easier to say as a reviewer than as an
+author. So please don't throw that back at me on my next AI ;-)
+
+---
+
+function Current_Entry:
+
+... or is not involved in generalized loop iteration ...
+
+Huh?? What does this mean? The default state is that there is no entries, so if
+it's not iterating, there are no entries. So there doesn't seem to be any need
+to mention this (which is good, 'cause it's nonsense - we don't care how the
+object is used, just that the sequence of calls makes sense).
+
+---
+
+A.16(125.a/3):
+
+    Implementation Advice: Directories.Start_Search{,} [and ]
+    Directories.Search{, and Entries} should raise Name_Error for malformed
+    patterns.
+
+The existing routines here give the package name, and the new one ought to as
+well - "Directories.Entries". This is the entry in the Implementation Advice
+annex, and a reader of that will not have any idea where this comes from, thus
+we have to be explicit.
+
+---
+
+As Jeff mentions, "Variable_Presence" should be changed like "Entry_Presence"
+was above. And I'd change Has_Element to "Has_Pair" or "Has_Variable" or
+something like that.
+
+---
+
+   type Name_Value_Pair_Type is limited private;
+
+   The type Name_Value_Pair_Type represents a single environment variable of
+   the execution environment. These items can only be created by generalized
+   loop iteration on the return object of the All_Variables function
+   in this package}. Information about the item can be obtained from the
+   functions declared in this package. A default-initialized object of this
+   type is invalid; objects returned by generalized loop iteration on the
+   result of Entries are valid.
+
+"These items can only be created by generalized loop iteration..."?? Huh? It
+looks to me like you can get some by calling All_Variables and then calling
+Current_Variable. As usual, anything that generalized iteration can do can be
+done explicitly!
+
+I'd probably focus on the use (which you did in the first sentence); the second
+and third sentences are obvious from the specification, so I'd just drop them.
+
+---
+
+Environment_Variable_Listing: Again, simply and point out that it *can* be used
+in a generalized loop iteration, but surely there is no requirement to do so.
+And repeating the whole business about how those work doesn't add anything not
+in the spec. The less English, the better!
+
+My comments on "Entries" apply to "All_Variables" as well.
+
+---
+
+The wording for Current_Variable depends on the previous fact that
+Variable_Presence is Boolean rather than private. And again, what the heck does
+"involved in generalized loop iteration" mean? What matters is the sequence of
+calls to All_Variables, Iterator, Current_Variable, and so on.
+
+---
+
+A.17(25): you've got "involve" on the brain! Just say "have":
+
+It is a bounded error to call Value {if the call does not have a parameter of
+type Name_Value_Pair_Type,} if more than one environment variable exists with
+the given name; the possible outcomes are that:
+
+---
+
+A.17(28/2):
+
+Again, you're ignoring the possibility of explicitly calling routines to create
+and use an object of Environment_Variable_Listing. It's irrelevant how the
+object got created or how it is being used, you'll need some abstract way to
+describe the state of when an object of that type is in use (between a call to
+Iterate and when Has_Pair becomes False).
+
+---
+
+Jeff wrote:
+
+>There seems to have been a generalised replacement of key-words by
+>their bold lower-case version, this has resulted in some sentences
+>beginning with a lower-case letter, e.g.:
+>
+>	for generalized loop iteration
+>
+>	if Pattern is the null string
+>
+>	when Start_Search propagates
+
+That's the same problem J-P complained about for AI12-0144-1. The autoformatter
+for AIs cannot handle the format of typical library subprogram definitions, as
+it starts with some code and then is followed by some indented text. *Never*
+worry about the formatted output -- *always* look at the raw text version before
+complaining about the "pretty" format.
 
 ****************************************************************
 

Questions? Ask the ACAA Technical Agent