Routine.pod

=begin pod

=TITLE class Routine

    class Routine is Block { }

A C<Routine> is a code object meant for larger unities of code than L<Block>.
Routine is the common superclass for L<Sub> and L<Method>, the two primary
code objects for code reuse.

Routines serve as a scope limiter for C<return> (ie a C<return> returns
from the innermost outer Routine).

Routine is also the level at which multiness (multi subs and multi methods)
are handled.

=head1 Methods

=head2 multi

    method multi(Routine:D:) returns Bool:D

Returns C<True> if the routine is a multi sub or method.

=head2 candidates

    method candidates(Routine:D:) returns Positional:D

Returns a list of multi candidates, or a one-element list with itself
if it's not a multi

=head2 wrap

    method wrap(Routine:D: &wrapper)

Wraps (ie in-place modifies) the routine. That means a call to this routine
first calls C<&wrapper>, which then can (but doesn't have to) call the
original routine with the C<callsame>, C<callwith>, C<nextsame> and
C<nextwith> dispatchers. The return value from the routine is also
the return value from the wrapper.

C<wrap> returns a wrap handler, which you can pass to L<unwrap> to restore
the original routine.

=head2 unwrap

    method unwrap(Routine:D: $wraphandler)

Restores the original routine after it has been wrapped with L<wrap>.

=head2 yada

    method yada(Routine:D:) returns Bool:D

Returns C<True> if the routine is a stub

    say (sub f() { ... }).yada      # True
    say (sub g() { 1;  }).yada      # False

=end pod