=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 CALL-ME

    method CALL-ME(Callable:D $self: |arguments)

This method is required for postfix:«( )» and postfix:«.( )». It's what makes
an object actually call-able and needs to be overloaded to let a given object
act like a routine. If the object needs to be stored in a C<&>-sigiled
container, is has to implement Callable.

    class A does Callable {
        submethod CALL-ME(|c){ 'called' }
    }
    my &a = A;
    say a(); # OUTPUT: «called␤»

=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 composition operator C«infix:<∘>» or C«infix:<o>» combines two functions, so
that the left function is called with the return value of the right function.
If the L«C<.count>|/routine/count» of the left function is greater than 1, the return
value of the right function will be L<slipped|/type/Slip> into the left function.

Both C<.count> and C<.arity> of the RHS will be maintained.

    sub f($p){ say 'f'; $p / 2 }
    sub g($p){ say 'g'; $p * 2 }

    my &composed = &f ∘ &g;
    say composed 2; # OUTPUT: «g␤f␤2␤»
    # equivalent to:
    say 2.&g.&f;
    # or to:
    say f g 2;

    =begin code
    sub f($a, $b, $c) { [~] $c, $b, $a }
    sub g($str){ $str.comb }
    my &composed = &f ∘ &g;
    say composed 'abc'; # OUTPUT: «cba␤»
    # equivalent to:
    say f |g 'abc';
    =end code

=end pod
