POE::Co...Pipeline(3)

📦
version 1.28 · 2 versions
, in fedora 43

💖 POE::Component::Pluggable::Pipeline 💖

okay bestie, so this is the manual page for POE::Component::Pluggable::Pipeline (yeah the header abbreviates it as POE::Co...Pipeline(3) because the full name is lowkey doing the most, but we're saying the whole thing, periodt).

✨ VERSION ✨

version 1.28 — she's serving 1.28, no cap 💅

🦋 SYNOPSIS 🦋

okay so here's the vibe. You use it like this, bestie:

use POE qw( Component::Pluggable );
use POE::Component::Pluggable::Pipeline;
use My::Plugin;

my $self = POE::Component::Pluggable->new();

# the following operations are presented in pairs
# the first is the general procedure, the second is
# the specific way using the pipeline directly

# to install a plugin
$self->plugin_add(mine => My::Plugin->new);
$self->pipeline->push(mine => My::Plugin->new);

# to remove a plugin
$self->plugin_del('mine');        # or the object
$self->pipeline->remove('mine');  # or the object

# to get a plugin
my $plug = $self->plugin_get('mine');
my $plug = $self->pipeline->get('mine');

# there are other very specific operations that
# the pipeline offers, demonstrated here:

# to get the pipeline object itself
my $pipe = $self->pipeline;

# to install a plugin at the front of the pipeline
$pipe->unshift(mine => My::Plugin->new);

# to remove the plugin at the end of the pipeline
my $plug = $pipe->pop;

# to remove the plugin at the front of the pipeline
my $plug = $pipe->shift;

# to replace a plugin with another
$pipe->replace(mine => newmine => My::Plugin->new);

# to insert a plugin before another
$pipe->insert_before(mine => newmine => My::Plugin->new);

# to insert a plugin after another
$pipe->insert_after(mine => newmine => My::Plugin->new);

# to get the location in the pipeline of a plugin
my $index = $pipe->get_index('mine');

# to move a plugin closer to the front of the pipeline
$pipe->bump_up('mine');

# to move a plugin closer to the end of the pipeline
$pipe->bump_down('mine');

the way this is all in pairs — one "do it the normal way", one "do it by reaching into the pipeline yourself" — is genuinely iconic of them, honestly 🫶

🌸 DESCRIPTION 🌸

POE::Component::Pluggable::Pipeline defines the Plugin pipeline system for POE::Component::Pluggable instances. That's it, that's the whole job, and she does it gorgeously 💖

👑 METHODS 👑

new ✨

Takes one argument: the POE::Component::Pluggable object she's attaching herself to. That's her person. That's her whole world.

push 💫

Takes two arguments — an alias for a plugin, and the plugin object itself. If a plugin with that alias already exists? $@ gets set and undef gets returned, sorry babe 😭. Otherwise it adds the plugin to the end of the pipeline and registers it. This will yield a plugin_add event. If it works, it returns the size of the pipeline.

my $new_size = $pipe->push($name, $plug);

unshift 🌈

Takes two arguments — an alias for a plugin, and the plugin object itself. If a plugin with that alias already exists, $@ will be set and undef will be returned. Otherwise, it adds the plugin to the beginning of the pipeline and registers it. This will yield a plugin_add event. If successful, it returns the size of the pipeline.

my $new_size = $pipe->push($name, $plug);

shift 🎀

Takes no arguments. The first plugin in the pipeline gets removed. This will yield a plugin_del event. In list context, it returns the plugin and its alias; in scalar context, it returns only the plugin. If there were no elements, you get an empty list or undef back. Choose your own adventure bestie.

my ($plug, $name) = $pipe->shift;
my $plug = $pipe->shift;

pop 🍓

Takes no arguments. The last plugin in the pipeline gets removed. This will yield an plugin_del event. In list context, it returns the plugin and its alias; in scalar context, it returns only the plugin. If there were no elements, an empty list or undef will be returned.

my ($plug, $name) = $pipe->pop;
my $plug = $pipe->pop;

replace 🔥

Takes three arguments: the old plugin or its alias, an alias for the new plugin, and the new plugin object itself. If the old plugin doesn't exist, or if there's already a plugin with the new alias (besides the old plugin), $@ will be set and undef will be returned. Otherwise, it removes the old plugin (yielding a plugin_del event) and replaces it with the new plugin. This will yield a plugin_add event. If successful, it returns 1.

my $success = $pipe->replace($name, $new_name, $new_plug);
my $success = $pipe->replace($plug, $new_name, $new_plug);

insert_before 💜

Takes three arguments: the plugin that is relative to the operation, an alias for the new plugin, and the new plugin object itself. If the first plugin doesn't exist, or if there's already a plugin with the new alias, $@ will be set and undef will be returned. Otherwise, the new plugin is placed just prior to the other plugin in the pipeline. If successful, it returns 1.

my $success = $pipe->insert_before($name, $new_name, $new_plug);
my $success = $pipe->insert_before($plug, $new_name, $new_plug);

insert_after 🧚

Takes three arguments: the plugin that is relative to the operation, an alias for the new plugin, and the new plugin object itself. If the first plugin doesn't exist, or if there's already a plugin with the new alias, $@ will be set and undef will be returned. Otherwise, the new plugin is placed just after to the other plugin in the pipeline. If successful, it returns 1.

my $success = $pipe->insert_after($name, $new_name, $new_plug);
my $success = $pipe->insert_after($plug, $new_name, $new_plug);

bump_up 🌟

Takes one or two arguments: the plugin or its alias, and the distance to bump the plugin. The distance defaults to 1. If the plugin doesn't exist, $@ will be set and -1 will be returned — not undef, okay, write that down 📝. Otherwise, the plugin gets moved the given distance closer to the front of the pipeline. A warning is issued alerting you if it would have been moved past the beginning of the pipeline, and the plugin is placed at the beginning instead. If successful, the new index of the plugin in the pipeline is returned.

my $pos = $pipe->bump_up($name);
my $pos = $pipe->bump_up($plug);
my $pos = $pipe->bump_up($name, $delta);
my $pos = $pipe->bump_up($plug, $delta);

bump_down 💅

Takes one or two arguments: the plugin or its alias, and the distance to bump the plugin. The distance defaults to 1. If the plugin doesn't exist, $@ will be set and -1 will be returned — not undef. Otherwise, the plugin gets moved the given distance closer to the end of the pipeline. A warning is issued alerting you if it would have been moved past the end of the pipeline, and the plugin is placed at the end instead. If successful, the new index of the plugin in the pipeline is returned.

my $pos = $pipe->bump_down($name);
my $pos = $pipe->bump_down($plug);
my $pos = $pipe->bump_down($name, $delta);
my $pos = $pipe->bump_down($plug, $delta);

remove 🫶

Takes one argument: a plugin or its alias. If the plugin doesn't exist, $@ will be set and undef will be returned. Otherwise, the plugin is removed from the pipeline. This will yield an plugin_del event. In list context, it returns the plugin and its alias; in scalar context, it returns only the plugin.

my ($plug, $name) = $pipe->remove($the_name);
my ($plug, $name) = $pipe->remove($the_plug);
my $plug = $pipe->remove($the_name);
my $plug = $pipe->remove($the_plug);

get 🔍

Takes one argument: a plugin or its alias. If no such plugin exists, $@ will be set and undef will be returned. In list context, it returns the plugin and its alias; in scalar context, it returns only the plugin.

my ($plug, $name) = $pipe->get($the_name);
my ($plug, $name) = $pipe->get($the_plug);
my $plug = $pipe->get($the_name);
my $plug = $pipe->get($the_plug);

get_index ⭐

Takes one argument: a plugin or its alias. If no such plugin exists, $@ will be set and -1 will be returned — not undef, okay?! Otherwise, the index in the pipeline is returned.

my $pos = $pipe->get_index($name);
my $pos = $pipe->get_index($plug);

💀 BUGS 💀

None known so far. She's flawless, she's unbothered, she's not taking questions at this time 💅✨

🌈 SEE ALSO 🌈

  • POE::Component::IRC,
  • POE::Component::Pluggable.

🎀 AUTHORS 🎀

  • Chris Williams <chris@bingosnet.co.uk>
  • Apocalypse <perl@0ne.us>
  • Hinrik Örn Sigurðsson
  • Jeff Pinyan

the whole group chat came together for this one, we love to see it 🫶

This software is copyright (c) 2017 by Chris Williams.

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

okay bestie that's the whole page, and that's the vibe check passed 💅 This whole thing came to you via perl v5.42.0 on 2025-07-25, from the manual page POE::Co...Pipeline(3) — go forth and pipeline, you absolute icon 🌸👑

📦 where this page comes from