=begin pod :kind("Type") :subkind("class") :category("basic")

=TITLE class Submethod

=SUBTITLE Member function that is not inherited by subclasses

    class Submethod is Routine {}

A Submethod is a method that is not inherited by child classes. They are
typically used for per-class initialization and tear-down tasks which
are called explicitly per class in an inheritance tree, usually for
enforcing a particular order. For example object construction with the
C<BUILD> submethod happens from the least-derived to most-derived, so
that the most-derived (child) classes can depend on the parent already
being initialized.

Submethods are of type C<Submethod>, and are declared with the
C<submethod> declarator:

    class Area {
        has $.size;
        submethod BUILD(:$x, :$y, :$z) {
            $!size = $x * $y * $z;
        }
    }

Since submethods are not inherited, an interesting use case is precisely
methods that are going to be called from the I<standard> submethods such as
C<BUILD> or C<TWEAK>.

=begin code
class Hero {
    has @.inventory;
    has Str $.name;
    submethod BUILD( :$!name, :@!inventory ) {
        @!inventory = self.clean-inventory( @!inventory );
    }
    submethod clean-inventory( @inventory ) {
        @!inventory.unique.sort
    }
}

my Hero $þor .= new( name => "Þor",
                     inventory => ( "Mjölnir", "Megingjörð", "Mjölnir" ) );
say $þor.inventory;
# OUTPUT: «[Megingjörð Mjölnir]␤»
=end code

Invoking these methods make sense only in the specific context of the
submethod it is invoked from.

=head1 Methods

=head2 method gist

Defined as:

    multi method gist(Submethod:D:)

Returns the name of the submethod.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
