NAME

POE::Component::IRC::Pipeline - the plugin pipeline for POE::Component::IRC.

SYNOPSIS

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

 my $irc = POE::Component::IRC->spawn;

 # 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
 $irc->plugin_add(mine => My::Plugin->new);
 $irc->pipeline->push(mine => My::Plugin->new);  

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

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

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

 # to get the pipeline object itself
 my $pipe = $irc->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');

DESCRIPTION

POE::Component::IRC::Pipeline defines the Plugin pipeline system for POE::Component::IRC instances.

METHODS

new

Takes one argument, the POE::Component::IRC object to attach to.

push

Take two arguments, an alias for a plugin and the plugin object itself. Adds the plugin to the end of the pipeline and registers it. If successful, it returns the size of the pipeline.

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

unshift

Take two arguments, an alias for a plugin and the plugin object itself. Adds the plugin to the beginning of the pipeline and registers it. This will yield an 'irc_plugin_add' event. If successful, it returns the size of the pipeline.

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

replace

Take three arguments, the old plugin or its alias, an alias for the new plugin and the new plugin object itself. Removes the old plugin (yielding an 'irc_plugin_del' event) and replaces it with the new plugin.This will yield an 'irc_plugin_add' event. If successful, it returns a true value.

 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. The new plugin is placed just prior to the other plugin in the pipeline. If successful, it returns a true value.

 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. The new plugin is placed just after to the other plugin in the pipeline. If successful, it returns a true value.

 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. 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. 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. The plugin is removed from the pipeline. This will yield an 'irc_plugin_del' event. If successful, it returns plugin and its alias in list context or just the plugin in scalar context.

 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);

shift

Takes no arguments. The first plugin in the pipeline is removed. This will yield an 'irc_plugin_del' event. If successful, it returns the plugin and its alias in list context or just the plugin in scalar context.

 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 'irc_plugin_del' event. If successful, it returns the plugin and its alias in list context or just the plugin in scalar context.

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

get

Takes one argument, a plugin or its alias. If successful, it returns the plugin and its alias in list context or just the plugin in scalar context.

 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. It returns the index in the pipeline if successful, otherwise -1 will be returned, not undef.

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

BUGS

None known so far.

SEE ALSO

POE::Component::IRC,

POE::Component::IRC::Plugin. Also look at

POE::Session::MultiDispatch which does something similar for session events.

AUTHOR

Jeff japhy Pinyan, <japhy@perlmonk.org>.