Author: lwall
Date: 2010-01-23 14:58:17 +0100 (Sat, 23 Jan 2010)
New Revision: 29581
Modified:
docs/Perl6/Spec/S02-bits.pod
docs/Perl6/Spec/S03-operators.pod
docs/Perl6/Spec/S06-routines.pod
docs/Perl6/Spec/S07-iterators.pod
docs/Perl6/Spec/S08-capture.pod
docs/Perl6/Spec/S12-objects.pod
docs/Perl6/Spec/S32-setting-library/Containers.pod
Log:
[Spec] random whackage on List, Seq, Parcel, Capture, Iterator, Nil etc.
List is now simply the iterator role, and doesn't do Positional.
Seq takes over Positional duties for reified (or reifiable) value lists.
Think of Seq now as a constant Array (but also lazy like Array)
Iterable now means you can ask for an iterator, but doesn't do List.
Array, Seq, etc do Iterable, but not List. Only actual iterators do List.
Nil is defined as a suitable sentinel for both list and slice iterators.
Modified: docs/Perl6/Spec/S02-bits.pod
===================================================================
--- docs/Perl6/Spec/S02-bits.pod 2010-01-23 00:04:30 UTC (rev 29580)
+++ docs/Perl6/Spec/S02-bits.pod 2010-01-23 13:58:17 UTC (rev 29581)
@@ -13,8 +13,8 @@
Created: 10 Aug 2004
- Last Modified: 8 Jan 2009
- Version: 195
+ Last Modified: 23 Jan 2009
+ Version: 196
This document summarizes Apocalypse 2, which covers small-scale
lexical items and typological issues. (These Synopses also contain
@@ -560,7 +560,7 @@
Built-in object types start with an uppercase letter. This includes
immutable types (e.g. C<Int>, C<Num>, C<Complex>, C<Rat>, C<Str>,
-C<Bit>, C<Regex>, C<Set>, C<Block>, C<List>,
+C<Bit>, C<Regex>, C<Set>, C<Block>, C<Iterator>,
C<Seq>), as well as mutable (container) types, such as C<Scalar>,
C<Array>, C<Hash>, C<Buf>, C<Routine>, C<Module>, and non-instantiable Roles
such as C<Callable>, C<Failure>, and C<Integral>.
@@ -1147,8 +1147,7 @@
Bool Perl boolean
Exception Perl exception
Block Executable objects that have lexical scopes
- List Lazy Perl list (composed of immutables and iterators)
- Seq Completely evaluated (hence immutable) sequence
+ Seq A list of values (can be generated lazily)
Range A pair of Ordered endpoints
Set Unordered collection of values that allows no duplicates
Bag Unordered collection of values that allows duplicates
@@ -1162,16 +1161,6 @@
Duration The difference between two Instants
HardRoutine A routine that is committed to not changing
-Insofar as Lists are lazy, they're really only partially immutable, in
-the sense that the past is fixed but the future is not. The portion of
-a List yet to be determined by iterators may depend on mutable values.
-When an iterator is called upon to iterate and extend the known part
-of the list, some number of immutable values (which includes immutable
-references to mutable objects) are decided and locked in at that point.
-Iterators may have several different ways of iterating depending on
-the degree of laziness/eagerness desired in context. The iterator
-API is described in S07.
-
C<Instant>s and C<Duration>s are measured in atomic seconds with
fractions. Notionally they are real numbers which may be implemented
in either C<Num> or C<Rat> types. (Fixed-point implementations are
@@ -1202,7 +1191,7 @@
Bool Boolean
Exception Failure
Block Callable
- List Iterable
+ Iterator List
Seq Iterable
Range Iterable
Set Associative[Bool]
@@ -1229,6 +1218,18 @@
clearly distance character strings from bit strings, keeping C<~>/etc for
character strings only and adding an analogy for bit strings.]
+The C<Iterable> role indicates not that you can iterate the type
+directly, but that you can request the type to return an iterator.
+Iterable types may have multiple iterators (lists) running across them
+simultaneously, but an iterator/list itself has only one thread of
+consumption. Every time you do C<get> on an iterator, a value
+disappears from its list.
+
+Types that do the C<List> role are generally hidden from casual view,
+since iteration is typically triggered by context rather than by
+explicit call to the iterator's C<.get> method. Filehandles are a
+notable exception.
+
=head2 Mutable types
Objects with these types have distinct C<.WHICH> values that do not change
@@ -1634,7 +1635,7 @@
C<@x> may be bound to an object of the C<Array> class, but it may also
be bound to any object that does the C<Positional> role, such as a
-C<List>, C<Seq>, C<Range>, C<Buf>, C<Parcel>, or C<Capture>. The C<Positional>
+C<Seq>, C<Range>, C<Buf>, C<Parcel>, or C<Capture>. The C<Positional>
role implies the ability to support C<< postcircumfix:<[ ]> >>.
Likewise, C<%x> may be bound to any object that does the C<Associative>
@@ -1843,7 +1844,7 @@
that cares. It's illegal to use the colon in place of the comma
anywhere except after the first argument.
-Like C<List> objects, C<Capture> objects are immutable in the abstract, but
+C<Capture> objects are immutable in the abstract, but
evaluate their arguments lazily. Before everything inside a C<Capture> is
fully evaluated (which happens at compile time when all the arguments are
constants), the eventual value may well be unknown. All we know is
@@ -1879,7 +1880,9 @@
The empty C<Parcel> is a value with a special name: C<Nil>. It is
the named equivalent of the empty C<()> list. The C<Nil> value is
officially undefined as an item but interpolates as a null list into
-list context, and an empty parcel into slice context.
+list context, and an empty C<Seq> into slice context. An iterator
+can never return C<Nil> as an ordinary value, so it is the sentinel
+value that marks the end of iteration.
Assigning or binding C<Nil> to any scalar container causes the
container to throw out any contents and restore itself to an
@@ -3967,10 +3970,11 @@
There is a "C<list>" operator which imposes a list context on
its arguments even if C<list> itself occurs in a item context.
-In list context, it flattens lazily. In an item context, it returns
-the resulting list as a single C<List> object. (So the C<list> operator
-really does exactly the same thing as putting a list in parentheses with
-at least one comma. But it's more readable in some situations.)
+In list context, it flattens lazily. In an item context, a list is
+turned into a lazy C<Seq> object, that is, an array that can
+extend itself on demand, use the iterators of the list as its new values.
+(Once determined, the values are readonly, however. To create an anonymous
+mutable array, use explicit square brackets around the list.)
To force a non-flattening item context, use the "C<item>" operator.
Modified: docs/Perl6/Spec/S03-operators.pod
===================================================================
--- docs/Perl6/Spec/S03-operators.pod 2010-01-23 00:04:30 UTC (rev 29580)
+++ docs/Perl6/Spec/S03-operators.pod 2010-01-23 13:58:17 UTC (rev 29581)
@@ -15,8 +15,8 @@
Created: 8 Mar 2004
- Last Modified: 21 Jan 2010
- Version: 185
+ Last Modified: 23 Jan 2010
+ Version: 186
=head1 Overview
@@ -250,7 +250,7 @@
Parentheses are parsed on the inside as a semicolon-separated list
of statements, which (unlike the statements in a block) returns the results
-of all the statements concatenated together as a C<List> of C<Capture>.
+of all the statements concatenated together as a C<List> of C<Parcel>.
How that is subsequently treated depends on its eventual binding.
=item *
@@ -2583,7 +2583,7 @@
=item *
Comma C<,> now constructs a C<Parcel> object from its
-operands. In item context this turns into a C<List> object. You have to use
a C<[*-1]> subscript to get the last one.
+operands. In item context this turns into a C<Seq> object. You have to use a
C<[*-1]> subscript to get the last one.
(Note the C<*>. Negative subscripts no longer implicitly count from
the end; in fact, the compiler may complain if you use C<[-1]> on an
object known at compile time not to have negative subscripts.)
@@ -3118,7 +3118,7 @@
These coercions are defined by multi signatures. (Other types may
have different coercion policies.) It is specifically illegal to
-use a C<Range> or a C<List> as implicitly numeric:
+use anything that does C<Iterable> as implicitly numeric:
0 ..^ 10 # 0 .. 9
0 .. ^10 # ERROR
@@ -3395,7 +3395,7 @@
Actual type Use entries for
=========== ===============
- List Seq Array
+ Iterator Seq Array
KeySet KeyBag KeyHash Hash
named values created with
Class, Enum, or Role,
@@ -3867,7 +3867,7 @@
this happens only on the "dwimmy" side.
On the non-dwimmy side, any scalar value that does not know how to
-do C<List> will be treated as a list of one element, and for infix
+do C<Iterable> will be treated as a list of one element, and for infix
operators must be matched by an equivalent one-element list on the
other side. That is, a hyper operator is guaranteed to degenerate
to the corresponding scalar operation when all its arguments are
@@ -3902,21 +3902,21 @@
# == [[5, 6], [8, 9]]
More generally, a dwimmy hyper operator works recursively for any object
-matching the C<Each> role even if the object itself doesn't support
+matching the C<Iterable> role even if the object itself doesn't support
the operator in question:
Bag(3,8,[2,Seq(9,3)],8) >>->> 1; # Bag(2,7,[1,Seq(8,2)],7)
Seq(3,8,[2,Seq(9,3)],8) >>->> (1,1,2,1); # Seq(2,7,[0,Seq(7,1)],7)
-In particular, tree node types with C<Each> semantics enable visitation:
+In particular, tree node types with C<Iterable> semantics enable visitation:
- $tree.».foo; # short for $tree.foo, $tree.each: { .».foo }
+ $tree.».foo; # short for $tree.foo, $tree.list: { .».foo }
If not all nodes support the operation, you need a form of it that
specifies the call is optional:
- $tree.».?foo; # short for $tree.?foo, $tree.each: { .».?foo }
- $tree.».*foo; # short for $tree.*foo, $tree.each: { .».*foo }
+ $tree.».?foo; # short for $tree.?foo, $tree.list: { .».?foo }
+ $tree.».*foo; # short for $tree.*foo, $tree.list: { .».*foo }
You are not allowed to define your own hyper operators, because they
are supposed to have consistent semantics derivable entirely from
Modified: docs/Perl6/Spec/S06-routines.pod
===================================================================
--- docs/Perl6/Spec/S06-routines.pod 2010-01-23 00:04:30 UTC (rev 29580)
+++ docs/Perl6/Spec/S06-routines.pod 2010-01-23 13:58:17 UTC (rev 29581)
@@ -951,12 +951,12 @@
|(x=>1); # Pair, becomes \(x=>1)
|{x=>1, y=>2}; # Hash, becomes \(x=>1, y=>2)
-C<List> (also C<Seq>, C<Range>, etc.) are simply turned into
+Anything else that is C<Iterable> is simply turned into
positional arguments:
|(1,2,3); # Seq, becomes \(1,2,3)
|(1..3); # Range, becomes \(1,2,3)
- |(1..2, 3); # List, becomes \(1,2,3)
+ |(1..2, 3); # Parcel, becomes \(1,2,3)
|([x=>1, x=>2]); # List (from an Array), becomes \((x=>1), (x=>2))
For example:
@@ -2042,7 +2042,7 @@
A C<Signature> object can be introspected to find out the details of
the parameters it is defined as expected. The C<.params> method will
-return a C<List> of C<Parameter> objects, which have the following
+return a C<Parcel> of C<Parameter> objects, which have the following
readonly properties:
name The name of the lexical variable to bind to, if any
Modified: docs/Perl6/Spec/S07-iterators.pod
===================================================================
--- docs/Perl6/Spec/S07-iterators.pod 2010-01-23 00:04:30 UTC (rev 29580)
+++ docs/Perl6/Spec/S07-iterators.pod 2010-01-23 13:58:17 UTC (rev 29581)
@@ -14,8 +14,8 @@
Created: 27 Nov 2008
- Last Modified: 22 Jan 2010
- Version: 7
+ Last Modified: 23 Jan 2010
+ Version: 8
=head1 Laziness and Eagerness
@@ -160,9 +160,9 @@
provides the same laziness level of the first example.
-=head1 The Iterator Role
+=head1 The List Role
-The iterator role represents the lazy access to a list, walking through:
+The C<List> role represents the lazy access to a list, walking through:
=over
@@ -176,10 +176,9 @@
=back
-It's important to realize that the iterator of a list can be accessed
-by the .Iterator() method (but only the runtime will be calling that
-most of the time), and the implementation of each iterator is private
-to the list and implementation specific.
+It's important to realize that the iterator of a list is the list
+itself; Perl does not distinguish the two concepts. Any type
+that supports the C<List> 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
@@ -191,11 +190,16 @@
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.
+to build a slice. While building a list, the items will be flattened.
-When it runs out of items, it will return C<Nil>.
+When it runs out of items, it will return C<Nil>. List context
+always removes C<Nil> values as part of flattening, while slice
+context always promotes parcels to C<Seq>, so it is never possible
+for this method to return C<Nil> as a value. We can use C<Nil> as
+the sentinel because iterators never return C<Parcel>s. and C<Nil>
+is defined as the empty C<Parcel>.
-=head1 The Iterator::PushBack Role
+=head1 The List::PushBack Role
This role defines an iterator that knows how to receive values back to
be consumed again as if they were never consumed. The iterator is free
@@ -210,13 +214,13 @@
original order or if it wasn't consumed. In that case, it should fail
with UnorderedPushBackException or BadPushBackException.
-=head1 The Iterator::Unshift Role
+=head1 The List::Unshift Role
This role defines an iterator that can receive new elements in the top
of the stack, it works like pushback, but it should be able to store
objects that are completely new to this stream. Either by being backed
by a mutable list or by providing a local stack. This role implies
-Iterator::PushBack, where pushback will be handled by unshift.
+List::PushBack, where pushback will be handled by unshift.
The purpose of defining two different Roles is to give the user the
"expect to fail" or "expect to succeed" semantics.
@@ -229,7 +233,7 @@
=head1 Auxiliary Implementations
Perl's built-ins require that a number of auxiliary types implement
-Iterators. These are available for general use, and are instantiated
+Lists. These are available for general use, and are instantiated
by ending a feed at a scalar, array, or sliced array.
=head2 Generic Item Iterator
@@ -331,8 +335,8 @@
The generic lazy slice consumes the C<Capture>s from an iterator but
stores the results as a bi-dimensional list, where the first dimension
corresponds to an iteration, and the second contains the values in
-the C<Capture> returned for that iteration. Empty C<Capture>s are
-stored just like the rest of the iterations.
+the C<Parcel> returned for that iteration, but turned into a C<Seq> object.
+Empty C<Parcel> objects are turned into empty C<Seq> objects.
To obtain a generic lazy slice, end a feed in a sliced C<Positional>.
Modified: docs/Perl6/Spec/S08-capture.pod
===================================================================
--- docs/Perl6/Spec/S08-capture.pod 2010-01-23 00:04:30 UTC (rev 29580)
+++ docs/Perl6/Spec/S08-capture.pod 2010-01-23 13:58:17 UTC (rev 29581)
@@ -13,8 +13,8 @@
Created: 20 Sep 2009
- Last Modified: 20 Sep 2009
- Version: 1
+ Last Modified: 23 Jan 2010
+ Version: 2
=head1 Introduction
@@ -37,11 +37,11 @@
Captures and Parcels are also the basis for the multidimensionality of
lists in Perl 6. Unlike Perl 5, no flattening happens unless it's
-explicitly required by the user, which is done by enforcing the List
-context. If you use the scalar context the dimensionality should be
+explicitly required by the user, which is done by enforcing the list
+context. If you use the item context the dimensionality should be
preserved.
-In addition to the List and Scalar context, there's also a special
+In addition to the list and item context, there's also a special
context, which is, in a simplified way, called "Capture context", but
it actually means "deferred context", in a way that the Capture or
Parcel is kept as-is while they are manipulated in the code. This is
Modified: docs/Perl6/Spec/S12-objects.pod
===================================================================
--- docs/Perl6/Spec/S12-objects.pod 2010-01-23 00:04:30 UTC (rev 29580)
+++ docs/Perl6/Spec/S12-objects.pod 2010-01-23 13:58:17 UTC (rev 29581)
@@ -13,8 +13,8 @@
Created: 27 Oct 2004
- Last Modified: 8 Jan 2010
- Version: 96
+ Last Modified: 23 Jan 2010
+ Version: 97
=head1 Overview
@@ -388,9 +388,9 @@
form may dispatch to a list of candidates if C<$candidates> is either
a list or a special C<Code> object representing a partial dispatch to a
list of candidates. If C<$candidates> (or any element of C<@candidates>)
-is a List or Array object it is expanded out recursively until C<Callable>
+is an iterable object it is expanded out recursively until C<Callable>
candidates are found. The call fails if it hits a candidate that is
-neither C<Callable> nor expandable.
+not C<Callable>, C<Iterable>, or C<List>.
Another form of indirection relies on the fact that operators are named
using a variant on hash subscript notation, which gives you these forms:
@@ -906,7 +906,7 @@
@object»!meth(@args) # calls private method on each
The return value is a list with exactly the same number of elements
-as C<@object>. Each such return value is a C<Capture> or C<List> of
C<Captures>
+as C<@object>. Each such return value is a C<Parcel> or C<List> of C<Parcel>
as specified above for the non-hyper "dot" variants.
Hyperoperators treat a junction as a scalar value, so saying:
Modified: docs/Perl6/Spec/S32-setting-library/Containers.pod
===================================================================
--- docs/Perl6/Spec/S32-setting-library/Containers.pod 2010-01-23 00:04:30 UTC
(rev 29580)
+++ docs/Perl6/Spec/S32-setting-library/Containers.pod 2010-01-23 13:58:17 UTC
(rev 29581)
@@ -67,7 +67,7 @@
=item roundrobin
- our List multi roundrobin( *@@list )
+ our Parcel multi roundrobin( *@@list )
C<roundrobin> is very similar to C<zip>. The difference is that
C<roundrobin> will not stop on lists that run out of elements but
@@ -82,8 +82,8 @@
=item zip
- our List of Parcel multi zip ( *@@list )
- our List of Parcel multi infix:<Z> ( *@@list )
+ our Parcel of Parcel multi zip ( *@@list )
+ our Parcel of Parcel multi infix:<Z> ( *@@list )
zip takes any number of arrays and returns one tuple for every index.
This is easier to read in an example:
@@ -108,7 +108,7 @@
for @a Z @b Z @c -> $a, $b, $c {...}
-In C<@@> context a List of Array is returned instead of flat list.
+In C<@@> context an Array of Array is returned instead of flat list.
=back
@@ -116,7 +116,7 @@
The following are defined in the C<List> role/class:
- role List does Container does Positional {...}
+ role List does Container {...}
=over
@@ -124,13 +124,13 @@
our List multi method new(*...@args)
-Constructs a C<List> containing the arguments passed to the C<new> method.
+Constructs an C<List> that can visit all iterable elements of the all the
arguments.
=item list
our List sub list(*...@args)
-Constructs a C<List> containing the arguments passed to the C<list> subroutine.
+Constructs an C<List> that can visit all iterable elements of the all the
arguments.
=item cat
@@ -750,11 +750,11 @@
=head2 Seq
- class Seq does Positional {...}
+ class Seq does Positional does Iterable {...}
=head2 Range
- class Range does Positional {
+ class Range does Positional does Iterable {
method from() {...}
method to() {...}
method min() {...}
@@ -993,7 +993,7 @@
=item !eigenstates
- method !eigenstates (Junction $j: --> List)
+ method !eigenstates (Junction $j: --> Parcel)
Returns an unordered list of the values that constitute the junction (formerly
called C<.values>). It flattens nested junctions of the same type, so
