Second pass at list-centric page

Author: skids

doc/Language/list.pod

@@ -12,7 +12,8 @@ an elegant system for handling them.
 
 =head1 Literal Lists
 
-Literal lists are created with C<,> B<not> with parentheses, so:
+Literal L<C<List>s|/type/List>> are created with commas B<not> with
+parentheses, so:
 
     1,2         # This is two-element list
     (1,2)       # This is also a list, in parenthesis
@@ -45,8 +46,8 @@ C<List> into an C<@>-sigiled variable, you can use binding with C<:=> instead.
     my @a := 1,2,3;
 
 One of the ways C<@>-sigiled variables act like lists is by always supporting
-<positional subscripting|/language/subscripts>.  Anything bound to a C<@>-sigiled
-value must support the L</type/positional> role which guarantees this:
+L<positional subscripting|/language/subscripts>.  Anything bound to a C<@>-sigiled
+value must support the L<Positional|/type/Positional> role which guarantees this:
 
     my @a := 1; # Type check failed in binding; expected Positional but got Int
 
@@ -72,12 +73,32 @@ it knows a sequence is infinite, but it cannot always know.
 
 =comment TODO link or describe C<...>
 
-Just because you are still allowed to subscript a C<Seq> does not mean it
-promises to keep values around after you have used them.  If you have a very
-long sequence, you may want to throw old values away so that memory does
-not fill up.
+Although the C<Seq> class does provide some positional subscripting, it does
+not provide the full interface of C<Positional>, so an C<@>-sigiled variable
+may B<not> be bound to a C<Seq>.
 
-=comment TODO document .iterator, .list and .cache
+    my @s := (loop { 42.say }); # Error expected Positional but got Seq
+
+This is because the C<Seq> does not keep values around after you have used them.
+This is useful behavior if you have a very long sequence, as you may want to
+throw values away after using them, so that your program does not fill up memory.
+
+On the other hand, you may want to keep old values around in some cases.
+It is possible to hide a C<Seq> inside a C<List>, which will still be lazy,
+but will remember old values -- this is done by calling the C<.list> method.
+Since this C<List> fully supports C<Positional>, you may bind it directly
+to an C<@>-sigiled variable.
+
+    my @s := (loop { 42.say }).list;
+    @s[2]; # Says 42 three times
+    @s[1]; # does not say anything
+    @s[4]; # Says 42 two more times
+
+You may also use the C<.cache> method instead of C<.list>, depending
+on how you want the references handled.  See the C<page on C<Seq>|/type/Seq>
+for details.
+
+=comment TODO document .iterator
 
 =head2 Slips
 
@@ -101,7 +122,7 @@ or re-bind existing elements:
     (1,2,3)[0] := 0;   # Error Cannot use bind operator with this left-hand side
     (1,2,3)[0] = 0;    # Error Cannot modify an immutable Int
 
-However, if any of the elements is wrapped in a L<C<Scalar>|/types/Scalar> you
+However, if any of the elements is wrapped in a L<C<Scalar>|/type/Scalar> you
 can still change the value which that C<Scalar> points to:
 
     my $a = 2;
@@ -135,7 +156,6 @@ you may flatten the list to produce a sequence of values as if all parentheses.
 This works no matter how many levels deep the parenthesis are nested.
 
     say (1,(2,(3,4)),5).flat eqv (1,2,3,4,5) # says True
-    for (1,(2,(3,4)),5).flat { .say }        #
 
 This is not really a syntactical "context" as much as it is a process of
 iteration, but it has the appearence of a context.
@@ -155,7 +175,7 @@ flattening:
 =head2 Argument List (Capture) Context
 
 When a list appears as arguments to a function or method call, special
-syntax rules are at play: the list immediately is converted into a
+syntax rules are at play: the list is immediately converted into a
 C<Capture>.  A C<Capture> itself has a List (C<.list>) and a Hash (C<.hash>).
 Any C<Pair> literals whose keys are not quoted, or which are not parenthesized,
 never make it into C<.list>.  Instead, they are considered to be named
@@ -164,16 +184,16 @@ for the details of this processing.
 
 Consider the following ways to make a new C<Array> from a C<List>.  These ways
 place the C<List> in an argument list context and because of that, the C<Array>
-only contains C<1> and C<2> but not the C<pair> C<:c3>, which is ignored.
+only contains C<1> and C<2> but not the C<Pair> C<:c(3)>, which is ignored.
 
-    Array.new(1, 2, :c(3);
+    Array.new(1, 2, :c(3));
     Array.new: 1, 2, :c(3);
     new Array: 1, 2, :c(3);
 
 In contrast, these ways do not place the C<List> in argument list context,
 so all the elements, even the C<Pair> C<:c(3)>, are placed in the C<Array>.
 
-    Array.new((1, 2, :c(3));
+    Array.new((1, 2, :c(3)));
     (1, 2, :c(3)).Array;
     my @a = 1, 2, :c(3); Array.new(@a);
     my @a = 1, 2, :c(3); Array.new: @a;
@@ -195,11 +215,28 @@ as named parameters:
 
 =comment TODO actualy not sure if there is anything special here, other then the internal itemization best left for later -- eager maybe?
 
-=head2 Slice Context
+=head2 Slice Indexing Context
+
+From the perspective of the C<List> inside a L<slice subscript|/language/subscripts#Slices>,
+is only remarkable in that it is unremarkable: because
+L<adverbs|/language/subscripts#Adverbs> to a  slice are attached after the C<]>,
+the inside of a slice is B<not> an argument list, and no special processing
+of pair forms happens.
+
+Most C<Positional> types will enforce an integer coercion on each element
+of a slice index, so pairs appearing there will generate an error, anyway:
+
+    (1,2,3)[1, 2, :c(3)] # Method 'Int' not found for invocant of class 'Pair'
+
+...however this is entirely up to the type -- if it defines an order
+for pairs, it could consider C<:c(3)> a valid index.
 
-    (1,2,3)[1, 2, :c(3)]
+Indices inside a slice are usually not automatically flattened, but
+neither are sublists usually coerced to C<Int>.  Instead, the list structure
+is kept intact, causing a nested slice operation that replicates the
+structure in the result:
 
-=comment TODO there is a typecheck against key/index, anything else?
+    say ("a","b","c")[(1,2),(0,1)] eqv (("b", "c"), ("a", "b")) # says True
 
 =head1 Arrays