Author: lwall
Date: 2010-02-02 18:51:25 +0100 (Tue, 02 Feb 2010)
New Revision: 29618
Modified:
docs/Perl6/Spec/S07-iterators.pod
Log:
[S07] pick slightly less misleading names for iteration primitives
stop using item to mean contradictory things
remove confusing discussion of outer flat/slice context; these methods don't
care because that's why there are different method names for get vs getobj
Modified: docs/Perl6/Spec/S07-iterators.pod
===
--- docs/Perl6/Spec/S07-iterators.pod 2010-02-02 17:32:50 UTC (rev 29617)
+++ docs/Perl6/Spec/S07-iterators.pod 2010-02-02 17:51:25 UTC (rev 29618)
@@ -14,8 +14,8 @@
Created: 27 Nov 2008
-Last Modified: 29 Jan 2010
-Version: 9
+Last Modified: 2 Feb 2010
+Version: 10
=head1 Laziness and Eagerness
@@ -180,62 +180,57 @@
itself; Perl does not distinguish the two concepts. Any type
that supports the CList role is an iterator.
-This is a minimal API that should allow custom iterator
-implementations, but this spec should be expanded in the future to
-provide additional API for batch-aware iterators.
-
The methods in this role are:
=head2 method get {...}
-Returns the next item for that iteration. The grouping of elements
-returned in each iteration is visible if this iterator is being used
-to build a slice. While building a list, the items will be flattened.
+Used to iterator over a flat list (the context supplied by a slurpy binding).
+Returns the next element from the iterator after flattening any leading parcel.
-When it runs out of items, it will fail with the CEMPTY exception.
+When it runs out of elements, it will fail with the CEMPTY exception.
As with most failures, it is generally returned without throwing it,
unless the calling lexical scope requests it to be thrown via use fatal.
No list should ever contain the CEMPTY exception, since iterational
control flow should always terminate when that value is returned.
-This method provides list context to the iterator.
+=head2 method batch ($max?) {...}
-=head2 method getsome ($max?) {...}
+Used to iterate over a flat list when you wish to return an arbitrary
+number of elements at a time. The returned set of elements is guaranteed
+not to contain any CParcel objects, since any such CParcel will
+be flattened before returning its elements.
-Returns a batch of items in some appropriate CPositional type that
+Returns the batch of elements in some appropriate CPositional type that
numerifies to the exact number of items returned. (The type may also
be CIterable in its turn.) Also returns CEMPTY if no arguments
are available; the CEMPTY exception should return 0 when numerified
-to facilitate numeric end testing if that is desired.
+to facilitate numeric end testing if that is desired. If C$max is
+not supplied, the iterator may choose a suitable batch size.
This method provides list context to the iterator.
-=head2 method getitem {...}
+=head2 method getobj {...}
-Returns the next item for that iteration. The grouping of elements
-returned in each iteration is visible if this iterator is being used
-to build a slice. While building a list, the items will be flattened.
+Returns the next parcel or other object from the iterator without
+any flattening. It is used both for binding to positional parameters
+in item context as well as variadically retrieving slice elements in
+slice context.
-When it runs out of items, it will fail with the CEMPTY exception.
+When it runs out of objects, it will fail with the CEMPTY exception.
As with most failures, it is generally returned without throwing it,
unless the calling lexical scope requests it to be thrown via use fatal.
No list should ever contain the CEMPTY exception, since iterational
control flow should always terminate when that value is returned.
-This method provides item context to the iterator, which is also
-used as slice context in the variadic region.
+=head2 method batchobj ($max?) {...}
-=head2 method getsomeitems ($max?) {...}
-
-Returns a batch of items in some appropriate CPositional type that
+Returns a batch of parcels/objects in some appropriate CPositional type that
numerifies to the exact number of items returned. (The type may also
be CIterable in its turn.) Also returns CEMPTY if no arguments
are available; the CEMPTY exception should return 0 when numerified
-to facilitate numeric end testing if that is desired.
+to facilitate numeric end testing if that is desired. If C$max is
+not supplied, the iterator may choose a suitable batch size.
-This method provides item context to the iterator, which is also
-used as slice context in the variadic region.
-
=head1 The List::PushBack Role
This role defines an iterator that knows how to receive values back to
