Debian Codegraph @

upstream/mageia-cauldron/man3pm/NEXT.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "NEXT 3pm"
61 .TH NEXT 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 NEXT \- Provide a pseudo\-class NEXT (et al) that allows method redispatch
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use NEXT;
72 \&
73 \& package P;
74 \& sub P::method { print "$_[0]: P method\en"; $_[0]\->NEXT::method() }
75 \& sub P::DESTROY { print "$_[0]: P dtor\en"; $_[0]\->NEXT::DESTROY() }
76 \&
77 \& package Q;
78 \& use base qw( P );
79 \& sub Q::AUTOLOAD { print "$_[0]: Q AUTOLOAD\en"; $_[0]\->NEXT::AUTOLOAD() }
80 \& sub Q::DESTROY { print "$_[0]: Q dtor\en"; $_[0]\->NEXT::DESTROY() }
81 \&
82 \& package R;
83 \& sub R::method { print "$_[0]: R method\en"; $_[0]\->NEXT::method() }
84 \& sub R::AUTOLOAD { print "$_[0]: R AUTOLOAD\en"; $_[0]\->NEXT::AUTOLOAD() }
85 \& sub R::DESTROY { print "$_[0]: R dtor\en"; $_[0]\->NEXT::DESTROY() }
86 \&
87 \& package S;
88 \& use base qw( Q R );
89 \& sub S::method { print "$_[0]: S method\en"; $_[0]\->NEXT::method() }
90 \& sub S::AUTOLOAD { print "$_[0]: S AUTOLOAD\en"; $_[0]\->NEXT::AUTOLOAD() }
91 \& sub S::DESTROY { print "$_[0]: S dtor\en"; $_[0]\->NEXT::DESTROY() }
92 \&
93 \& package main;
94 \&
95 \& my $obj = bless {}, "S";
96 \&
97 \& $obj\->method(); # Calls S::method, P::method, R::method
98 \& $obj\->missing_method(); # Calls S::AUTOLOAD, Q::AUTOLOAD, R::AUTOLOAD
99 \&
100 \& # Clean\-up calls S::DESTROY, Q::DESTROY, P::DESTROY, R::DESTROY
101 .Ve
102 .SH DESCRIPTION
103 .IX Header "DESCRIPTION"
104 The \f(CW\*(C`NEXT\*(C'\fR module adds a pseudoclass named \f(CW\*(C`NEXT\*(C'\fR to any program
105 that uses it. If a method \f(CW\*(C`m\*(C'\fR calls \f(CW\*(C`$self\->NEXT::m()\*(C'\fR, the call to
106 \&\f(CW\*(C`m\*(C'\fR is redispatched as if the calling method had not originally been found.
107 .PP
108 \&\fBNote:\fR before using this module,
109 you should look at next::method <https://metacpan.org/pod/mro#next::method>
110 in the core mro module.
111 \&\f(CW\*(C`mro\*(C'\fR has been a core module since Perl 5.9.5.
112 .PP
113 In other words, a call to \f(CW\*(C`$self\->NEXT::m()\*(C'\fR resumes the depth\-first,
114 left\-to\-right search of \f(CW$self\fR\*(Aqs class hierarchy that resulted in the
115 original call to \f(CW\*(C`m\*(C'\fR.
116 .PP
117 Note that this is not the same thing as \f(CW\*(C`$self\->SUPER::m()\*(C'\fR, which
118 begins a new dispatch that is restricted to searching the ancestors
119 of the current class. \f(CW\*(C`$self\->NEXT::m()\*(C'\fR can backtrack
120 past the current class \-\- to look for a suitable method in other
121 ancestors of \f(CW$self\fR \-\- whereas \f(CW\*(C`$self\->SUPER::m()\*(C'\fR cannot.
122 .PP
123 A typical use would be in the destructors of a class hierarchy,
124 as illustrated in the SYNOPSIS above. Each class in the hierarchy
125 has a DESTROY method that performs some class\-specific action
126 and then redispatches the call up the hierarchy. As a result,
127 when an object of class S is destroyed, the destructors of \fIall\fR
128 its parent classes are called (in depth\-first, left\-to\-right order).
129 .PP
130 Another typical use of redispatch would be in \f(CW\*(C`AUTOLOAD\*(C'\fR\*(Aqed methods.
131 If such a method determined that it was not able to handle a
132 particular call, it might choose to redispatch that call, in the
133 hope that some other \f(CW\*(C`AUTOLOAD\*(C'\fR (above it, or to its left) might
134 do better.
135 .PP
136 By default, if a redispatch attempt fails to find another method
137 elsewhere in the objects class hierarchy, it quietly gives up and does
138 nothing (but see "Enforcing redispatch"). This gracious acquiescence
139 is also unlike the (generally annoying) behaviour of \f(CW\*(C`SUPER\*(C'\fR, which
140 throws an exception if it cannot redispatch.
141 .PP
142 Note that it is a fatal error for any method (including \f(CW\*(C`AUTOLOAD\*(C'\fR)
143 to attempt to redispatch any method that does not have the
144 same name. For example:
145 .PP
146 .Vb 1
147 \& sub S::oops { print "oops!\en"; $_[0]\->NEXT::other_method() }
148 .Ve
149 .SS "Enforcing redispatch"
150 .IX Subsection "Enforcing redispatch"
151 It is possible to make \f(CW\*(C`NEXT\*(C'\fR redispatch more demandingly (i.e. like
152 \&\f(CW\*(C`SUPER\*(C'\fR does), so that the redispatch throws an exception if it cannot
153 find a "next" method to call.
154 .PP
155 To do this, simple invoke the redispatch as:
156 .PP
157 .Vb 1
158 \& $self\->NEXT::ACTUAL::method();
159 .Ve
160 .PP
161 rather than:
162 .PP
163 .Vb 1
164 \& $self\->NEXT::method();
165 .Ve
166 .PP
167 The \f(CW\*(C`ACTUAL\*(C'\fR tells \f(CW\*(C`NEXT\*(C'\fR that there must actually be a next method to call,
168 or it should throw an exception.
169 .PP
170 \&\f(CW\*(C`NEXT::ACTUAL\*(C'\fR is most commonly used in \f(CW\*(C`AUTOLOAD\*(C'\fR methods, as a means to
171 decline an \f(CW\*(C`AUTOLOAD\*(C'\fR request, but preserve the normal exception\-on\-failure
172 semantics:
173 .PP
174 .Vb 8
175 \& sub AUTOLOAD {
176 \& if ($AUTOLOAD =~ /foo|bar/) {
177 \& # handle here
178 \& }
179 \& else { # try elsewhere
180 \& shift()\->NEXT::ACTUAL::AUTOLOAD(@_);
181 \& }
182 \& }
183 .Ve
184 .PP
185 By using \f(CW\*(C`NEXT::ACTUAL\*(C'\fR, if there is no other \f(CW\*(C`AUTOLOAD\*(C'\fR to handle the
186 method call, an exception will be thrown (as usually happens in the absence of
187 a suitable \f(CW\*(C`AUTOLOAD\*(C'\fR).
188 .SS "Avoiding repetitions"
189 .IX Subsection "Avoiding repetitions"
190 If \f(CW\*(C`NEXT\*(C'\fR redispatching is used in the methods of a "diamond" class hierarchy:
191 .PP
192 .Vb 5
193 \& # A B
194 \& # / \e /
195 \& # C D
196 \& # \e /
197 \& # E
198 \&
199 \& use NEXT;
200 \&
201 \& package A;
202 \& sub foo { print "called A::foo\en"; shift\->NEXT::foo() }
203 \&
204 \& package B;
205 \& sub foo { print "called B::foo\en"; shift\->NEXT::foo() }
206 \&
207 \& package C; @ISA = qw( A );
208 \& sub foo { print "called C::foo\en"; shift\->NEXT::foo() }
209 \&
210 \& package D; @ISA = qw(A B);
211 \& sub foo { print "called D::foo\en"; shift\->NEXT::foo() }
212 \&
213 \& package E; @ISA = qw(C D);
214 \& sub foo { print "called E::foo\en"; shift\->NEXT::foo() }
215 \&
216 \& E\->foo();
217 .Ve
218 .PP
219 then derived classes may (re\-)inherit base\-class methods through two or
220 more distinct paths (e.g. in the way \f(CW\*(C`E\*(C'\fR inherits \f(CW\*(C`A::foo\*(C'\fR twice \-\-
221 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
222 will invoke the multiply inherited method as many times as it is
223 inherited. For example, the above code prints:
224 .PP
225 .Vb 6
226 \& called E::foo
227 \& called C::foo
228 \& called A::foo
229 \& called D::foo
230 \& called A::foo
231 \& called B::foo
232 .Ve
233 .PP
234 (i.e. \f(CW\*(C`A::foo\*(C'\fR is called twice).
235 .PP
236 In some cases this \fImay\fR be the desired effect within a diamond hierarchy,
237 but in others (e.g. for destructors) it may be more appropriate to
238 call each method only once during a sequence of redispatches.
239 .PP
240 To cover such cases, you can redispatch methods via:
241 .PP
242 .Vb 1
243 \& $self\->NEXT::DISTINCT::method();
244 .Ve
245 .PP
246 rather than:
247 .PP
248 .Vb 1
249 \& $self\->NEXT::method();
250 .Ve
251 .PP
252 This causes the redispatcher to only visit each distinct \f(CW\*(C`method\*(C'\fR method
253 once. That is, to skip any classes in the hierarchy that it has
254 already visited during redispatch. So, for example, if the
255 previous example were rewritten:
256 .PP
257 .Vb 2
258 \& package A;
259 \& sub foo { print "called A::foo\en"; shift\->NEXT::DISTINCT::foo() }
260 \&
261 \& package B;
262 \& sub foo { print "called B::foo\en"; shift\->NEXT::DISTINCT::foo() }
263 \&
264 \& package C; @ISA = qw( A );
265 \& sub foo { print "called C::foo\en"; shift\->NEXT::DISTINCT::foo() }
266 \&
267 \& package D; @ISA = qw(A B);
268 \& sub foo { print "called D::foo\en"; shift\->NEXT::DISTINCT::foo() }
269 \&
270 \& package E; @ISA = qw(C D);
271 \& sub foo { print "called E::foo\en"; shift\->NEXT::DISTINCT::foo() }
272 \&
273 \& E\->foo();
274 .Ve
275 .PP
276 then it would print:
277 .PP
278 .Vb 5
279 \& called E::foo
280 \& called C::foo
281 \& called A::foo
282 \& called D::foo
283 \& called B::foo
284 .Ve
285 .PP
286 and omit the second call to \f(CW\*(C`A::foo\*(C'\fR (since it would not be distinct
287 from the first call to \f(CW\*(C`A::foo\*(C'\fR).
288 .PP
289 Note that you can also use:
290 .PP
291 .Vb 1
292 \& $self\->NEXT::DISTINCT::ACTUAL::method();
293 .Ve
294 .PP
295 or:
296 .PP
297 .Vb 1
298 \& $self\->NEXT::ACTUAL::DISTINCT::method();
299 .Ve
300 .PP
301 to get both unique invocation \fIand\fR exception\-on\-failure.
302 .PP
303 Note that, for historical compatibility, you can also use
304 \&\f(CW\*(C`NEXT::UNSEEN\*(C'\fR instead of \f(CW\*(C`NEXT::DISTINCT\*(C'\fR.
305 .SS "Invoking all versions of a method with a single call"
306 .IX Subsection "Invoking all versions of a method with a single call"
307 Yet another pseudo\-class that \f(CW\*(C`NEXT\*(C'\fR provides is \f(CW\*(C`EVERY\*(C'\fR.
308 Its behaviour is considerably simpler than that of the \f(CW\*(C`NEXT\*(C'\fR family.
309 A call to:
310 .PP
311 .Vb 1
312 \& $obj\->EVERY::foo();
313 .Ve
314 .PP
315 calls \fIevery\fR method named \f(CW\*(C`foo\*(C'\fR that the object in \f(CW$obj\fR has inherited.
316 That is:
317 .PP
318 .Vb 1
319 \& use NEXT;
320 \&
321 \& package A; @ISA = qw(B D X);
322 \& sub foo { print "A::foo " }
323 \&
324 \& package B; @ISA = qw(D X);
325 \& sub foo { print "B::foo " }
326 \&
327 \& package X; @ISA = qw(D);
328 \& sub foo { print "X::foo " }
329 \&
330 \& package D;
331 \& sub foo { print "D::foo " }
332 \&
333 \& package main;
334 \&
335 \& my $obj = bless {}, \*(AqA\*(Aq;
336 \& $obj\->EVERY::foo(); # prints" A::foo B::foo X::foo D::foo
337 .Ve
338 .PP
339 Prefixing a method call with \f(CW\*(C`EVERY::\*(C'\fR causes every method in the
340 object\*(Aqs hierarchy with that name to be invoked. As the above example
341 illustrates, they are not called in Perl\*(Aqs usual "left\-most\-depth\-first"
342 order. Instead, they are called "breadth\-first\-dependency\-wise".
343 .PP
344 That means that the inheritance tree of the object is traversed breadth\-first
345 and the resulting order of classes is used as the sequence in which methods
346 are called. However, that sequence is modified by imposing a rule that the
347 appropriate method of a derived class must be called before the same method of
348 any ancestral class. That\*(Aqs why, in the above example, \f(CW\*(C`X::foo\*(C'\fR is called
349 before \f(CW\*(C`D::foo\*(C'\fR, even though \f(CW\*(C`D\*(C'\fR comes before \f(CW\*(C`X\*(C'\fR in \f(CW@B::ISA\fR.
350 .PP
351 In general, there\*(Aqs no need to worry about the order of calls. They will be
352 left\-to\-right, breadth\-first, most\-derived\-first. This works perfectly for
353 most inherited methods (including destructors), but is inappropriate for
354 some kinds of methods (such as constructors, cloners, debuggers, and
355 initializers) where it\*(Aqs more appropriate that the least\-derived methods be
356 called first (as more\-derived methods may rely on the behaviour of their
357 "ancestors"). In that case, instead of using the \f(CW\*(C`EVERY\*(C'\fR pseudo\-class:
358 .PP
359 .Vb 1
360 \& $obj\->EVERY::foo(); # prints" A::foo B::foo X::foo D::foo
361 .Ve
362 .PP
363 you can use the \f(CW\*(C`EVERY::LAST\*(C'\fR pseudo\-class:
364 .PP
365 .Vb 1
366 \& $obj\->EVERY::LAST::foo(); # prints" D::foo X::foo B::foo A::foo
367 .Ve
368 .PP
369 which reverses the order of method call.
370 .PP
371 Whichever version is used, the actual methods are called in the same
372 context (list, scalar, or void) as the original call via \f(CW\*(C`EVERY\*(C'\fR, and return:
373 .IP \(bu 4
374 A hash of array references in list context. Each entry of the hash has the
375 fully qualified method name as its key and a reference to an array containing
376 the method\*(Aqs list\-context return values as its value.
377 .IP \(bu 4
378 A reference to a hash of scalar values in scalar context. Each entry of the hash has the
379 fully qualified method name as its key and the method\*(Aqs scalar\-context return values as its value.
380 .IP \(bu 4
381 Nothing in void context (obviously).
382 .ie n .SS "Using ""EVERY"" methods"
383 .el .SS "Using \f(CWEVERY\fP methods"
384 .IX Subsection "Using EVERY methods"
385 The typical way to use an \f(CW\*(C`EVERY\*(C'\fR call is to wrap it in another base
386 method, that all classes inherit. For example, to ensure that every
387 destructor an object inherits is actually called (as opposed to just the
388 left\-most\-depth\-first\-est one):
389 .PP
390 .Vb 2
391 \& package Base;
392 \& sub DESTROY { $_[0]\->EVERY::Destroy }
393 \&
394 \& package Derived1;
395 \& use base \*(AqBase\*(Aq;
396 \& sub Destroy {...}
397 \&
398 \& package Derived2;
399 \& use base \*(AqBase\*(Aq, \*(AqDerived1\*(Aq;
400 \& sub Destroy {...}
401 .Ve
402 .PP
403 et cetera. Every derived class than needs its own clean\-up
404 behaviour simply adds its own \f(CW\*(C`Destroy\*(C'\fR method (\fInot\fR a \f(CW\*(C`DESTROY\*(C'\fR method),
405 which the call to \f(CW\*(C`EVERY::LAST::Destroy\*(C'\fR in the inherited destructor
406 then correctly picks up.
407 .PP
408 Likewise, to create a class hierarchy in which every initializer inherited by
409 a new object is invoked:
410 .PP
411 .Vb 6
412 \& package Base;
413 \& sub new {
414 \& my ($class, %args) = @_;
415 \& my $obj = bless {}, $class;
416 \& $obj\->EVERY::LAST::Init(\e%args);
417 \& }
418 \&
419 \& package Derived1;
420 \& use base \*(AqBase\*(Aq;
421 \& sub Init {
422 \& my ($argsref) = @_;
423 \& ...
424 \& }
425 \&
426 \& package Derived2;
427 \& use base \*(AqBase\*(Aq, \*(AqDerived1\*(Aq;
428 \& sub Init {
429 \& my ($argsref) = @_;
430 \& ...
431 \& }
432 .Ve
433 .PP
434 et cetera. Every derived class than needs some additional initialization
435 behaviour simply adds its own \f(CW\*(C`Init\*(C'\fR method (\fInot\fR a \f(CW\*(C`new\*(C'\fR method),
436 which the call to \f(CW\*(C`EVERY::LAST::Init\*(C'\fR in the inherited constructor
437 then correctly picks up.
438 .SH "SEE ALSO"
439 .IX Header "SEE ALSO"
440 mro
441 (in particular next::method <https://metacpan.org/pod/mro#next::method>),
442 which has been a core module since Perl 5.9.5.
443 .SH AUTHOR
444 .IX Header "AUTHOR"
445 Damian Conway ([email protected])
446 .SH "BUGS AND IRRITATIONS"
447 .IX Header "BUGS AND IRRITATIONS"
448 Because it\*(Aqs a module, not an integral part of the interpreter, \f(CW\*(C`NEXT\*(C'\fR
449 has to guess where the surrounding call was found in the method
450 look\-up sequence. In the presence of diamond inheritance patterns
451 it occasionally guesses wrong.
452 .PP
453 It\*(Aqs also too slow (despite caching).
454 .PP
455 Comment, suggestions, and patches welcome.
456 .SH COPYRIGHT
457 .IX Header "COPYRIGHT"
458 .Vb 3
459 \& Copyright (c) 2000\-2001, Damian Conway. All Rights Reserved.
460 \& This module is free software. It may be used, redistributed
461 \& and/or modified under the same terms as Perl itself.
462 .Ve