=encoding utf8

=head1 TITLE

DRAFT: Synopsis 32: Setting Library - Callable

=head1 AUTHORS

    Tim Nelson <wayland@wayland.id.au>
    Larry Wall <larry@wall.org>

=head1 VERSION

    Created: 26 Feb 2009

    Last Modified: 3 May 2009
    Version: 2

The document is a draft.

If you read the HTML version, it is generated from the Pod in the pugs
repository under /docs/Perl6/Spec/S32-setting-library/Callable.pod so edit it there in
the SVN repository if you would like to make changes.

This document documents Code, Block, Signature, Capture, Routine, Sub, Method, Submethod,
and Macro.

=head1 Roles

=head2 Callable

    role Callable {...}

The C<Callable> role implies the ability
to support C<< postcircumfix:<( )> >>.

=head2 Code

    # Base class for all executable objects
    role Code {
        method Signature signature() {...}
        method Code      assuming(...) {...}
        method           do() {...} # See L<S12/Introspection>
        method Bool defined {...}
        # XXX What does do() return?  I mean, it's a "method body", but what's that?
    }

For C<Code>, the C<.defined> method returns whether a body has
been defined.  A body consisting only of C<...>, C<!!!>, or C<???>
(with optional message arguments) does not count as defined.

To test if a name has been declared, look up the symbol in the
appropriate symbol table.

=head2 Block

    # Executable objects that have lexical scopes
    role Block does Code does Callable {
        method next() {...}
        method last() {...}
        method redo() {...}
        method leave() {...}
        method labels() {...}
        method as() {...} # See L<S12/Introspection> and L<S02/Value types>
    }

=head2 Signature

 # Function parameters (left-hand side of a binding)
 role Signature {...}

=head2 Capture

 # Function call arguments (right-hand side of a binding)
 role Capture does Positional does Associative {...}

=head2 WrapHandle

 role WrapHandle {...}

=head1 Classes

=head2 Routine

 class Routine does Block {
      method WrapHandle wrap(Code $code) {...}
      method Routine    unwrap(Wraphandle $original) {...}
      method Str        name() {...}
      method Bool       multi() {...}
 }

=over

=item unwrap

See L<S06/Wrapping>.

=item wrap

 method wrap(Code $code) {...}

See L<S06/Wrapping>.

=back

=head2 Sub

    class Sub isa Routine {...}

=head2 Method

    class Method isa Routine {...}

=head2 Submethod

    class Submethod isa Routine {...} # XXX or should this be isa Sub

=head2 Macro

    class Macro isa Routine {...}

=head1 Additions

Please post errors and feedback to perl6-language.  If you are making
a general laundry list, please separate messages by topic.