NAME

       Kavorka::Manual::Methods - method/classmethod/objectmethod keywords

DESCRIPTION

       Kavorka provides the "method", "classmethod" and "objectmethod" keywords for the purpose of defining
       methods.

       The anatomy of a method:

       1.  The keyword introducing the method.

       2.  The method name (optional).

       3.  The signature (optional).

       4.  Traits (optional).

       5.  The prototype (optional).

       6.  The attribute list (optional).

       7.  The method body.

       Example:

          #  (1)    (2)    (3)    (4)     (5)  (6)     (7)
             method foobar ($foo) is cool :($) :cached { return $foo + $self->bar }

          #          (1)    (6)
             my $m = method { return $_[0] + $self->bar };

   The Keyword
       By default, only the "method" keyword is exported. The others can be exported by request:

          use Kavorka qw( method classmethod objectmethod );

   The Method Name
       If  present, it specifies the name of the method being defined. If no name is present, the declaration is
       an expression that evaluates to a reference to the method in question.

       Although methods are compiled at compile-time (and variables are closed over then), methods are installed
       into the class at run-time. So this works:

          if ($ENV{DEBUG}) {
             method foobar { ... }
          }
          else {
             method foobar { ... }
          }

       It is possible to add the method to the class at compile time using the "begin" trait:

          method foobar but begin { ... }

       This may be useful for role composition, if roles are composed before methods are defined, but the  roles
       require certain methods to exist in your class.

       It is possible to define lexical (i.e. truly private) methods using a lexical variable for a method name:

          objectmethod get_name () {
             return $self->{name};
          }
          objectmethod my $set_name (Str $new) {
             $self->{name} = $new;
          }

          $obj->$set_name("Bob");
          $obj->get_name;            # Bob

       See also: Lexical::Accessor.

   The Signature
       See Kavorka::Manual::Signatures.

       The  "method" keyword has a default invocant called $self, but it does not have a type constraint, so can
       equally be used for class or object methods. The "objectmethod" keyword works the same, but does define a
       type constraint for $self, requiring it to be a blessed object.  The  "classmethod"  keyword  defines  an
       invocant called $class which has a type constraint requiring it to be a string.

       In any case, it is perfectly possible to define your own name and type constraint for the invocant:

          method foo ( ClassName $me: Int $foo ) { ... }

   Traits
       See Kavorka::Manual::ExtendingKavorka.

       Two traits for methods are bundled with Kavorka: "override" and "fresh".

       The  "fresh"  trait  will  throw  an  exception  if  the  method  you  are defining already exists in the
       inheritance hierarchy for this class.  The idea of this trait is to increase safety when subclassing.

       Suppose a future release of your parent class adds a new method with the same name as one of  yours,  but
       differing  functionality;  your  method  would  normally  override  the one in the parent class. With the
       "fresh" trait, an exception would be thrown, giving you opportunity to resolve the conflict.

       The "override" trait does the opposite; it will throw an exception if the method being defined  does  not
       already exist.

   The Prototype
       See Kavorka::Manual::PrototypeAndAttributes.

       Note however that prototypes are fairly useless for methods.

   The Attributes
       Attributes may alternatively be provided before the signature.

       See Kavorka::Manual::PrototypeAndAttributes.

       The  "method",  "objectmethod"  and  "classmethod"  keywords automatically add the ":method" attribute to
       methods.

   The Method Body
       This is more or less what you'd expect from the method body you'd write with  sub,  however  the  lexical
       variables for parameters are pre-declared and pre-populated, and invocants have been shifted off @_.

BUGS

       Please report any bugs to <http://rt.cpan.org/Dist/Display.html?Queue=Kavorka>.

SEE ALSO

       Kavorka::Manual,           Kavorka::Manual::Signatures,          Kavorka::Manual::PrototypeAndAttributes,
       Kavorka::Manual::MultiSubs, Kavorka::Manual::MethodModifiers.

AUTHOR

       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

       This software is copyright (c) 2013-2014 by Toby Inkster.

       This is free software; you can redistribute it and/or modify it under  the  same  terms  as  the  Perl  5
       programming language system itself.

DISCLAIMER OF WARRANTIES

       THIS  PACKAGE  IS  PROVIDED  "AS  IS"  AND  WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
       LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

perl v5.24.1                                       2016-12-15                      Kavorka::Manual::Methods(3pm)