Rework containers.pod

closes #139

Author: moritz

lib/Language/containers.pod

@@ -80,6 +80,19 @@ is equivalent to
         method attr() is rw { $!attr }
     }
 
+Scalar containers are transparent to type checks and most kinds of read-only
+accesses. A C<.VAR> makes them visible:
+
+    my $x = 42;
+    say $x.^name;       # Int
+    say $x.VAR.^name;   # Scalar
+
+And C<is rw> on a parameter requires the presence of a writable Scalar
+container:
+
+    sub f($x is rw) { say $x };
+    f 42;   # Parameter '$x' expected a writable container, but got Int value
+
 =head2 Binding
 
 Next to assignment, Perl 6 also supports I<binding> with the C<:=> operator.
@@ -116,7 +129,7 @@ There are a number of positional container types with slightly different
 semantics in Perl 6. The most basic one is L<List|/type/List>
 It is created by the comma operator.
 
-    say (1, 2, 3).WHAT;     # (List)
+    say (1, 2, 3).^name;    # List
 
 A list is immutable, which means you cannot change the number of elements
 in a list. But if one of the elements happens to be a scalar container,
@@ -154,11 +167,12 @@ the same thing: discard the old value(s), and enter some new value(s).
 
 Nevertheless, it's easy to observe how different they are:
 
-    my $x = 42; say $x.WHAT;    # (Int)
-    my @a = 42; say @a.WHAT;    # (Array)
+    my $x = 42; say $x.^name;   # Int
+    my @a = 42; say @a.^name;   # Array
 
 This is because the C<Scalar> container type hides itself well, but C<Array>
-makes no such effort.
+makes no such effort. Also assignment to an array variable is coercive, so
+you can assign a non-array value to an array variable.
 
 To place a non-C<Array> into an array variable, binding works:
 
@@ -182,7 +196,8 @@ at run time).
 
 The answer is that binding to array elements is recognized at the syntax
 level and instead of emitting code for a normal binding operation, a special
-method on the array is called that knows how to do the binding itself.
+method (called C<BIND-KEY>) is called on the array. This method handles binding
+to array elements.
 
 Note that, while supported, one should generally avoid directly binding
 uncontainerized things into array elements.  Doing so may produce
@@ -200,135 +215,46 @@ a thing happening accidentally.
 
 =head2 Flattening, items and containers
 
-The C<%> and C<@> sigils in Perl 6 generally indicate flattening. Hence
-flattening list context iterates over them as if there were no container
-boundary:
-
-    my @a = 1, 2, 3;
-    my @b = @a, 4, 5;
-    say @b.elems;               # 5
-    say @b.join: '|';           # 1|2|3|4|5
-
-Here C<@a> is flattened out in the second line.
+The C<%> and C<@> sigils in Perl 6 generally indicate multiple values
+to an iteration construct, whereas the C<$> sigil indicates only one value.
 
-Item containers prevent flattening, thus allowing the programmer to write
-nested data structures.
+    my @a = 1, 2 3;
+    for @a { };         # 3 iterations
+    my $a = (1, 2, 3);
+    for $a { };         # 1 iteration
 
-The following examples all do the same and do not flatten:
+Contrary to earlier versions of Perl 6, and to Perl 5, C<@>-sigiled variables
+do not flatten in list context:
 
     my @a = 1, 2, 3;
