POE::Component::Pluggable::Pipeline - the plugin pipeline for POE::Component::Pluggable.
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');
POE::Component::Pluggable::Pipeline defines the Plugin pipeline system for POE::Component::Pluggable instances.
new
Takes one argument, the POE::Component::Pluggable object to attach to.
push
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 end of the pipeline and
registers it. This will yield an 'plugin_add' event. If successful, 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 an '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 is 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, an empty list or undef will be returned.
my ($plug, $name) = $pipe->shift; my $plug = $pipe->shift;
pop
Takes no arguments. The last plugin in the pipeline is 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
Take 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 is 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 an 'plugin_del' event) and replaces it with the new
plugin. This will yield an '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 is 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 is 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. Otherwise, the plugin will be 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. 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
will be 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. 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. Otherwise, the index in the
pipeline is returned.
my $pos = $pipe->get_index($name); my $pos = $pipe->get_index($plug);
None known so far.
Jeff japhy Pinyan, japhy@perlmonk.org.
Chris BinGOs Williams, chris@bingosnet.co.uk.