=pod
=encoding utf-8
=for stopwords invocant invocants lexicals unintuitive yada globals
=head1 NAME
Kavorka::Manual::MethodModifiers - before/after/around keywords
=head1 DESCRIPTION
Kavorka provides the C<before>, C<after> and C<around> keywords for
method modifiers.
Method modifiers should work in L<Moose>, L<Moo>, L<Mouse> and
L<Role::Tiny> classes and roles. In other classes they will fall back
to using L<Class::Method::Modifiers>.
The keywords C<augment> and C<override> are also available, but will
only work in classes backed by a framework that supports these
modifiers (i.e. L<Moose> or L<Mouse>, but I<not> L<Moo>).
The anatomy of a method modifier:
=over
=item 1.
The keyword introducing the method.
=item 2.
The method names.
=item 3.
The signature (optional).
=item 4.
Traits (optional).
=item 5.
The prototype (optional).
=item 6.
The attribute list (optional).
=item 7.
The modifier body.
=back
Example:
# (1) (2) (3) (4) (5) (6) (7)
after foobar ($foo) is cool :($) :cached { $self->log("foobar $foo") }
=head2 The Keyword
By default, these keywords are exported. They must be exported by
request:
use Kavorka qw( before after around );
use Kavorka qw( -modifiers );
=head2 The Method Names
These are the names of the methods being wrapped.
Multiple names may be separated by colons:
after foo, bar, baz { ... }
=head2 The Signature
See L<Kavorka::Manual::Signatures>.
The C<before> and C<after> keywords have a default invocant called
C<< $self >>, but it does not have a type constraint, so can equally
be used for class or object methods.
The C<around> modifier defines two invocants called C<< $next >> and
C<< $self >>. (C<< ${^NEXT} >> is also available as an alias for
C<< $next >> for backwards compatibility with Moops::MethodModifiers.)
Beware using type constraints for method modifiers (which are
essentially wrappers); constraints will be checked at each level of
wrapping which will slow down method calls.
=head2 Traits
See L<Kavorka::Manual::ExtendingKavorka>.
=head2 The Prototype
See L<Kavorka::Manual::PrototypeAndAttributes>.
Note however that prototypes are fairly useless for methods.
=head2 The Attributes
Attributes may alternatively be provided I<< before the signature >>.
See L<Kavorka::Manual::PrototypeAndAttributes>.
Note that this applies the attribute to the modifier code, and not to
the method being modified.
=head2 The Modifier Body
This is more or less what you'd expect from the modifier body you'd
write with L<Moose>, however the lexical variables for parameters
are pre-declared and pre-populated, and invocants have been shifted
off C<< @_ >>.
=head1 BUGS
Please report any bugs to
L<http://rt.cpan.org/Dist/Display.html?Queue=Kavorka>.
=head1 SEE ALSO
L<Kavorka::Manual>,
L<Kavorka::Manual::Signatures>,
L<Kavorka::Manual::PrototypeAndAttributes>,
L<Kavorka::Manual::Methods>.
=head1 AUTHOR
Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
=head1 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.
=head1 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.