Object::Pluggable::PipUsereContributed Perl DocuObject::Pluggable::Pipeline(3)NAMEObject::Pluggable::Pipeline - The plugin pipeline for
Object::Pluggable.
SYNOPSIS
use Object::Pluggable;
use Object::Pluggable::Pipeline;
use My::Plugin;
my $self = Object::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');
DESCRIPTIONObject::Pluggable::Pipeline defines the Plugin pipeline system for
Object::Pluggable instances.
METHODS
"new"
Takes one argument, the Object::Pluggable object to attach to.
"push"
Takes at least two arguments, an alias for a plugin and the plugin
object itself. Any extra arguments will be passed to the register
method of the plugin object. 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
a "plugin_add" event. If successful, it returns the size of the
pipeline.
my $new_size = $pipe->push($name, $plug, @register_args);
"unshift"
Takes at least two arguments, an alias for a plugin and the plugin
object itself. Any extra arguments will be passed to the register
method of the plugin object. 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, @register_args);
"shift"
Takes any number of arguments. The first plugin in the pipeline is
removed. Any arguments will be passed to the unregister method of the
plugin object. 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(@unregister_args);
my $plug = $pipe->shift(@unregister_args);
"pop"
Takes any number of arguments. The last plugin in the pipeline is
removed. Any arguments will be passed to the unregister method of the
plugin object. 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(@unregister_args);
my $plug = $pipe->pop(@unregister_args);
"replace"
Takes at least three arguments, the old plugin or its alias, an alias
for the new plugin and the new plugin object itself. You can optionally
pass two array references of arguments which will be delivered to the
unregister method of the old plugin and the register method of the new
plugin, respectively. If you only want to pass the latter, you can put
"undef" in place of the former. 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, \@unregister_args, \@register_args);
my $success = $pipe->replace($plug, $new_name, $new_plug, \@unregister_args, \@register_args);
"insert_before"
Takes at least three arguments, the plugin that is relative to the
operation, an alias for the new plugin and the new plugin object
itself. Any extra arguments will be passed to the register method of
the new plugin object. 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, @register_args);
my $success = $pipe->insert_before($plug, $new_name, $new_plug, @register_args);
"insert_after"
Takes at least three arguments, the plugin that is relative to the
operation, an alias for the new plugin and the new plugin object
itself. any extra arguments will be passed to the register method of
the new plugin object. 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, @register_args);
my $success = $pipe->insert_after($plug, $new_name, $new_plug, @register_args);
"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 at least one argument, a plugin or its alias. Any arguments will
be passed to the unregister method of the plugin object. 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, @unregister_args);
my ($plug, $name) = $pipe->remove($the_plug, @unregister_args);
my $plug = $pipe->remove($the_name, @unregister_args);
my $plug = $pipe->remove($the_plug, @unregister_args);
"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);
BUGS
None known so far.
AUTHOR
Jeff "japhy" Pinyan, japhy@perlmonk.org.
MAINTAINER
Chris "BinGOs" Williams, chris@bingosnet.co.uk.
SEE ALSO
Object::Pluggable.
POE::Component::IRC,
perl v5.14.1 2010-10-09 Object::Pluggable::Pipeline(3)
