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 @_.

AUTHOR

Toby Inkster <[email protected]>.

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.