.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\" ========================================================================
.de Sh \" Subsection heading
.de Sp \" Vertical space (when we can't use .PP)
.de Vb \" Begin verbatim text
.de Ve \" End verbatim text
.\" 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. | will give a
.\" real vertical bar. \*(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<>.
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
. 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
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
. tm Index:\\$1\t\\n%\t"\\$2"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. \" simple accents for nroff and troff
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
.\" ========================================================================
.TH NEXT 3 "2002-06-01" "perl v5.8.0" "Perl Programmers Reference Guide"
NEXT.pm \- Provide a pseudo\-class NEXT that allows method redispatch
\& sub A::method { print "$_[0]: A method\en"; $_[0]->NEXT::method() }
\& sub A::DESTROY { print "$_[0]: A dtor\en"; $_[0]->NEXT::DESTROY() }
\& sub B::AUTOLOAD { print "$_[0]: B AUTOLOAD\en"; $_[0]->NEXT::AUTOLOAD() }
\& sub B::DESTROY { print "$_[0]: B dtor\en"; $_[0]->NEXT::DESTROY() }
\& sub C::method { print "$_[0]: C method\en"; $_[0]->NEXT::method() }
\& sub C::AUTOLOAD { print "$_[0]: C AUTOLOAD\en"; $_[0]->NEXT::AUTOLOAD() }
\& sub C::DESTROY { print "$_[0]: C dtor\en"; $_[0]->NEXT::DESTROY() }
\& sub D::method { print "$_[0]: D method\en"; $_[0]->NEXT::method() }
\& sub D::AUTOLOAD { print "$_[0]: D AUTOLOAD\en"; $_[0]->NEXT::AUTOLOAD() }
\& sub D::DESTROY { print "$_[0]: D dtor\en"; $_[0]->NEXT::DESTROY() }
\& my $obj = bless {}, "D";
\& $obj->method(); # Calls D::method, A::method, C::method
\& $obj->missing_method(); # Calls D::AUTOLOAD, B::AUTOLOAD, C::AUTOLOAD
\& # Clean-up calls D::DESTROY, B::DESTROY, A::DESTROY, C::DESTROY
\&\s-1NEXT\s0.pm adds a pseudoclass named \f(CW\*(C`NEXT\*(C'\fR to any program
that uses it. If a method \f(CW\*(C`m\*(C'\fR calls \f(CW\*(C`$self\-\*(C'\fR\fINEXT::m()\fR>, the call to
\&\f(CW\*(C`m\*(C'\fR is redispatched as if the calling method had not originally been found.
In other words, a call to \f(CW\*(C`$self\-\*(C'\fR\fINEXT::m()\fR> resumes the depth\-first,
left-to-right search of \f(CW$self\fR's class hierarchy that resulted in the
original call to \f(CW\*(C`m\*(C'\fR.
Note that this is not the same thing as \f(CW\*(C`$self\-\*(C'\fR\fISUPER::m()\fR>, which
begins a new dispatch that is restricted to searching the ancestors
of the current class. \f(CW\*(C`$self\-\*(C'\fR\fINEXT::m()\fR> can backtrack
past the current class \*(-- to look for a suitable method in other
ancestors of \f(CW$self\fR \*(-- whereas \f(CW\*(C`$self\-\*(C'\fR\fISUPER::m()\fR> cannot.
A typical use would be in the destructors of a class hierarchy,
as illustrated in the synopsis above. Each class in the hierarchy
has a \s-1DESTROY\s0 method that performs some class-specific action
and then redispatches the call up the hierarchy. As a result,
when an object of class D is destroyed, the destructors of \fIall\fR
its parent classes are called (in depth\-first, left-to-right order).
Another typical use of redispatch would be in \f(CW\*(C`AUTOLOAD\*(C'\fR'ed methods.
If such a method determined that it was not able to handle a
particular call, it might choose to redispatch that call, in the
hope that some other \f(CW\*(C`AUTOLOAD\*(C'\fR (above it, or to its left) might
By default, if a redispatch attempt fails to find another method
elsewhere in the objects class hierarchy, it quietly gives up and does
nothing (but see \*(L"Enforcing redispatch\*(R"). This gracious acquiesence
is also unlike the (generally annoying) behaviour of \f(CW\*(C`SUPER\*(C'\fR, which
throws an exception if it cannot redispatch.
Note that it is a fatal error for any method (including \f(CW\*(C`AUTOLOAD\*(C'\fR)
to attempt to redispatch any method that does not have the
\& sub D::oops { print "oops!\en"; $_[0]->NEXT::other_method() }
.Sh "Enforcing redispatch"
.IX Subsection "Enforcing redispatch"
It is possible to make \f(CW\*(C`NEXT\*(C'\fR redispatch more demandingly (i.e. like
\&\f(CW\*(C`SUPER\*(C'\fR does), so that the redispatch throws an exception if it cannot
find a \*(L"next\*(R" method to call.
To do this, simple invoke the redispatch as:
\& $self->NEXT::ACTUAL::method();
\& $self->NEXT::method();
The \f(CW\*(C`ACTUAL\*(C'\fR tells \f(CW\*(C`NEXT\*(C'\fR that there must actually be a next method to call,
or it should throw an exception.
\&\f(CW\*(C`NEXT::ACTUAL\*(C'\fR is most commonly used in \f(CW\*(C`AUTOLOAD\*(C'\fR methods, as a means to
decline an \f(CW\*(C`AUTOLOAD\*(C'\fR request, but preserve the normal exception-on-failure
\& if ($AUTOLOAD =~ /foo|bar/) {
\& else { # try elsewhere
\& shift()->NEXT::ACTUAL::AUTOLOAD(@_);
By using \f(CW\*(C`NEXT::ACTUAL\*(C'\fR, if there is no other \f(CW\*(C`AUTOLOAD\*(C'\fR to handle the
method call, an exception will be thrown (as usually happens in the absence of
a suitable \f(CW\*(C`AUTOLOAD\*(C'\fR).
.Sh "Avoiding repetitions"
.IX Subsection "Avoiding repetitions"
If \f(CW\*(C`NEXT\*(C'\fR redispatching is used in the methods of a \*(L"diamond\*(R" class hierarchy:
\& sub foo { print "called A::foo\en"; shift->NEXT::foo() }
\& sub foo { print "called B::foo\en"; shift->NEXT::foo() }
\& package C; @ISA = qw( A );
\& sub foo { print "called C::foo\en"; shift->NEXT::foo() }
\& package D; @ISA = qw(A B);
\& sub foo { print "called D::foo\en"; shift->NEXT::foo() }
\& package E; @ISA = qw(C D);
\& sub foo { print "called E::foo\en"; shift->NEXT::foo() }
then derived classes may (re\-)inherit base-class methods through two or
more distinct paths (e.g. in the way \f(CW\*(C`E\*(C'\fR inherits \f(CW\*(C`A::foo\*(C'\fR twice \*(--
through \f(CW\*(C`C\*(C'\fR and \f(CW\*(C`D\*(C'\fR). In such cases, a sequence of \f(CW\*(C`NEXT\*(C'\fR redispatches
will invoke the multiply inherited method as many times as it is
inherited. For example, the above code prints:
(i.e. \f(CW\*(C`A::foo\*(C'\fR is called twice).
In some cases this \fImay\fR be the desired effect within a diamond hierarchy,
but in others (e.g. for destructors) it may be more appropriate to
call each method only once during a sequence of redispatches.
To cover such cases, you can redispatch methods via:
\& $self->NEXT::UNSEEN::method();
\& $self->NEXT::method();
This causes the redispatcher to skip any classes in the hierarchy that it has
already visited in an earlier redispatch. So, for example, if the
previous example were rewritten:
\& sub foo { print "called A::foo\en"; shift->NEXT::UNSEEN::foo() }
\& sub foo { print "called B::foo\en"; shift->NEXT::UNSEEN::foo() }
\& package C; @ISA = qw( A );
\& sub foo { print "called C::foo\en"; shift->NEXT::UNSEEN::foo() }
\& package D; @ISA = qw(A B);
\& sub foo { print "called D::foo\en"; shift->NEXT::UNSEEN::foo() }
\& package E; @ISA = qw(C D);
\& sub foo { print "called E::foo\en"; shift->NEXT::UNSEEN::foo() }
and omit the second call to \f(CW\*(C`A::foo\*(C'\fR.
Note that you can also use:
\& $self->NEXT::UNSEEN::ACTUAL::method();
\& $self->NEXT::ACTUAL::UNSEEN::method();
to get both unique invocation \fIand\fR exception\-on\-failure.
Damian Conway (damian@conway.org)
.SH "BUGS AND IRRITATIONS"
.IX Header "BUGS AND IRRITATIONS"
Because it's a module, not an integral part of the interpreter, \s-1NEXT\s0.pm
has to guess where the surrounding call was found in the method
look-up sequence. In the presence of diamond inheritance patterns
it occasionally guesses wrong.
It's also too slow (despite caching).
Comment, suggestions, and patches welcome.
\& Copyright (c) 2000-2001, Damian Conway. All Rights Reserved.
\& This module is free software. It may be used, redistributed
\& and/or modified under the same terms as Perl itself.