-    my @b = @a.item, 4, 5;
-       @b = $(@a), 4, 5;
-       @b = $@a, 4, 5;
-       @b = [1, 2, 3], 4, 5;
-
-    my $item = @a;
-       @b = $item, 4, 5;
-
-    say @b.perl;            # Array.new([1, 2, 3], 4, 5);
-
-C<[...]> creates an itemized array, and C<Array.new(...)> a non-itemized
-array.
-
-There is a slight exception though: if you call a method on an itemized
-container, it will generally behave as if it weren't itemized. So C<[1, 2,
-3].join(',')> produces C<"1,2,3"> as a result, as one might hope.
-
-This also means that calling the C<.list> method flattens out an itemized
-container:
-
-   my $item = [1, 2, 3];
-   my @b = $item.list, 4, 5;    # 5 elems
-      @b = @($item), 4, 5;      # a shortcut
-      @b = @$item, 4, 5;        # another shortcut
-
-Other methods on lists also return flat lists, so for example
-
-   my $item = [1, 2, 3];
-   my @b = $item.sort, 4, 5;    # 5 elems
-
-sorts the elements of C<$item> and then returns a list that is flattened out
-in the array assignment.
-
-Note that C<.list> de-itemizes only the invocant; it does not recursively
-flatten the whole data structure. For example in
-
-    my @a = [1, [2, 3, 4]].list;
-    say @a.elems;               # 2
-
-the C<.list> only de-itemizes the outer brackets, the inner ones create an
-array that is stored in the second element of the Array and is not touched
-by C<.list>.
-
-=head3 Non-flattening contexts
-
-In the examples above, it was always assignment to an array variable that
-flattened out non-itemized arrays. However, sometimes you want to preserve
-the structure.
-
-The most common case (and one of the reasons for the whole flattening vs.
-non-flattening distinction to exist) is to have some list-like operator that
-could conceivably return either a flat list, or a list of lists.  Consider
-the zip operator C<Z>, which takes an element from each list like a zipper:
-
-    my @left  = <a b c>;
-    my @right = 1, 2, 3;
-
-    my @flat = @left Z @right;
-    my @tree = (@left Z @right).tree;
-
-The expression C<@left Z @right> returns C<(('a', 1), ('b', 2), ('c', 3))>.
-In a flattening context like array assignment, that flattens out into a list
-of 6 elements, C<('a', 1, 'b', 2, 'c', 3)>. But if you want to preserve the
-structure, you can append C<.tree>, and it returns the array
-
-    ['a', 1], ['b', 2], ['c', 3]
-
-On the other hand, assigning (or binding) to a scalar preserves the
-structure without itemizing any inner arrays or lists:
-
-    my $x = (<a b c> Z <D E F>);
-    say $x.perl;                # (("a", "D"), ("b", "E"), ("c", "F")).list.item
-
-Again C<.tree> can turn the inner parcels into "hard", itemized arrays:
-
-    say $x.tree.perl;           # (["a", "D"], ["b", "E"], ["c", "F"]).list
+    my @b = @a, 4, 5;
+    say @b.elems;               # 3
 
-What happens when you call C<$x.list>?
+There are operations that flatten out sublists that are not inside a scalar
+container: slurpy parameters (C<*@a>) and explicit calls to C<flat>:
 
-    say $x.list.perl;           # (("a", "D"), ("b", "E"), ("c", "F")).list
 
-It just returned the same object without the outer C<.item> container, but
-didn't look inside the list. If that's what you want, there is another
-utility method called C<flat>:
+    my @a = 1, 2, 3;
+    say (flat @a, 4, 5).elems;  # 5
 
-    say $x.flat.perl            # ("a", "D", "b", "E", "c", "F").list
+    sub f(*@x) { @x.elems };
+    say f @a, 4, 5;             # 5
 
-To reiterate the previous point: C<.list> only removes the itemization (or
-scalar container) of the invocant, whereas C<.flat> walks the elements of
-the invocant and removes their itemization (note that both methods don't
-modify the invocant object; they just return a modified copy).
+As hinted above, scalar containers prevent that flattening:
 
-=head3 What flattens, what doesn't?
+    sub f(*@x) { @x.elems };
+    say f $@a, 4, 5;            # 3
 
-In general, operations that have to iterate the list usually flatten the
-list.  Other operations don't. Here is a list of a few operations that
-flatten:
+The C<@> character can also be used as a prefix to remove a scalar container:
 
-=item .map, .grep, .first
-=item Iteration with "for"
-=item .join
-=item assignment to an array variable
-=item assignment to a hash variable
+    my $x = (1, 2, 3);
+    .say for @$x;               # 3 iterations
 
-And a few that don't flatten:
+Methods generally don't care whether their invocant is in a scalar, so
 
-=item Indexing with [$idx]
-=item .elems
-=item .tree
+    my $x = (1, 2, 3);
+    $x.map(*.say);              # 3 iterations
 
-The first two cannot flatten, otherwise it would be very hard to get access
-to the structure that's actually stored in the list and the whole
-point of C<.tree> is not to flatten.
+maps over a list of three elements, not of one.
 
 =end pod