local-lib5/man/man3/Class::C3::Adopt::NEXT.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Class::C3::Adopt::NEXT 3"
 132 .TH Class::C3::Adopt::NEXT 3 "2009-06-08" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Class::C3::Adopt::NEXT \- make NEXT suck less
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 4
 138 \&    package MyApp::Plugin::FooBar;
 139 \&    #use NEXT;
 140 \&    use Class::C3::Adopt::NEXT;
 141 \&    # or 'use Class::C3::Adopt::NEXT \-no_warn;' to suppress warnings
 142 .Ve
 143 .PP
 144 .Vb 2
 145 \&    # Or use warnings::register
 146 \&    # no warnings 'Class::C3::Adopt::NEXT';
 147 .Ve
 148 .PP
 149 .Vb 4
 150 \&    # Or suppress warnings in a set of modules from one place
 151 \&    # no Class::C3::Adopt::NEXT qw/ Module1 Module2 Module3 /;
 152 \&    # Or suppress using a regex
 153 \&    # no Class::C3::Adopt::NEXT qr/^Module\ed$/;
 154 .Ve
 155 .PP
 156 .Vb 3
 157 \&    sub a_method {
 158 \&        my ($self) = @_;
 159 \&        # Do some stuff
 160 .Ve
 161 .PP
 162 .Vb 5
 163 \&        # Re\-dispatch method
 164 \&        # Note that this will generate a warning the _first_ time the package
 165 \&        # uses NEXT unless you un comment the 'no warnings' line above.
 166 \&        $self\->NEXT::method();
 167 \&    }
 168 .Ve
 169 .SH "DESCRIPTION"
 170 .IX Header "DESCRIPTION"
 171 \&\s-1NEXT\s0 was a good solution a few years ago, but isn't any more.  It's slow,
 172 and the order in which it re-dispatches methods appears random at times. It
 173 also encourages bad programming practices, as you end up with code to
 174 re-dispatch methods when all you really wanted to do was run some code before
 175 or after a method fired.
 176 .PP
 177 However, if you have a large application, then weaning yourself off \f(CW\*(C`NEXT\*(C'\fR
 178 isn't easy.
 179 .PP
 180 This module is intended as a drop-in replacement for \s-1NEXT\s0, supporting the same
 181 interface, but using Class::C3 to do the hard work. You can then write new
 182 code without \f(CW\*(C`NEXT\*(C'\fR, and migrate individual source files to use \f(CW\*(C`Class::C3\*(C'\fR
 183 or method modifiers as appropriate, at whatever pace you're comfortable with.
 184 .SH "WARNINGS"
 185 .IX Header "WARNINGS"
 186 This module will warn once for each package using \s-1NEXT\s0. It uses
 187 warnings::register, and so can be disabled like by adding \f(CW\*(C`no warnings
 188 \&'Class::C3::Adopt::NEXT';\*(C'\fR to each package which generates a warning, or adding
 189 \&\f(CW\*(C`use Class::C3::Adopt::NEXT \-no_warn;\*(C'\fR, or disable multiple modules at once by
 190 saying:
 191 .PP
 192 .Vb 1
 193 \&    no Class::C3::Adopt::NEXT qw/ Module1 Module2 Module3 /;
 194 .Ve
 195 .PP
 196 somewhere before the warnings are first triggered. You can also setup entire
 197 name spaces of modules which will not warn using a regex, e.g.
 198 .PP
 199 .Vb 1
 200 \&    no Class::C3::Adopt::NEXT qr/^Module\ed$/;
 201 .Ve
 202 .SH "MIGRATING"
 203 .IX Header "MIGRATING"
 204 .Sh "Current code using \s-1NEXT\s0"
 205 .IX Subsection "Current code using NEXT"
 206 You add \f(CW\*(C`use MRO::Compat\*(C'\fR to the top of a package as you start converting it,
 207 and gradually replace your calls to \f(CW\*(C`NEXT::method()\*(C'\fR with
 208 \&\f(CW\*(C`maybe::next::method()\*(C'\fR, and calls to \f(CW\*(C`NEXT::ACTUAL::method()\*(C'\fR with
 209 \&\f(CW\*(C`next::method()\*(C'\fR.
 210 .PP
 211 Example:
 212 .PP
 213 .Vb 2
 214 \&    sub yourmethod {
 215 \&        my $self = shift;
 216 .Ve
 217 .PP
 218 .Vb 3
 219 \&        # $self\->NEXT::yourmethod(@_); becomes
 220 \&        $self\->maybe::next::method();
 221 \&    }
 222 .Ve
 223 .PP
 224 .Vb 2
 225 \&    sub othermethod {
 226 \&        my $self = shift;
 227 .Ve
 228 .PP
 229 .Vb 3
 230 \&        # $self\->NEXT::ACTUAL::yourmethodname(); becomes
 231 \&        $self\->next::method();
 232 \&    }
 233 .Ve
 234 .PP
 235 On systems with Class::C3::XS present, this will automatically be used to
 236 speed up method re\-dispatch. If you are running perl version 5.9.5 or greater
 237 then the C3 method resolution algorithm is included in perl. Correct use of
 238 MRO::Compat as shown above allows your code to be seamlessly forward and
 239 backwards compatible, taking advantage of native versions if available, but
 240 falling back to using pure perl \f(CW\*(C`Class::C3\*(C'\fR.
 241 .Sh "Writing new code"
 242 .IX Subsection "Writing new code"
 243 Use Moose and make all of your plugins Moose::Roles, then use
 244 method modifiers to wrap methods.
 245 .PP
 246 Example:
 247 .PP
 248 .Vb 2
 249 \&    package MyApp::Role::FooBar;
 250 \&    use Moose::Role;
 251 .Ve
 252 .PP
 253 .Vb 4
 254 \&    before 'a_method' => sub {
 255 \&        my ($self) = @_;
 256 \&        # Do some stuff
 257 \&    };
 258 .Ve
 259 .PP
 260 .Vb 8
 261 \&    around 'a_method' => sub {
 262 \&        my $orig = shift;
 263 \&        my $self = shift;
 264 \&        # Do some stuff before
 265 \&        my $ret = $self\->$orig(@_); # Run wrapped method (or not!)
 266 \&        # Do some stuff after
 267 \&        return $ret;
 268 \&    };
 269 .Ve
 270 .PP
 271 .Vb 2
 272 \&    package MyApp;
 273 \&    use Moose;
 274 .Ve
 275 .PP
 276 .Vb 1
 277 \&    with 'MyApp::Role::FooBar';
 278 .Ve
 279 .SH "CAVEATS"
 280 .IX Header "CAVEATS"
 281 There are some inheritance hierarchies that it is possible to create which
 282 cannot be resolved to a simple C3 hierarchy. In that case, this module will
 283 fall back to using \f(CW\*(C`NEXT\*(C'\fR. In this case a warning will be emitted.
 284 .PP
 285 Because calculating the \s-1MRO\s0 of every class every time \f(CW\*(C`\->NEXT::foo\*(C'\fR is
 286 used from within it is too expensive, runtime manipulations of \f(CW@ISA\fR are
 287 prohibited.
 288 .SH "FUNCTIONS"
 289 .IX Header "FUNCTIONS"
 290 This module replaces \f(CW\*(C`NEXT::AUTOLOAD\*(C'\fR with it's own version. If warnings are
 291 enabled then a warning will be emitted on the first use of \f(CW\*(C`NEXT\*(C'\fR by each
 292 package.
 293 .SH "SEE ALSO"
 294 .IX Header "SEE ALSO"
 295 MRO::Compat and Class::C3 for method re-dispatch and Moose for method
 296 modifiers and roles.
 297 .PP
 298 \&\s-1NEXT\s0 for documentation on the functionality you'll be removing.
 299 .SH "AUTHORS"
 300 .IX Header "AUTHORS"
 301 Florian Ragwitz \f(CW\*(C`rafl@debian.org\*(C'\fR
 302 .PP
 303 Tomas Doran \f(CW\*(C`bobtfish@bobtfish.net\*(C'\fR
 304 .SH "COPYRIGHT AND LICENSE"
 305 .IX Header "COPYRIGHT AND LICENSE"
 306 Copyright (c) 2008, 2009  Florian Ragwitz
 307 .PP
 308 You may distribute this code under the same terms as Perl itself.