=begin pod

=TITLE role Callable

=SUBTITLE Invocable code object

    role Callable { ... }

Role for objects which support calling them. It's used in L<Block>,
L<Routine>, L<Sub>, L<Method>, L<Submethod> and L<Macro> types.

Callables can be stored in C<&>-sigiled containers, the default type constraint
of such a container is C<Callable>. A signature object can be used to
force a check against the signature of the Callable to be stored into the
container.

    my &a = {;}; # Empty block needs a semicolon
    my &b = -> {};
    my &c = sub () {};
    sub foo() {};
    my &d = &foo;
for code :skip-test
my &f:(Int) = sub bar(Int) {}; # Not yet implemented
my &f:(Str) = -> Str {};       # Not yet implemented

=head1 Methods

=head2 method assuming

    method assuming(Callable:D $self: |primers)

Returns a C<Callable> that implements the same behaviour as the
original, but has the values passed to .assuming already bound to the
corresponding parameters.

    my sub slow($n){ my $i = 0; $i++ while $i < $n; $i };

    # takes only one parameter and as such wont forward $n
    sub bench(&c){ c, now - ENTER now };

    say &slow.assuming(10000000).&bench;
    # OUTPUT«(10000000 7.5508834)␤»

=comment according to design docs it's Callable but in rakudo it's assuming is in Block

=head1 Operators

=head2 C«infix:<∘>»
X<|∘,function combinator>X<|o,function combinator>

The function combinator C«infix:<∘>» or C«infix:<o>» combines two functions, so
that the left function is called with the return value of the right function.
The number of return values of the right function has to match the arity of the
left function.

    sub f($p){ say 'f'; $p / 2 }
    sub g($p){ say 'g'; $p * 2 }
    my &f-g = &f ∘ &g;
    say f-g(2); # OUTPUT«g␤f␤2␤»

=end pod
