Class:...::NEXT(3pm)

💖 Class::C3::Adopt::NEXT — the Class:...::NEXT(3pm) manual, but make it make sense

okay bestie, sit down, hydrate, because we're talking about a module whose entire personality is "make NEXT suck less" and honestly? iconic mission statement. no cap.

---

✨ NAME ✨

Class::C3::Adopt::NEXT — literally just: make NEXT suck less. that's the whole pitch. 🫶

🌸 VERSION 🌸

version 0.14 — yeah we're on the classics, she's vintage, she's stable, she slays.

🎀 SYNOPSIS 🎀

here's the whole vibe, verbatim, don't touch anything:

package MyApp::Plugin::FooBar;
#use NEXT;
use Class::C3::Adopt::NEXT;
# or 'use Class::C3::Adopt::NEXT -no_warn;' to suppress warnings

# Or use warnings::register
# no warnings 'Class::C3::Adopt::NEXT';

# Or suppress warnings in a set of modules from one place
# no Class::C3::Adopt::NEXT qw/ Module1 Module2 Module3 /;
# Or suppress using a regex
# no Class::C3::Adopt::NEXT qr/^Module\d$/;

sub a_method {
    my ($self) = @_;
    # Do some stuff

    # Re-dispatch method
    # Note that this will generate a warning the _first_ time the package
    # uses NEXT unless you un comment the 'no warnings' line above.
    $self->NEXT::method();
}

see how you just swap the use line and keep the rest of your life intact? that's the whole magic trick. 💅

---

🦋 DESCRIPTION 🦋

so, tea time. NEXT was a good solution a few years ago, but isn't any more. it's slow, and the order in which it re-dispatches methods appears random at times. it also encourages bad programming practices, as you end up with code to re-dispatch methods when all you really wanted to do was run some code before or after a method fired. and the way that it's just like that... yeah. not the vibe.

but here's the thing, and I'm not gonna lie to you: if you have a large application, then weaning yourself off NEXT isn't easy. it's giving "we can't just delete it, half the codebase would riot." 😭

this module is intended as a drop-in replacement for NEXT, supporting the same interface, but using Class::C3 to do the hard work. you can then write new code without NEXT, and migrate individual source files to use Class::C3 or method modifiers as appropriate, at whatever pace you're comfortable with. slow girl summer migration arc. we love a gradual glow-up. ✨

---

⚠️ WARNINGS ⚠️

this module will warn once for each package using NEXT. it uses warnings::register, and so can be disabled like by adding

no warnings 'Class::C3::Adopt::NEXT';

to each package which generates a warning, or adding use Class::C3::Adopt::NEXT -no_warn;, or disable multiple modules at once by saying:

no Class::C3::Adopt::NEXT qw/ Module1 Module2 Module3 /;

somewhere before the warnings are first triggered. you can also setup entire name spaces of modules which will not warn using a regex, e.g.

no Class::C3::Adopt::NEXT qr/^Module\d$/;

so many options to make it be quiet, we love a module with boundaries. 🙈

---

🧚 MIGRATING 🧚

🌈 Current code using NEXT

okay so step one: you add use MRO::Compat to the top of a package as you start converting it, and gradually replace your calls to NEXT::method() with maybe::next::method(), and calls to NEXT::ACTUAL::method() with next::method().

Example:

sub yourmethod {
    my $self = shift;

    # $self->NEXT::yourmethod(@_); becomes
    $self->maybe::next::method();
}

sub othermethod {
    my $self = shift;

    # $self->NEXT::ACTUAL::yourmethodname(); becomes
    $self->next::method();
}

on systems with Class::C3::XS present, this will automatically be used to speed up method re-dispatch. if you are running perl version 5.9.5 or greater then the C3 method resolution algorithm is included in perl. correct use of MRO::Compat as shown above allows your code to be seamlessly forward and backwards compatible, taking advantage of native versions if available, but falling back to using pure perl Class::C3. forward AND backwards compatible?? she contains multitudes, periodt. 👑

💜 Writing new code

bestie, this is the fun part. use Moose and make all of your plugins Moose::Roles, then use method modifiers to wrap methods.

Example:

package MyApp::Role::FooBar;
use Moose::Role;

before 'a_method' => sub {
    my ($self) = @_;
    # Do some stuff
};

around 'a_method' => sub {
    my $orig = shift;
    my $self = shift;
    # Do some stuff before
    my $ret = $self->$orig(@_); # Run wrapped method (or not!)
    # Do some stuff after
    return $ret;
};

package MyApp;
use Moose;

with 'MyApp::Role::FooBar';

look at that around block. she wraps, she runs the orig, she returns. main character energy. 🌟

---

💀 CAVEATS 💀

okay listen, real talk, the serious part:

there are some inheritance hierarchies that it is possible to create which cannot be resolved to a simple C3 hierarchy. in that case, this module will fall back to using NEXT. in this case a warning will be emitted. so like, you'll know. she tells you.

and because calculating the method resolution order of every class every time ->NEXT::foo is used from within it is too expensive, runtime manipulations of @ISA are prohibited. 🚫 like, do not. don't do it. it's giving undefined chaos.

---

🔥 FUNCTIONS 🔥

this module replaces NEXT::AUTOLOAD with its own version. if warnings are enabled then a warning will be emitted on the first use of NEXT by each package. one warning, one time, per package — she's not naggy, she just wants you to know. 🎀

---

👑 SEE ALSO 👑

• MRO::Compat and Class::C3 for method re-dispatch — your new besties for the whole re-dispatch situation.
• Moose for method modifiers and roles — the glow-up path.
• NEXT for documentation on the functionality you'll be removing. like, read it before you leave it. it's a farewell tour. 🥺

---

💖 AUTHORS 💖

• Florian Ragwitz <rafl@debian.org>
• Tomas Doran <bobtfish@bobtfish.net>

🌸 CONTRIBUTOR 🌸

• Karen Etheridge <ether@cpan.org>

---

⭐ COPYRIGHT AND LICENSE ⭐

this software is copyright (c) 2015 by Florian Ragwitz.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie. this beauty shipped as part of perl v5.34.0 on 2022-06-11, and yeah, it's filed under Class:...::NEXT(3pm) because even the manpage title has main character energy. go forth, use Class::C3::Adopt::NEXT;, and migrate at your own pace. iykyk. 💅✨🫶