The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Kavorka-0.039
River stage two • 15 direct dependents • 30 total dependents
33 ++
/ Kavorka::Sub

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, 2017 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.