=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 ordinarily give a type
error, because C<$seq> is of type L<Seq|/type/Seq>, which 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
