1NEXT(3pm) Perl Programmers Reference Guide NEXT(3pm)
2
6 NEXT.pm - Provide a pseudo-class NEXT (et al) that allows method redis‐
7 patch
8
10 use NEXT;
11 package A;
13 sub A::method { print "$_[0]: A method\n"; $_[0]->NEXT::method() }
14 sub A::DESTROY { print "$_[0]: A dtor\n"; $_[0]->NEXT::DESTROY() }
15 package B;
17 use base qw( A );
18 sub B::AUTOLOAD { print "$_[0]: B AUTOLOAD\n"; $_[0]->NEXT::AUTOLOAD() }
19 sub B::DESTROY { print "$_[0]: B dtor\n"; $_[0]->NEXT::DESTROY() }
20 package C;
22 sub C::method { print "$_[0]: C method\n"; $_[0]->NEXT::method() }
23 sub C::AUTOLOAD { print "$_[0]: C AUTOLOAD\n"; $_[0]->NEXT::AUTOLOAD() }
24 sub C::DESTROY { print "$_[0]: C dtor\n"; $_[0]->NEXT::DESTROY() }
25 package D;
27 use base qw( B C );
28 sub D::method { print "$_[0]: D method\n"; $_[0]->NEXT::method() }
29 sub D::AUTOLOAD { print "$_[0]: D AUTOLOAD\n"; $_[0]->NEXT::AUTOLOAD() }
30 sub D::DESTROY { print "$_[0]: D dtor\n"; $_[0]->NEXT::DESTROY() }
31 package main;
33 my $obj = bless {}, "D";
35 $obj->method(); # Calls D::method, A::method, C::method
37 $obj->missing_method(); # Calls D::AUTOLOAD, B::AUTOLOAD, C::AUTOLOAD
38 # Clean-up calls D::DESTROY, B::DESTROY, A::DESTROY, C::DESTROY
40
42 NEXT.pm adds a pseudoclass named "NEXT" to any program that uses it. If
43 a method "m" calls "$self->NEXT::m()", the call to "m" is redispatched
44 as if the calling method had not originally been found.
45 In other words, a call to "$self->NEXT::m()" resumes the depth-first,
47 left-to-right search of $self's class hierarchy that resulted in the
48 original call to "m".
49 Note that this is not the same thing as "$self->SUPER::m()", which
51 begins a new dispatch that is restricted to searching the ancestors of
52 the current class. "$self->NEXT::m()" can backtrack past the current
53 class -- to look for a suitable method in other ancestors of $self --
54 whereas "$self->SUPER::m()" cannot.
55 A typical use would be in the destructors of a class hierarchy, as
57 illustrated in the synopsis above. Each class in the hierarchy has a
58 DESTROY method that performs some class-specific action and then redis‐
59 patches the call up the hierarchy. As a result, when an object of class
60 D is destroyed, the destructors of all its parent classes are called
61 (in depth-first, left-to-right order).
62 Another typical use of redispatch would be in "AUTOLOAD"'ed methods.
64 If such a method determined that it was not able to handle a particular
65 call, it might choose to redispatch that call, in the hope that some
66 other "AUTOLOAD" (above it, or to its left) might do better.
67 By default, if a redispatch attempt fails to find another method else‐
69 where in the objects class hierarchy, it quietly gives up and does
70 nothing (but see "Enforcing redispatch"). This gracious acquiesence is
71 also unlike the (generally annoying) behaviour of "SUPER", which throws
72 an exception if it cannot redispatch.
73 Note that it is a fatal error for any method (including "AUTOLOAD") to
75 attempt to redispatch any method that does not have the same name. For
76 example:
77 sub D::oops { print "oops!\n"; $_[0]->NEXT::other_method() }
79 Enforcing redispatch
81 It is possible to make "NEXT" redispatch more demandingly (i.e. like
83 "SUPER" does), so that the redispatch throws an exception if it cannot
84 find a "next" method to call.
85 To do this, simple invoke the redispatch as:
87 $self->NEXT::ACTUAL::method();
89 rather than:
91 $self->NEXT::method();
93 The "ACTUAL" tells "NEXT" that there must actually be a next method to
95 call, or it should throw an exception.
96 "NEXT::ACTUAL" is most commonly used in "AUTOLOAD" methods, as a means
98 to decline an "AUTOLOAD" request, but preserve the normal exception-on-
99 failure semantics:
100 sub AUTOLOAD {
102 if ($AUTOLOAD =~ /foo⎪bar/) {
103 # handle here
104 }
105 else { # try elsewhere
106 shift()->NEXT::ACTUAL::AUTOLOAD(@_);
107 }
108 }
109 By using "NEXT::ACTUAL", if there is no other "AUTOLOAD" to handle the
111 method call, an exception will be thrown (as usually happens in the
112 absence of a suitable "AUTOLOAD").
113 Avoiding repetitions
115 If "NEXT" redispatching is used in the methods of a "diamond" class
117 hierarchy:
118 # A B
120 # / \ /
121 # C D
122 # \ /
123 # E
124 use NEXT;
126 package A;
128 sub foo { print "called A::foo\n"; shift->NEXT::foo() }
129 package B;
131 sub foo { print "called B::foo\n"; shift->NEXT::foo() }
132 package C; @ISA = qw( A );
134 sub foo { print "called C::foo\n"; shift->NEXT::foo() }
135 package D; @ISA = qw(A B);
137 sub foo { print "called D::foo\n"; shift->NEXT::foo() }
138 package E; @ISA = qw(C D);
140 sub foo { print "called E::foo\n"; shift->NEXT::foo() }
141 E->foo();
143 then derived classes may (re-)inherit base-class methods through two or
145 more distinct paths (e.g. in the way "E" inherits "A::foo" twice --
146 through "C" and "D"). In such cases, a sequence of "NEXT" redispatches
147 will invoke the multiply inherited method as many times as it is inher‐
148 ited. For example, the above code prints:
149 called E::foo
151 called C::foo
152 called A::foo
153 called D::foo
154 called A::foo
155 called B::foo
156 (i.e. "A::foo" is called twice).
158 In some cases this may be the desired effect within a diamond hierar‐
160 chy, but in others (e.g. for destructors) it may be more appropriate to
161 call each method only once during a sequence of redispatches.
162 To cover such cases, you can redispatch methods via:
164 $self->NEXT::DISTINCT::method();
166 rather than:
168 $self->NEXT::method();
170 This causes the redispatcher to only visit each distinct "method"
172 method once. That is, to skip any classes in the hierarchy that it has
173 already visited during redispatch. So, for example, if the previous
174 example were rewritten:
175 package A;
177 sub foo { print "called A::foo\n"; shift->NEXT::DISTINCT::foo() }
178 package B;
180 sub foo { print "called B::foo\n"; shift->NEXT::DISTINCT::foo() }
181 package C; @ISA = qw( A );
183 sub foo { print "called C::foo\n"; shift->NEXT::DISTINCT::foo() }
184 package D; @ISA = qw(A B);
186 sub foo { print "called D::foo\n"; shift->NEXT::DISTINCT::foo() }
187 package E; @ISA = qw(C D);
189 sub foo { print "called E::foo\n"; shift->NEXT::DISTINCT::foo() }
190 E->foo();
192 then it would print:
194 called E::foo
196 called C::foo
197 called A::foo
198 called D::foo
199 called B::foo
200 and omit the second call to "A::foo" (since it would not be distinct
202 from the first call to "A::foo").
203 Note that you can also use:
205 $self->NEXT::DISTINCT::ACTUAL::method();
207 or:
209 $self->NEXT::ACTUAL::DISTINCT::method();
211 to get both unique invocation and exception-on-failure.
213 Note that, for historical compatibility, you can also use
215 "NEXT::UNSEEN" instead of "NEXT::DISTINCT".
216 Invoking all versions of a method with a single call
218 Yet another pseudo-class that NEXT.pm provides is "EVERY". Its behav‐
220 iour is considerably simpler than that of the "NEXT" family. A call
221 to:
222 $obj->EVERY::foo();
224 calls every method named "foo" that the object in $obj has inherited.
226 That is:
227 use NEXT;
229 package A; @ISA = qw(B D X);
231 sub foo { print "A::foo " }
232 package B; @ISA = qw(D X);
234 sub foo { print "B::foo " }
235 package X; @ISA = qw(D);
237 sub foo { print "X::foo " }
238 package D;
240 sub foo { print "D::foo " }
241 package main;
243 my $obj = bless {}, 'A';
245 $obj->EVERY::foo(); # prints" A::foo B::foo X::foo D::foo
246 Prefixing a method call with "EVERY::" causes every method in the
248 object's hierarchy with that name to be invoked. As the above example
249 illustrates, they are not called in Perl's usual
250 "left-most-depth-first" order. Instead, they are called
251 "breadth-first-dependency-wise".
252 That means that the inheritance tree of the object is traversed
254 breadth-first and the resulting order of classes is used as the
255 sequence in which methods are called. However, that sequence is modi‐
256 fied by imposing a rule that the appropritae method of a derived class
257 must be called before the same method of any ancestral class. That's
258 why, in the above example, "X::foo" is called before "D::foo", even
259 though "D" comes before "X" in @B::ISA.
260 In general, there's no need to worry about the order of calls. They
262 will be left-to-right, breadth-first, most-derived-first. This works
263 perfectly for most inherited methods (including destructors), but is
264 inappropriate for some kinds of methods (such as constructors, cloners,
265 debuggers, and initializers) where it's more appropriate that the
266 least-derived methods be called first (as more-derived methods may rely
267 on the behaviour of their "ancestors"). In that case, instead of using
268 the "EVERY" pseudo-class:
269 $obj->EVERY::foo(); # prints" A::foo B::foo X::foo D::foo
271 you can use the "EVERY::LAST" pseudo-class:
273 $obj->EVERY::LAST::foo(); # prints" D::foo X::foo B::foo A::foo
275 which reverses the order of method call.
277 Whichever version is used, the actual methods are called in the same
279 context (list, scalar, or void) as the original call via "EVERY", and
280 return:
281 · A hash of array references in list context. Each entry of the hash
283 has the fully qualified method name as its key and a reference to
284 an array containing the method's list-context return values as its
285 value.
286 · A reference to a hash of scalar values in scalar context. Each
288 entry of the hash has the fully qualified method name as its key
289 and the method's scalar-context return values as its value.
290 · Nothing in void context (obviously).
292 Using "EVERY" methods
294 The typical way to use an "EVERY" call is to wrap it in another base
296 method, that all classes inherit. For example, to ensure that every
297 destructor an object inherits is actually called (as opposed to just
298 the left-most-depth-first-est one):
299 package Base;
301 sub DESTROY { $_[0]->EVERY::Destroy }
302 package Derived1;
304 use base 'Base';
305 sub Destroy {...}
306 package Derived2;
308 use base 'Base', 'Derived1';
309 sub Destroy {...}
310 et cetera. Every derived class than needs its own clean-up behaviour
312 simply adds its own "Destroy" method (not a "DESTROY" method), which
313 the call to "EVERY::LAST::Destroy" in the inherited destructor then
314 correctly picks up.
315 Likewise, to create a class hierarchy in which every initializer inher‐
317 ited by a new object is invoked:
318 package Base;
320 sub new {
321 my ($class, %args) = @_;
322 my $obj = bless {}, $class;
323 $obj->EVERY::LAST::Init(\%args);
324 }
325 package Derived1;
327 use base 'Base';
328 sub Init {
329 my ($argsref) = @_;
330 ...
331 }
332 package Derived2;
334 use base 'Base', 'Derived1';
335 sub Init {
336 my ($argsref) = @_;
337 ...
338 }
339 et cetera. Every derived class than needs some additional initializa‐
341 tion behaviour simply adds its own "Init" method (not a "new" method),
342 which the call to "EVERY::LAST::Init" in the inherited constructor then
343 correctly picks up.
344
346 Damian Conway (damian@conway.org)
347
349 Because it's a module, not an integral part of the interpreter, NEXT.pm
350 has to guess where the surrounding call was found in the method look-up
351 sequence. In the presence of diamond inheritance patterns it occasion‐
352 ally guesses wrong.
353 It's also too slow (despite caching).
355 Comment, suggestions, and patches welcome.
357
359 Copyright (c) 2000-2001, Damian Conway. All Rights Reserved.
360 This module is free software. It may be used, redistributed
361 and/or modified under the same terms as Perl itself.
362perl v5.8.8 2001-09-21 NEXT(3pm)