Document PositionalBindFailover

Also cleanup type-graph.txt a bit, and remove outdated class names
from the Cool documentation

Author: moritz

lib/Type/Cool.pod

@@ -20,8 +20,8 @@ C<Int> converts the integer to C<Str> first.
 The following built-in types inherit from C<Cool>:
 L<Array> L<Backtrace> L<Bag> L<Baggy> L<Bool> L<Complex> L<Cool>
 L<Duration> L<Enumeration> L<EnumMap> L<FatRat> L<Hash> L<Instant>
-L<Int> L<Iterable> L<Iterator> L<KeyHash> L<KeySet> L<List>
-L<ListIter> L<LoL> L<MapIter> L<Nil> L<Num> L<Numeric> L<Parcel>
+L<Int> L<KeyHash> L<KeySet> L<List>
+L<Nil> L<Num> L<Numeric> L<Parcel>
 L<Range> L<Real> L<Seq> L<Set> L<Stash> L<Str> L<Stringy>
 
 The following table summarizes the methods that C<Cool> provides, and

lib/Type/PositionalBindFailover.pod

@@ -0,0 +1,52 @@
+=begin pod
+
+=TITLE role PositionalBindFailover
+
+=SUBTITLE Failover for binding an Iterable to a Positional
+
+    role PositionalBindFailover { ... }
+
+This role provides an interface by which an L<Iterable|/type/Iterable> can
+be coerced into a L<Positional|/type/Positional>, so that you can for example
+write:
+
+    sub fifths (@a) {       # @a is constraint to Positional
+        @a[4];
+    }
+    my $seq := gather {     # a Seq, which is not Positional
+        take $_ for 1..*;
+    }
+    say fifths($seq);       # 5
+
+The invocation of C<fifths> in the example above would oridinarly give a type
+error, because C<$seq> is of type L<Seq|/type/Seq>, whhich doesn't do the
+L<Positional|/type/Positional> interface that the C<@>-sigil implies.
+
+But the signature binder recognizes that C<Seq> does the
+C<PositionalBindFailover> role, and calls its C<cache> method to coerce it to
+a L<List|/type/List>, which does the C<Positional> role.
+
+
+=head1 Methods
+
+=head2 method cache
+
+    method cache(PositionalBindFailover:D:) returns List:D
+
+Returns a L<List|/type/List> based on the C<iterator> method, and caches it.
+Subsequent calls to C<cache> always return the same C<List> object.
+
+=head2 method list
+
+    method list(PositionalBindFailover:D:) returns List:D
+
+Returns a L<List|/type/List> based on the C<iterator> method without caching it.
+
+=head2 method iterator
+
+    method iterator(PositionalBindFailover:D:) { ... }
+
+This method stub ensure that a class implementing role
+C<PositionalBindFailover> provides an C<iterator> method.
+
+=end pod

type-graph.txt

@@ -58,6 +58,7 @@ class Variable                      is Any
 class Proxy                         is Any
 class Cool                          is Any
 class Bool                          is Cool
+class Nil                           is Cool
 
 [Basic]
 # Callables
@@ -186,26 +187,20 @@ class Thread
 
 [Composite]
 # Collections: Iteration
-class Iterable                      is Any
-class Iterator                      is Iterable
-# Nil maybe should be a Basic type?
-class Nil                           is Iterator is Cool
-class GatherIter                    is Iterator
-class ListIter                      is Iterator
-class MapIter                       is Iterator
-class HashIter                      is Iterator
+role  Iterable
+role  Iterator
+role  PositionalBindFailover
+class Seq                           is Cool        does Iterable does PositionalBindFailover
 
 [Composite]
 # Collections: Positional
 role  Positional[::T = Mu]
 role  Blob[::T = uint8]             does Positional[T] does Stringy
 role  Buf[::T = uint8]              does Blob[T]
 class Capture
-class Parcel                        is Cool        does Positional
-class Range                         is Iterable is Cool does Positional
-class List                          is Iterable is Cool does Positional
+class Range                         is Cool        does Positional does Iterable
+class List                          is Cool        does Positional does Iterable
 class Array                         is List
-class LoL                           is List
 role  TypedArray[::TValue]                         does Positional[TValue]
 
 [Composite]