=begin pod

=TITLE class Capture

=SUBTITLE Argument list suitable for passing to a L<Signature>

    class Capture does Positional does Associative { }

A Capture is a container for passing arguments to a code object.  Captures
are the flip-side of Signatures -- Captures at the caller define arguments,
while Signatures at the callee define parameters.

When you call C<print $a, $b>, the C<$a, $b> part is a Capture.

Captures contain a list-like part for positional arguments and a hash-like
part for named arguments.  For the named arguments, Captures use a slightly
different I<syntax> than a normal List.  There are two easy ways to make a
named argument: 1) use an unquoted key naming a parameter, followed by C<'=>'>,
followed by the argument and 2) use a colon-pair literal named after the
parameter:

    say unique 1, -2, 2, 3, as => { abs $_ }; # 1, -2, 3
    # ... is the same thing as:
    say unique 1, -2, 2, 3, :as({ abs $_ });  # 1, -2, 3
    # Be careful not to quote the name of a named parameter:
    say unique 1, -2, 2, 3, 'as' => { abs $_ }; # 1, -2, 2, 3, "as" => { ... }

A stand-alone Capture can also be made, stored, and used later.  A literal
Capture can be created by prefixing a term with a backslash C<\>.
Commonly, this term will be a List of terms, from which any Pair
literal will be placed in the named part, and all other terms will be
placed in the positional part.

    my $c = \42;            # Capture with one positional parts
    $c = \(1, 2, a => 'b'); # Capture with two positional and one named part

To use such a Capture, you may use C<'|'> before it in a function call, and it
will be as if the values in the Capture were passed directly to the function
as arguments -- named arguments will be passed as named arguments and positional
arguments will be passed as positional arguments.  You may re-use the Capture
as many times as you want, even with different functions.

    my $c = \(4,2,3);
    reverse(|$c).say; # 3 2 4
    sort(5,|$c).say;  # 2 3 4 5

Inside a Signature, a Capture may be created by prefixing a sigilless parameter
with a vertical bar C<|>.  This packs the remainder of the argument list
into that parameter.

    f(1, 2, 3, a => 4, b => 5);
    sub f($a, |c) {
        # c  is  \(2, 3, a => 4, b => 5)
    }

Note that Captures are still Lists in that they may contain containers, not
just values:

    my $b = 1;
    my $c = \(4,2,$b,3);
    sort(|$c).say;        # 1 2 3 4
    $b = 6;
    sort(|$c).say;        # 2 3 4 6

=head1 Methods

=head2 method list

Defined as:

    method list(Capture:D:) returns Positional

Usage:

    CAPTURE.list

Returns the positional part of the Capture.

=head2 method hash

Defined as:

    method hash(Capture:D:) returns Associative

Usage:

    CAPTURE.hash

Returns the named/hash part of the Capture.

=head2 method elems

Defined as:

    method elems(Capture:D:) returns Int:D

Usage:

    CAPTURE.elems

Returns the number of positional elements in the Capture.

=end pod
