.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Class::Method::Modifiers 3pm"
.TH Class::Method::Modifiers 3pm "2023-06-11" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Class::Method::Modifiers \- Provides Moose\-like method modifiers
.SH "VERSION"
.IX Header "VERSION"
version 2.15
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    package Child;
\&    use parent \*(AqMyParent\*(Aq;
\&    use Class::Method::Modifiers;
\&
\&    sub new_method { }
\&
\&    before \*(Aqold_method\*(Aq => sub {
\&        carp "old_method is deprecated, use new_method";
\&    };
\&
\&    around \*(Aqother_method\*(Aq => sub {
\&        my $orig = shift;
\&        my $ret = $orig\->(@_);
\&        return $ret =~ /\ed/ ? $ret : lc $ret;
\&    };
\&
\&    after \*(Aqprivate\*(Aq, \*(Aqprotected\*(Aq => sub {
\&        debug "finished calling a dangerous method";
\&    };
\&
\&    use Class::Method::Modifiers qw(fresh);
\&
\&    fresh \*(Aqnot_in_hierarchy\*(Aq => sub {
\&        warn "freshly added method\en";
\&    };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Method modifiers are a convenient feature from the \s-1CLOS\s0 (Common Lisp Object
System) world.
.PP
In its most basic form, a method modifier is just a method that calls
\&\f(CW\*(C`$self\->SUPER::foo(@_)\*(C'\fR. I for one have trouble remembering that exact
invocation, so my classes seldom re-dispatch to their base classes. Very bad!
.PP
\&\f(CW\*(C`Class::Method::Modifiers\*(C'\fR provides three modifiers: \f(CW\*(C`before\*(C'\fR, \f(CW\*(C`around\*(C'\fR, and
\&\f(CW\*(C`after\*(C'\fR. \f(CW\*(C`before\*(C'\fR and \f(CW\*(C`after\*(C'\fR are run just before and after the method they
modify, but can not really affect that original method. \f(CW\*(C`around\*(C'\fR is run in
place of the original method, with a hook to easily call that original method.
See the \*(L"\s-1MODIFIERS\*(R"\s0 section for more details on how the particular modifiers
work.
.PP
One clear benefit of using \f(CW\*(C`Class::Method::Modifiers\*(C'\fR is that you can define
multiple modifiers in a single namespace. These separate modifiers don't need
to know about each other. This makes top-down design easy. Have a base class
that provides the skeleton methods of each operation, and have plugins modify
those methods to flesh out the specifics.
.PP
Parent classes need not know about \f(CW\*(C`Class::Method::Modifiers\*(C'\fR. This means you
should be able to modify methods in \fIany\fR subclass. See
Term::VT102::ZeroBased for an example of subclassing with
\&\f(CW\*(C`Class::Method::Modifiers\*(C'\fR.
.PP
In short, \f(CW\*(C`Class::Method::Modifiers\*(C'\fR solves the problem of making sure you
call \f(CW\*(C`$self\->SUPER::foo(@_)\*(C'\fR, and provides a cleaner interface for it.
.PP
As of version 1.00, \f(CW\*(C`Class::Method::Modifiers\*(C'\fR is faster in some cases than
Moose. See \fIbenchmark/method_modifiers.pl\fR in the Moose distribution.
.PP
\&\f(CW\*(C`Class::Method::Modifiers\*(C'\fR also provides an additional \*(L"modifier\*(R" type,
\&\f(CW\*(C`fresh\*(C'\fR; see below.
.SH "MODIFIERS"
.IX Header "MODIFIERS"
All modifiers let you modify one or multiple methods at a time. The names of
multiple methods can be provided as a list or as an array-reference. Examples:
.PP
.Vb 3
\& before \*(Aqmethod\*(Aq => sub { ... };
\& before \*(Aqmethod1\*(Aq, \*(Aqmethod2\*(Aq => sub { ... };
\& before [ \*(Aqmethod1\*(Aq, \*(Aqmethod2\*(Aq ] => sub { ... };
.Ve
.SS "before method(s) => sub { ... };"
.IX Subsection "before method(s) => sub { ... };"
\&\f(CW\*(C`before\*(C'\fR is called before the method it is modifying. Its return value is
totally ignored. It receives the same \f(CW@_\fR as the method it is modifying
would have received. You can modify the \f(CW@_\fR the original method will receive
by changing \f(CW$_[0]\fR and friends (or by changing anything inside a reference).
This is a feature!
.SS "after method(s) => sub { ... };"
.IX Subsection "after method(s) => sub { ... };"
\&\f(CW\*(C`after\*(C'\fR is called after the method it is modifying. Its return value is
totally ignored. It receives the same \f(CW@_\fR as the method it is modifying
received, mostly. The original method can modify \f(CW@_\fR (such as by changing
\&\f(CW$_[0]\fR or references) and \f(CW\*(C`after\*(C'\fR will see the modified version. If you
don't like this behavior, specify both a \f(CW\*(C`before\*(C'\fR and \f(CW\*(C`after\*(C'\fR, and copy the
\&\f(CW@_\fR during \f(CW\*(C`before\*(C'\fR for \f(CW\*(C`after\*(C'\fR to use.
.SS "around method(s) => sub { ... };"
.IX Subsection "around method(s) => sub { ... };"
\&\f(CW\*(C`around\*(C'\fR is called instead of the method it is modifying. The method you're
overriding is passed in as the first argument (called \f(CW$orig\fR by convention).
Watch out for contextual return values of \f(CW$orig\fR.
.PP
You can use \f(CW\*(C`around\*(C'\fR to:
.ie n .IP "Pass $orig a different @_" 4
.el .IP "Pass \f(CW$orig\fR a different \f(CW@_\fR" 4
.IX Item "Pass $orig a different @_"
.Vb 5
\&    around \*(Aqmethod\*(Aq => sub {
\&        my $orig = shift;
\&        my $self = shift;
\&        $orig\->($self, reverse @_);
\&    };
.Ve
.ie n .IP "Munge the return value of $orig" 4
.el .IP "Munge the return value of \f(CW$orig\fR" 4
.IX Item "Munge the return value of $orig"
.Vb 4
\&    around \*(Aqmethod\*(Aq => sub {
\&        my $orig = shift;
\&        ucfirst $orig\->(@_);
\&    };
.Ve
.ie n .IP "Avoid calling $orig \*(-- conditionally" 4
.el .IP "Avoid calling \f(CW$orig\fR \*(-- conditionally" 4
.IX Item "Avoid calling $orig conditionally"
.Vb 5
\&    around \*(Aqmethod\*(Aq => sub {
\&        my $orig = shift;
\&        return $orig\->(@_) if time() % 2;
\&        return "no dice, captain";
\&    };
.Ve
.SS "fresh method(s) => sub { ... };"
.IX Subsection "fresh method(s) => sub { ... };"
(Available since version 2.00)
.PP
Unlike the other modifiers, this does not modify an existing method.
Ordinarily, \f(CW\*(C`fresh\*(C'\fR merely installs the coderef as a method in the
appropriate class; but if the class hierarchy already contains a method of
the same name, an exception is thrown.  The idea of this \*(L"modifier\*(R" is to
increase safety when subclassing.  Suppose you're writing a subclass of a
class Some::Base, and adding a new method:
.PP
.Vb 2
\&    package My::Subclass;
\&    use base \*(AqSome::Base\*(Aq;
\&
\&    sub foo { ... }
.Ve
.PP
If a later version of Some::Base also adds a new method named \f(CW\*(C`foo\*(C'\fR, your
method will shadow that method.  Alternatively, you can use \f(CW\*(C`fresh\*(C'\fR
to install the additional method into your subclass:
.PP
.Vb 2
\&    package My::Subclass;
\&    use base \*(AqSome::Base\*(Aq;
\&
\&    use Class::Method::Modifiers \*(Aqfresh\*(Aq;
\&
\&    fresh \*(Aqfoo\*(Aq => sub { ... };
.Ve
.PP
Now upgrading Some::Base to a version with a conflicting \f(CW\*(C`foo\*(C'\fR method will
cause an exception to be thrown; seeing that error will give you the
opportunity to fix the problem (perhaps by picking a different method name
in your subclass, or similar).
.PP
Creating fresh methods with \f(CW\*(C`install_modifier\*(C'\fR (see below) provides a way
to get similar safety benefits when adding local monkeypatches to existing
classes; see <http://aaroncrane.co.uk/talks/monkey_patching_subclassing/>.
.PP
For \s-1API\s0 compatibility reasons, this function is exported only when you ask
for it specifically, or for \f(CW\*(C`:all\*(C'\fR.
.ie n .SS "install_modifier $package, $type, @names, sub { ... }"
.el .SS "install_modifier \f(CW$package\fP, \f(CW$type\fP, \f(CW@names\fP, sub { ... }"
.IX Subsection "install_modifier $package, $type, @names, sub { ... }"
\&\f(CW\*(C`install_modifier\*(C'\fR is like \f(CW\*(C`before\*(C'\fR, \f(CW\*(C`after\*(C'\fR, \f(CW\*(C`around\*(C'\fR, and \f(CW\*(C`fresh\*(C'\fR but
it also lets you dynamically select the modifier type ('before', 'after',
\&'around', 'fresh')
and package that the method modifiers are installed into. This expert-level
function is exported only when you ask for it specifically, or for \f(CW\*(C`:all\*(C'\fR.
.SH "NOTES"
.IX Header "NOTES"
All three normal modifiers; \f(CW\*(C`before\*(C'\fR, \f(CW\*(C`after\*(C'\fR, and \f(CW\*(C`around\*(C'\fR; are exported
into your namespace by default. You may \f(CW\*(C`use Class::Method::Modifiers ()\*(C'\fR to
avoid modifying your namespace. I may steal more features from Moose, namely
\&\f(CW\*(C`super\*(C'\fR, \f(CW\*(C`override\*(C'\fR, \f(CW\*(C`inner\*(C'\fR, \f(CW\*(C`augment\*(C'\fR, and whatever the Moose folks
come up with next.
.PP
Note that the syntax and semantics for these modifiers is directly borrowed
from Moose (the implementations, however, are not).
.PP
Class::Trigger shares a few similarities with \f(CW\*(C`Class::Method::Modifiers\*(C'\fR,
and they even have some overlap in purpose \*(-- both can be used to implement
highly pluggable applications. The difference is that Class::Trigger
provides a mechanism for easily letting parent classes to invoke hooks defined
by other code. \f(CW\*(C`Class::Method::Modifiers\*(C'\fR provides a way of
overriding/augmenting methods safely, and the parent class need not know about
it.
.SS ":lvalue \s-1METHODS\s0"
.IX Subsection ":lvalue METHODS"
When adding \f(CW\*(C`before\*(C'\fR or \f(CW\*(C`after\*(C'\fR modifiers, the wrapper method will be
an lvalue method if the wrapped sub is, and assigning to the method
will propagate to the wrapped method as expected.  For \f(CW\*(C`around\*(C'\fR
modifiers, it is the modifier sub that determines if the wrapper
method is an lvalue method.
.SH "CAVEATS"
.IX Header "CAVEATS"
It is erroneous to modify a method that doesn't exist in your class's
inheritance hierarchy. If this occurs, an exception will be thrown when
the modifier is defined.
.PP
It doesn't yet play well with \f(CW\*(C`caller\*(C'\fR. There are some \f(CW\*(C`TODO\*(C'\fR tests for this.
Don't get your hopes up though!
.PP
Applying modifiers to array lvalue methods is not fully supported. Attempting
to assign to an array lvalue method that has an \f(CW\*(C`after\*(C'\fR modifier applied will
result in an error.  Array lvalue methods are not well supported by perl in
general, and should be avoided.
.SH "MAJOR VERSION CHANGES"
.IX Header "MAJOR VERSION CHANGES"
This module was bumped to 1.00 following a complete reimplementation, to
indicate breaking backwards compatibility. The \*(L"guard\*(R" modifier was removed,
and the internals are completely different.
.PP
The new version is a few times faster with half the code. It's now even faster
than Moose.
.PP
Any code that just used modifiers should not change in behavior, except to
become more correct. And, of course, faster. :)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
Class::Method::Modifiers::Fast
.IP "\(bu" 4
Moose
.IP "\(bu" 4
Class::Trigger
.IP "\(bu" 4
Class::MOP::Method::Wrapped
.IP "\(bu" 4
MRO::Compat
.IP "\(bu" 4
\&\s-1CLOS\s0 <https://en.wikipedia.org/wiki/Common_Lisp_Object_System>
.SH "ACKNOWLEDGMENTS"
.IX Header "ACKNOWLEDGMENTS"
Thanks to Stevan Little for Moose, I would never have known about
method modifiers otherwise.
.PP
Thanks to Matt Trout and Stevan Little for their advice.
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted through the \s-1RT\s0 bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=Class-Method-Modifiers>
(or bug\-Class\-Method\-Modifiers@rt.cpan.org <mailto:bug-Class-Method-Modifiers@rt.cpan.org>).
.SH "AUTHOR"
.IX Header "AUTHOR"
Shawn M Moore <sartak@gmail.com>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
Karen Etheridge <ether@cpan.org>
.IP "\(bu" 4
Shawn M Moore <code@sartak.org>
.IP "\(bu" 4
Graham Knop <haarg@haarg.org>
.IP "\(bu" 4
Aaron Crane <arc@cpan.org>
.IP "\(bu" 4
Peter Rabbitson <ribasushi@cpan.org>
.IP "\(bu" 4
David Steinbrunner <dsteinbrunner@pobox.com>
.IP "\(bu" 4
gfx <gfuji@cpan.org>
.IP "\(bu" 4
Justin Hunter <justin.d.hunter@gmail.com>
.IP "\(bu" 4
mannih <github@lxxi.org>
.IP "\(bu" 4
Yves Orton <demerphq@gmail.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2007 by Shawn M Moore.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.