diff options
Diffstat (limited to 'upstream/debian-unstable/man3/NEXT.3perl')
| -rw-r--r-- | upstream/debian-unstable/man3/NEXT.3perl | 459 |
1 files changed, 459 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/NEXT.3perl b/upstream/debian-unstable/man3/NEXT.3perl new file mode 100644 index 00000000..abe44fc5 --- /dev/null +++ b/upstream/debian-unstable/man3/NEXT.3perl @@ -0,0 +1,459 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (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 +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. 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 "NEXT 3perl" +.TH NEXT 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" 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 +NEXT \- Provide a pseudo\-class NEXT (et al) that allows method redispatch +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use NEXT; +\& +\& package P; +\& sub P::method { print "$_[0]: P method\en"; $_[0]\->NEXT::method() } +\& sub P::DESTROY { print "$_[0]: P dtor\en"; $_[0]\->NEXT::DESTROY() } +\& +\& package Q; +\& use base qw( P ); +\& sub Q::AUTOLOAD { print "$_[0]: Q AUTOLOAD\en"; $_[0]\->NEXT::AUTOLOAD() } +\& sub Q::DESTROY { print "$_[0]: Q dtor\en"; $_[0]\->NEXT::DESTROY() } +\& +\& package R; +\& sub R::method { print "$_[0]: R method\en"; $_[0]\->NEXT::method() } +\& sub R::AUTOLOAD { print "$_[0]: R AUTOLOAD\en"; $_[0]\->NEXT::AUTOLOAD() } +\& sub R::DESTROY { print "$_[0]: R dtor\en"; $_[0]\->NEXT::DESTROY() } +\& +\& package S; +\& use base qw( Q R ); +\& sub S::method { print "$_[0]: S method\en"; $_[0]\->NEXT::method() } +\& sub S::AUTOLOAD { print "$_[0]: S AUTOLOAD\en"; $_[0]\->NEXT::AUTOLOAD() } +\& sub S::DESTROY { print "$_[0]: S dtor\en"; $_[0]\->NEXT::DESTROY() } +\& +\& package main; +\& +\& my $obj = bless {}, "S"; +\& +\& $obj\->method(); # Calls S::method, P::method, R::method +\& $obj\->missing_method(); # Calls S::AUTOLOAD, Q::AUTOLOAD, R::AUTOLOAD +\& +\& # Clean\-up calls S::DESTROY, Q::DESTROY, P::DESTROY, R::DESTROY +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \f(CW\*(C`NEXT\*(C'\fR module 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\->NEXT::m()\*(C'\fR, the call to +\&\f(CW\*(C`m\*(C'\fR is redispatched as if the calling method had not originally been found. +.PP +\&\fBNote:\fR before using this module, +you should look at next::method <https://metacpan.org/pod/mro#next::method> +in the core mro module. +\&\f(CW\*(C`mro\*(C'\fR has been a core module since Perl 5.9.5. +.PP +In other words, a call to \f(CW\*(C`$self\->NEXT::m()\*(C'\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. +.PP +Note that this is not the same thing as \f(CW\*(C`$self\->SUPER::m()\*(C'\fR, which +begins a new dispatch that is restricted to searching the ancestors +of the current class. \f(CW\*(C`$self\->NEXT::m()\*(C'\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\->SUPER::m()\*(C'\fR cannot. +.PP +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 DESTROY method that performs some class-specific action +and then redispatches the call up the hierarchy. As a result, +when an object of class S is destroyed, the destructors of \fIall\fR +its parent classes are called (in depth-first, left-to-right order). +.PP +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 +do better. +.PP +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 "Enforcing redispatch"). This gracious acquiescence +is also unlike the (generally annoying) behaviour of \f(CW\*(C`SUPER\*(C'\fR, which +throws an exception if it cannot redispatch. +.PP +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 +same name. For example: +.PP +.Vb 1 +\& sub S::oops { print "oops!\en"; $_[0]\->NEXT::other_method() } +.Ve +.SS "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 "next" method to call. +.PP +To do this, simple invoke the redispatch as: +.PP +.Vb 1 +\& $self\->NEXT::ACTUAL::method(); +.Ve +.PP +rather than: +.PP +.Vb 1 +\& $self\->NEXT::method(); +.Ve +.PP +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. +.PP +\&\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 +semantics: +.PP +.Vb 8 +\& sub AUTOLOAD { +\& if ($AUTOLOAD =~ /foo|bar/) { +\& # handle here +\& } +\& else { # try elsewhere +\& shift()\->NEXT::ACTUAL::AUTOLOAD(@_); +\& } +\& } +.Ve +.PP +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). +.SS "Avoiding repetitions" +.IX Subsection "Avoiding repetitions" +If \f(CW\*(C`NEXT\*(C'\fR redispatching is used in the methods of a "diamond" class hierarchy: +.PP +.Vb 5 +\& # A B +\& # / \e / +\& # C D +\& # \e / +\& # E +\& +\& use NEXT; +\& +\& package A; +\& sub foo { print "called A::foo\en"; shift\->NEXT::foo() } +\& +\& package B; +\& 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() } +\& +\& E\->foo(); +.Ve +.PP +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: +.PP +.Vb 6 +\& called E::foo +\& called C::foo +\& called A::foo +\& called D::foo +\& called A::foo +\& called B::foo +.Ve +.PP +(i.e. \f(CW\*(C`A::foo\*(C'\fR is called twice). +.PP +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. +.PP +To cover such cases, you can redispatch methods via: +.PP +.Vb 1 +\& $self\->NEXT::DISTINCT::method(); +.Ve +.PP +rather than: +.PP +.Vb 1 +\& $self\->NEXT::method(); +.Ve +.PP +This causes the redispatcher to only visit each distinct \f(CW\*(C`method\*(C'\fR method +once. That is, to skip any classes in the hierarchy that it has +already visited during redispatch. So, for example, if the +previous example were rewritten: +.PP +.Vb 2 +\& package A; +\& sub foo { print "called A::foo\en"; shift\->NEXT::DISTINCT::foo() } +\& +\& package B; +\& sub foo { print "called B::foo\en"; shift\->NEXT::DISTINCT::foo() } +\& +\& package C; @ISA = qw( A ); +\& sub foo { print "called C::foo\en"; shift\->NEXT::DISTINCT::foo() } +\& +\& package D; @ISA = qw(A B); +\& sub foo { print "called D::foo\en"; shift\->NEXT::DISTINCT::foo() } +\& +\& package E; @ISA = qw(C D); +\& sub foo { print "called E::foo\en"; shift\->NEXT::DISTINCT::foo() } +\& +\& E\->foo(); +.Ve +.PP +then it would print: +.PP +.Vb 5 +\& called E::foo +\& called C::foo +\& called A::foo +\& called D::foo +\& called B::foo +.Ve +.PP +and omit the second call to \f(CW\*(C`A::foo\*(C'\fR (since it would not be distinct +from the first call to \f(CW\*(C`A::foo\*(C'\fR). +.PP +Note that you can also use: +.PP +.Vb 1 +\& $self\->NEXT::DISTINCT::ACTUAL::method(); +.Ve +.PP +or: +.PP +.Vb 1 +\& $self\->NEXT::ACTUAL::DISTINCT::method(); +.Ve +.PP +to get both unique invocation \fIand\fR exception-on-failure. +.PP +Note that, for historical compatibility, you can also use +\&\f(CW\*(C`NEXT::UNSEEN\*(C'\fR instead of \f(CW\*(C`NEXT::DISTINCT\*(C'\fR. +.SS "Invoking all versions of a method with a single call" +.IX Subsection "Invoking all versions of a method with a single call" +Yet another pseudo-class that \f(CW\*(C`NEXT\*(C'\fR provides is \f(CW\*(C`EVERY\*(C'\fR. +Its behaviour is considerably simpler than that of the \f(CW\*(C`NEXT\*(C'\fR family. +A call to: +.PP +.Vb 1 +\& $obj\->EVERY::foo(); +.Ve +.PP +calls \fIevery\fR method named \f(CW\*(C`foo\*(C'\fR that the object in \f(CW$obj\fR has inherited. +That is: +.PP +.Vb 1 +\& use NEXT; +\& +\& package A; @ISA = qw(B D X); +\& sub foo { print "A::foo " } +\& +\& package B; @ISA = qw(D X); +\& sub foo { print "B::foo " } +\& +\& package X; @ISA = qw(D); +\& sub foo { print "X::foo " } +\& +\& package D; +\& sub foo { print "D::foo " } +\& +\& package main; +\& +\& my $obj = bless {}, \*(AqA\*(Aq; +\& $obj\->EVERY::foo(); # prints" A::foo B::foo X::foo D::foo +.Ve +.PP +Prefixing a method call with \f(CW\*(C`EVERY::\*(C'\fR causes every method in the +object's hierarchy with that name to be invoked. As the above example +illustrates, they are not called in Perl's usual "left-most-depth-first" +order. Instead, they are called "breadth-first-dependency-wise". +.PP +That means that the inheritance tree of the object is traversed breadth-first +and the resulting order of classes is used as the sequence in which methods +are called. However, that sequence is modified by imposing a rule that the +appropriate method of a derived class must be called before the same method of +any ancestral class. That's why, in the above example, \f(CW\*(C`X::foo\*(C'\fR is called +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. +.PP +In general, there's no need to worry about the order of calls. They will be +left-to-right, breadth-first, most-derived-first. This works perfectly for +most inherited methods (including destructors), but is inappropriate for +some kinds of methods (such as constructors, cloners, debuggers, and +initializers) where it's more appropriate that the least-derived methods be +called first (as more-derived methods may rely on the behaviour of their +"ancestors"). In that case, instead of using the \f(CW\*(C`EVERY\*(C'\fR pseudo-class: +.PP +.Vb 1 +\& $obj\->EVERY::foo(); # prints" A::foo B::foo X::foo D::foo +.Ve +.PP +you can use the \f(CW\*(C`EVERY::LAST\*(C'\fR pseudo-class: +.PP +.Vb 1 +\& $obj\->EVERY::LAST::foo(); # prints" D::foo X::foo B::foo A::foo +.Ve +.PP +which reverses the order of method call. +.PP +Whichever version is used, the actual methods are called in the same +context (list, scalar, or void) as the original call via \f(CW\*(C`EVERY\*(C'\fR, and return: +.IP \(bu 4 +A hash of array references in list context. Each entry of the hash has the +fully qualified method name as its key and a reference to an array containing +the method's list-context return values as its value. +.IP \(bu 4 +A reference to a hash of scalar values in scalar context. Each entry of the hash has the +fully qualified method name as its key and the method's scalar-context return values as its value. +.IP \(bu 4 +Nothing in void context (obviously). +.ie n .SS "Using ""EVERY"" methods" +.el .SS "Using \f(CWEVERY\fP methods" +.IX Subsection "Using EVERY methods" +The typical way to use an \f(CW\*(C`EVERY\*(C'\fR call is to wrap it in another base +method, that all classes inherit. For example, to ensure that every +destructor an object inherits is actually called (as opposed to just the +left-most-depth-first-est one): +.PP +.Vb 2 +\& package Base; +\& sub DESTROY { $_[0]\->EVERY::Destroy } +\& +\& package Derived1; +\& use base \*(AqBase\*(Aq; +\& sub Destroy {...} +\& +\& package Derived2; +\& use base \*(AqBase\*(Aq, \*(AqDerived1\*(Aq; +\& sub Destroy {...} +.Ve +.PP +et cetera. Every derived class than needs its own clean-up +behaviour simply adds its own \f(CW\*(C`Destroy\*(C'\fR method (\fInot\fR a \f(CW\*(C`DESTROY\*(C'\fR method), +which the call to \f(CW\*(C`EVERY::LAST::Destroy\*(C'\fR in the inherited destructor +then correctly picks up. +.PP +Likewise, to create a class hierarchy in which every initializer inherited by +a new object is invoked: +.PP +.Vb 6 +\& package Base; +\& sub new { +\& my ($class, %args) = @_; +\& my $obj = bless {}, $class; +\& $obj\->EVERY::LAST::Init(\e%args); +\& } +\& +\& package Derived1; +\& use base \*(AqBase\*(Aq; +\& sub Init { +\& my ($argsref) = @_; +\& ... +\& } +\& +\& package Derived2; +\& use base \*(AqBase\*(Aq, \*(AqDerived1\*(Aq; +\& sub Init { +\& my ($argsref) = @_; +\& ... +\& } +.Ve +.PP +et cetera. Every derived class than needs some additional initialization +behaviour simply adds its own \f(CW\*(C`Init\*(C'\fR method (\fInot\fR a \f(CW\*(C`new\*(C'\fR method), +which the call to \f(CW\*(C`EVERY::LAST::Init\*(C'\fR in the inherited constructor +then correctly picks up. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +mro +(in particular next::method <https://metacpan.org/pod/mro#next::method>), +which has been a core module since Perl 5.9.5. +.SH AUTHOR +.IX Header "AUTHOR" +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, \f(CW\*(C`NEXT\*(C'\fR +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. +.PP +It's also too slow (despite caching). +.PP +Comment, suggestions, and patches welcome. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +.Vb 3 +\& 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. +.Ve |