NAME

       Kavorka::Sub - a function that has been declared

DESCRIPTION

       Kavorka::Sub is a role which represents a function declared using Kavorka. Classes
       implementing this role are used to parse functions, and also to inject Perl code into
       them.

       Instances of classes implementing this role are also returned by Kavorka's function
       introspection API.

   Introspection API
       A function instance has the following methods.

       "keyword"
           The keyword (e.g. "method") used to declare the function.

       "package"
           Returns the package name the parameter was declared in. Not necessarily the package it
           will be installed into...

              package Foo;
              fun UNIVERSAL::quux { ... }  # will be installed into UNIVERSAL

       "is_anonymous"
           Returns a boolean indicating whether this is an anonymous coderef.

       "declared_name"
           The declared name of the function (if any).

       "qualified_name"
           The name the function will be installed as, based on the package and declared name.

       "signature"
           An instance of Kavorka::Signature, or undef.

       "traits"
           A hashref of traits.

       "prototype"
           The function prototype as a string.

       "attributes"
           The function attributes. The structure returned by this method is subject to change.

       "body"
           The function body as a coderef. Note that this coderef will have had the signature
           code injected into it.

   Other Methods
       "parse", "parse_subname", "parse_signature", "parse_traits", "parse_prototype",
       "parse_attributes", "parse_body"
           Internal methods used to parse a subroutine. It only makes sense to call these from a
           Parse::Keyword parser, but may make sense to override them in classes consuming the
           Kavorka::Sub role.

       "allow_anonymous"
           Returns a boolean indicating whether this keyword allows functions to be anonymous.

           The implementation defined in this role returns true.

       "signature_class"
           A class to use for signatures.

       "default_attributes"
           Returns a list of attributes to add to the sub when it is parsed.  It would make sense
           to override this in classes implementing this role, however attributes don't currently
           work properly anyway.

           The implementation defined in this role returns the empty list.

       "default_invocant"
           Returns a list invocant parameters to add to the signature if no invocants are
           specified in the signature. It makes sense to override this for keywords which have
           implicit invocants, such as "method".  (See Kavorka::Sub::Method for an example.)

           The implementation defined in this role returns the empty list.

       "forward_declare_sub"
           Method called at compile time to forward-declare the sub, if that behaviour is
           desired.

           The implementation defined in this role does nothing, but Kavorka::Sub::Fun actually
           does some forward declaration.

       "install_sub"
           Method called at run time to install the sub into the symbol table.

           This makes sense to override if the sub shouldn't be installed in the normal Perlish
           way. For example Kavorka::MethodModifier overrides it.

       "invocation_style"
           Returns a string "fun" or "method" depending on whether subs are expected to be
           invoked as functions or methods. May return undef if neither is really the case (e.g.
           as with method modifiers).

       "inject_attributes"
           Returns a string of Perl code along the lines of ":foo :bar(1)" which is injected into
           the Perl token stream to be parsed as the sub's attributes. (Only used for named
           subs.)

       "inject_prelude"
           Returns a string of Perl code to inject into the body of the sub.

       "bypass_custom_parsing"
           A class method that is called when people attempt to use the keyword while bypassing
           the Perl keyword API's custom parsing.  Examples of how they can do that are:

              use Kavorka 'method';

              &method(...);

              __PACKAGE__->can("method")->(...);

           The default implementation of "bypass_custom_parsing" is to croak, but this can be
           overridden in cases where it may be possible to do something useful.
           (Kavorka::MethodModifier does this.)

           It is passed the name of the keyword, the name of the package that the keyword was
           installed into, and an arrayref representing @_.

BUGS

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

SEE ALSO

       Kavorka::Manual::API, Kavorka::Signature.

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.