Ordered(3pm)

💖 Ordered(3pm) — like, the whole vibe 💖

okay bestie, pull up a chair, because we're talking about Module::Pluggable::Ordered — the module that lets you call your plugins in a specified order. yes. in order. no chaos. no random alphabetical nonsense. we're doing ✨choreography✨ here.

---

🌸 NAME 🌸

Module::Pluggable::Ordered — call module plugins in a specified order. that's it, that's the whole job, and it does it gorgeously. 💅

---

✨ SYNOPSIS ✨

okay so imagine your main character package:

package Foo;
use Module::Pluggable::Ordered;

Foo->call_plugins("some_event", @stuff);

    for my $plugin (Foo->plugins()){
            $plugin->method();
    }

Meanwhile, in a nearby module... (yes, the dramatic cutaway 🎬)

package Foo::Plugin::One;
sub some_event_order { 99 } # I get called last of all
sub some_event { my ($self, @stuff) = @_; warn "Hello!" }

    sub _order { 99 } # I get listed by plugins_ordered() last

And in another:

package Foo::Plugin::Two;
sub some_event_order { 13 } # I get called relatively early
sub some_event { ... }

    sub _order { 10 } # I get listed by plugins_ordered() early

see how they're just, like, declaring where they want to be in the lineup? that's the whole magic. 🪄

---

💜 DESCRIPTION 💜

This module behaves exactly the same as Module::Pluggable — supporting all of its options — but it also mixes in the call_plugins and plugins_ordered methods to your class. two little besties, added to your class, no extra work. 🫶

call_plugins acts a little like Class::Trigger; it takes the name of a method, and some parameters. Let's say we call it like so:

__PACKAGE__->call_plugins("my_method", @something);

So here's what happens, step by step, no cap:

call_plugins looks at the plugin modules found using Module::Pluggable for ones which provide my_method_order. it sorts the modules numerically based on the result of this method, and then calls $_->my_method(@something) on them in order.

This produces an effect a little like the System V init process, where files can specify where in the init sequence they want to be called. iconic behaviour honestly. 👑

plugins_ordered extends the plugins method created by Module::Pluggable to list the plugins in defined order. it looks for a _order method in the modules found using Module::Pluggable, and returns the modules sorted numerically in that order. For example:

    my @plugins = __PACKAGE__->plugins();

The resulting array of plugins will be sorted. 💫

⚠️ heads up bestie: if no _order subroutine is defined for a module, an arbitrary default value of 50 is used. so like, mid. right in the middle. okay? okay. 💅

---

🎀 OPTIONS 🎀

• the package option — lets you put the pluggability into another package, to be used for modules building on the functionality of this one. very giving-other-packages-a-turn energy.

It also provides the only and except options. 🦋

     # will only return the Foo::Plugin::Quux plugin
     use Module::Pluggable::Ordered only => [ "Foo::Plugin::Quux" ];

     # will not return the Foo::Plugin::Quux plugin
     use Module::Pluggable::Ordered except => [ "Foo::Plugin::Quux" ];

---

🌈 SEE ALSO 🌈

• Module::Pluggable
• Class::Trigger

go read them, they're the blueprint, we're the remix. 💖

---

👑 AUTHOR 👑

• Simon Cozens, <simon@cpan.org> (author emeritus)
• Christopher Nehren, <apeiron@cpan.org> (current maintainer)

Please report bugs via the CPAN RT tracker at http://rt.cpan.org. 🐛 (be nice, they're doing their best, fr fr)

---

📜 COPYRIGHT AND LICENSE 📜

Copyright 2004 by Simon Cozens

Copyright 2004 by Christopher Nehren (current copyright holder)

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🫶 open source slay.

---

🧚 ACKNOWLEDGEMENTS 🧚

Thank you to Simon Cozens for originally writing this module. 💖

Thanks to Lars Thegler for indirectly alerting me to the fact that my POD was horribly broken, for providing patches to make this module work with Perl versions < 5.6, for maintaining the port up to version 1.3, and for allowing me to take maintainership for versions 1.3 onwards. that's a LOT of gratitude and honestly every single bit of it is earned. 🌸

---

and that's the whole page, bestie!! this doc shipped as part of perl v5.36.0, dated 2022-11-19, and it lives at Ordered(3pm). mwah. 💅✨ no notes.