1Class::C3::Adopt::NEXT(U3s)er Contributed Perl DocumentatCiloanss::C3::Adopt::NEXT(3)
2
3
4
6 Class::C3::Adopt::NEXT - make NEXT suck less
7
9 package MyApp::Plugin::FooBar;
10 #use NEXT;
11 use Class::C3::Adopt::NEXT;
12 # or 'use Class::C3::Adopt::NEXT -no_warn;' to suppress warnings
13
14 # Or use warnings::register
15 # no warnings 'Class::C3::Adopt::NEXT';
16
17 # Or suppress warnings in a set of modules from one place
18 # no Class::C3::Adopt::NEXT qw/ Module1 Module2 Module3 /;
19 # Or suppress using a regex
20 # no Class::C3::Adopt::NEXT qr/^Module\d$/;
21
22 sub a_method {
23 my ($self) = @_;
24 # Do some stuff
25
26 # Re-dispatch method
27 # Note that this will generate a warning the _first_ time the package
28 # uses NEXT unless you un comment the 'no warnings' line above.
29 $self->NEXT::method();
30 }
31
33 NEXT was a good solution a few years ago, but isn't any more. It's
34 slow, and the order in which it re-dispatches methods appears random at
35 times. It also encourages bad programming practices, as you end up with
36 code to re-dispatch methods when all you really wanted to do was run
37 some code before or after a method fired.
38
39 However, if you have a large application, then weaning yourself off
40 "NEXT" isn't easy.
41
42 This module is intended as a drop-in replacement for NEXT, supporting
43 the same interface, but using Class::C3 to do the hard work. You can
44 then write new code without "NEXT", and migrate individual source files
45 to use "Class::C3" or method modifiers as appropriate, at whatever pace
46 you're comfortable with.
47
49 This module will warn once for each package using NEXT. It uses
50 warnings::register, and so can be disabled like by adding "no warnings
51 'Class::C3::Adopt::NEXT';" to each package which generates a warning,
52 or adding "use Class::C3::Adopt::NEXT -no_warn;", or disable multiple
53 modules at once by saying:
54
55 no Class::C3::Adopt::NEXT qw/ Module1 Module2 Module3 /;
56
57 somewhere before the warnings are first triggered. You can also setup
58 entire name spaces of modules which will not warn using a regex, e.g.
59
60 no Class::C3::Adopt::NEXT qr/^Module\d$/;
61
63 Current code using NEXT
64 You add "use MRO::Compat" to the top of a package as you start
65 converting it, and gradually replace your calls to "NEXT::method()"
66 with "maybe::next::method()", and calls to "NEXT::ACTUAL::method()"
67 with "next::method()".
68
69 Example:
70
71 sub yourmethod {
72 my $self = shift;
73
74 # $self->NEXT::yourmethod(@_); becomes
75 $self->maybe::next::method();
76 }
77
78 sub othermethod {
79 my $self = shift;
80
81 # $self->NEXT::ACTUAL::yourmethodname(); becomes
82 $self->next::method();
83 }
84
85 On systems with Class::C3::XS present, this will automatically be used
86 to speed up method re-dispatch. If you are running perl version 5.9.5
87 or greater then the C3 method resolution algorithm is included in perl.
88 Correct use of MRO::Compat as shown above allows your code to be
89 seamlessly forward and backwards compatible, taking advantage of native
90 versions if available, but falling back to using pure perl "Class::C3".
91
92 Writing new code
93 Use Moose and make all of your plugins Moose::Roles, then use method
94 modifiers to wrap methods.
95
96 Example:
97
98 package MyApp::Role::FooBar;
99 use Moose::Role;
100
101 before 'a_method' => sub {
102 my ($self) = @_;
103 # Do some stuff
104 };
105
106 around 'a_method' => sub {
107 my $orig = shift;
108 my $self = shift;
109 # Do some stuff before
110 my $ret = $self->$orig(@_); # Run wrapped method (or not!)
111 # Do some stuff after
112 return $ret;
113 };
114
115 package MyApp;
116 use Moose;
117
118 with 'MyApp::Role::FooBar';
119
121 There are some inheritance hierarchies that it is possible to create
122 which cannot be resolved to a simple C3 hierarchy. In that case, this
123 module will fall back to using "NEXT". In this case a warning will be
124 emitted.
125
126 Because calculating the MRO of every class every time "->NEXT::foo" is
127 used from within it is too expensive, runtime manipulations of @ISA are
128 prohibited.
129
131 This module replaces "NEXT::AUTOLOAD" with it's own version. If
132 warnings are enabled then a warning will be emitted on the first use of
133 "NEXT" by each package.
134
136 MRO::Compat and Class::C3 for method re-dispatch and Moose for method
137 modifiers and roles.
138
139 NEXT for documentation on the functionality you'll be removing.
140
142 Florian Ragwitz <rafl@debian.org>
143 Tomas Doran <bobtfish@bobtfish.net>
144
146 This software is copyright (c) 2010 by Florian Ragwitz.
147
148 This is free software; you can redistribute it and/or modify it under
149 the same terms as the Perl 5 programming language system itself.
150
151
152
153perl v5.12.0 2010-05-07 Class::C3::Adopt::NEXT(3)