Author: lwall
Date: 2009-04-20 10:30:10 +0200 (Mon, 20 Apr 2009)
New Revision: 26302
Modified:
docs/Perl6/Spec/S07-iterators.pod
docs/Perl6/Spec/S32-setting-library/IO.pod
Log:
[S32] add limit to lines
[S07] refine get/iterator semantics; fix typos
Modified: docs/Perl6/Spec/S07-iterators.pod
===================================================================
--- docs/Perl6/Spec/S07-iterators.pod 2009-04-20 08:27:47 UTC (rev 26301)
+++ docs/Perl6/Spec/S07-iterators.pod 2009-04-20 08:30:10 UTC (rev 26302)
@@ -6,12 +6,12 @@
=head1 Version
- Maintainer: ???
+ Maintainer: *
Contributions: Tim Nelson <wayl...@wayland.id.au>
Daniel Ruoso <dan...@ruoso.com>
Date: 27 Nov 2008
- Last Modified: 19 Apr 2008
- Version: 4
+ Last Modified: 20 Apr 2008
+ Version: 5
=head1 Laziness and Eagerness
@@ -32,12 +32,15 @@
=item Strictly Lazy
Does not evaluate anything unless explictly required by the user,
-including not traversing non-lazy objects.
+including not traversing non-lazy objects. This behavior is generally
+available only by pragma or by explicit programming with non-lazy
+primitives.
=item Mostly Lazy
Try to obtain available items without causing eager evaluation of
-other lazy objects.
+other lazy objects. However, the implementation is allowed to do batching
+for efficiency.
=item Mostly Eager
@@ -47,16 +50,18 @@
=item Strictly Eager
Obtain all items, fail in data structures known to be infinite.
+This behavior is generally available only by pragma or by explicit
+programming primitives.
=back
-It's important to realize that the responsability of determining the
-level of lazyness/eagerness in each operation is external to each lazy
+It's important to realize that the responsibility of determining the
+level of laziness/eagerness in each operation is external to each lazy
object, the runtime, depending on which operation is being performed,
-is going to assume the level of lazyness and perform the needed
+is going to assume the level of laziness and perform the needed
operations to apply that level.
-=head2 The lazyness level of some common operations
+=head2 The laziness level of some common operations
=over
@@ -91,7 +96,7 @@
=back
But it's important to notice that eagerness takes precedence over
-lazyness, meaning that
+laziness, meaning that
my @a = grep { ... } <== map { ... } <== grep { ... } <== 1, 2, 3
@@ -111,7 +116,7 @@
my @b <== map { ... }, @c;
my @a = grep { ... }, @b;
-provides the same lazyness level of the first example.
+provides the same laziness level of the first example.
=head1 The Iterator Role
@@ -142,11 +147,11 @@
=head2 method get {...}
-Returns the items for that iteration. The grouping of elements
+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.
-When it runs out of items, it will throw an OutOfItemsException.
+When it runs out of items, it will return C<Nil>.
=head1 The Iterator::PushBack Role
Modified: docs/Perl6/Spec/S32-setting-library/IO.pod
===================================================================
--- docs/Perl6/Spec/S32-setting-library/IO.pod 2009-04-20 08:27:47 UTC (rev
26301)
+++ docs/Perl6/Spec/S32-setting-library/IO.pod 2009-04-20 08:30:10 UTC (rev
26302)
@@ -17,8 +17,8 @@
Daniel Ruoso <dan...@ruoso.com>
Lyle Hopkins <webmas...@cosmicperl.com>
Date: 19 Feb 2009 extracted from S29-functions.pod; added stuff from
S16-IO later
- Last Modified: 13 Apr 2009
- Version: 5
+ Last Modified: 20 Apr 2009
+ Version: 6
The document is a draft.
@@ -830,6 +830,7 @@
=item lines
method lines ($handle:
+ Any $limit = *,
Bool :$bin = False,
Str :$enc = "Unicode",
Any :$nl = "\n",
@@ -838,6 +839,7 @@
) is export
multi lines (Str $filename,
+ Any $limit = *,
Bool :$bin = False,
Str :$enc = "Unicode",
Any :$nl = "\n",
@@ -845,10 +847,29 @@
--> List
)
-Returns all the lines of a file as a C<List> regardless of context.
+Returns some or all the lines of a file as a C<List> regardless of context.
See also C<slurp>. Note that lists are lazy by default, but you
-can always ask for C<eager lines>.
+can always ask for C<eager lines>. Note that the limit semantics cannot be
+duplicated by subscripting, since
+ $fh.lines[^5]
+
+reads all the lines before the subscript gives you the first five,
+whereas
+
+ $fh.lines(5)
+
+reads only five lines from the handle. Note that
+
+ $fh.lines(1)
+
+is equivalent to
+
+ $fh.get
+
+If fewer lines are available than the limit, it is not an error;
+you just get the number of lines available.
+
=item slurp
method slurp ($handle:
