NAME

       Kavorka::Manual::MultiSubs - multi subs and multi methods

DESCRIPTION

       Kavorka supports multi methods and multi subs:

          multi method process (ArrayRef $x) { say "here" }
          multi method process (HashRef $x) { say "there" }

          __PACKAGE__->process( [] );    # here
          __PACKAGE__->process( {} );    # there

       Multi subs and multi methods must be named (cannot be anonymous coderefs).

       This feature is shared with Perl 6 signatures, though Kavorka does not support some of
       Perl 6's more advanced features such as multi method prototypes. (Though method modifiers
       should more or less work with multi methods!) Kavorka includes both type constraints and
       value constraints in the dispatch decision, while Perl 6 only uses type constraints.

   Multi methods versus multi subs
       The word after "multi" (i.e. "method" in the above example) can be any Kavorka keyword
       that has been set up in the current lexical scope, provided the implementation class
       provides a non-undef "invocation_style" method (see Kavorka::Sub).

       If the "invocation_style" is "fun" (like Kavorka::Sub::Fun), then the signature of each
       candidate function in package is checked in the order in which they were defined, and the
       first matching candidate is dispatched to.

       If the "invocation_style" is "method" (like Kavorka::Sub::Method), then if no successful
       candidate is found in the current class, candidates in superclasses are also considered.

   Long names
       It is possible to define alternative "long names" for the candidates of a multi method or
       multi sub using the ":long" attribute:

          multi fun process (ArrayRef $x) :long(process_array) {
             say "here";
          }

          multi fun process (HashRef $x) :long(process_hash) {
             say "there";
          }

          process($a);          # multi dispatch
          process_array($b);    # single dispatch
          process_hash($c);     # single dispatch

       (Actually, ":long" isn't a real attribute; we just borrow the syntax. If you try to use
       attributes' introspection stuff, you won't find it.)

       Prototypes, subroutine attributes, etc. declared on the multi subs will appear on the
       "long name" subs, but not the multi sub.

   Definition at run time
       Multi subs and multi methods are added to the symbol at run time (like methods, see "The
       Method Name" in Kavorka::Manual::Methods).

       This means that it's possible to partly define a multi sub, call it, then further define
       it, before calling it again.

          use Kavorka qw( multi fun );
          use Try::Tiny;

          multi fun plus_one (Int $x) { $x + 1 }

          try {
             plus_one(41);      # 42
             plus_one(1.1);     # throws
          };

          multi fun plus_one (Num $x) { $x + 1 }

          plus_one(41);      # 42
          plus_one(1.1);     # 2.1

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::Functions, Kavorka::Manual::Methods.

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.