POE::Component::Pluggable::Pipeline(3pm)

1POE::Component::PluggabUlsee:r:PCiopnetlriinbeu(t3e)d PePrOlE:D:oCcoummpeonnteantti:o:nPluggable::Pipeline(3)
2
3
4

NAME

6       POE::Component::Pluggable::Pipeline - the plugin pipeline for
7       POE::Component::Pluggable.
8

SYNOPSIS

10         use POE qw( Component::Pluggable );
11         use POE::Component::Pluggable::Pipeline;
12         use My::Plugin;
13
14         my $self = POE::Component::Pluggable->new();
15
16         # the following operations are presented in pairs
17         # the first is the general procedure, the second is
18         # the specific way using the pipeline directly
19
20         # to install a plugin
21         $self->plugin_add(mine => My::Plugin->new);
22         $self->pipeline->push(mine => My::Plugin->new);
23
24         # to remove a plugin
25         $self->plugin_del('mine');        # or the object
26         $self->pipeline->remove('mine');  # or the object
27
28         # to get a plugin
29         my $plug = $self->plugin_get('mine');
30         my $plug = $self->pipeline->get('mine');
31
32         # there are other very specific operations that
33         # the pipeline offers, demonstrated here:
34
35         # to get the pipeline object itself
36         my $pipe = $self->pipeline;
37
38         # to install a plugin at the front of the pipeline
39         $pipe->unshift(mine => My::Plugin->new);
40
41         # to remove the plugin at the end of the pipeline
42         my $plug = $pipe->pop;
43
44         # to remove the plugin at the front of the pipeline
45         my $plug = $pipe->shift;
46
47         # to replace a plugin with another
48         $pipe->replace(mine => newmine => My::Plugin->new);
49
50         # to insert a plugin before another
51         $pipe->insert_before(mine => newmine => My::Plugin->new);
52
53         # to insert a plugin after another
54         $pipe->insert_after(mine => newmine => My::Plugin->new);
55
56         # to get the location in the pipeline of a plugin
57         my $index = $pipe->get_index('mine');
58
59         # to move a plugin closer to the front of the pipeline
60         $pipe->bump_up('mine');
61
62         # to move a plugin closer to the end of the pipeline
63         $pipe->bump_down('mine');
64

DESCRIPTION

66       POE::Component::Pluggable::Pipeline defines the Plugin pipeline system
67       for POE::Component::Pluggable instances.
68

METHODS

70   "new"
71       Takes one argument, the POE::Component::Pluggable object to attach to.
72
73   "push"
74       Takes two arguments, an alias for a plugin and the plugin object
75       itself.  If a plugin with that alias already exists, $@ will be set and
76       "undef" will be returned. Otherwise, it adds the plugin to the end of
77       the pipeline and registers it. This will yield a "plugin_add" event. If
78       successful, it returns the size of the pipeline.
79
80        my $new_size = $pipe->push($name, $plug);
81
82   "unshift"
83       Takes two arguments, an alias for a plugin and the plugin object
84       itself.  If a plugin with that alias already exists, $@ will be set and
85       "undef" will be returned. Otherwise, it adds the plugin to the
86       beginning of the pipeline and registers it. This will yield a
87       "plugin_add" event. If successful, it returns the size of the pipeline.
88
89        my $new_size = $pipe->push($name, $plug);
90
91   "shift"
92       Takes no arguments. The first plugin in the pipeline is removed. This
93       will yield a "plugin_del" event. In list context, it returns the plugin
94       and its alias; in scalar context, it returns only the plugin. If there
95       were no elements, an empty list or "undef" will be returned.
96
97        my ($plug, $name) = $pipe->shift;
98        my $plug = $pipe->shift;
99
100   "pop"
101       Takes no arguments. The last plugin in the pipeline is removed. This
102       will yield an "plugin_del" event. In list context, it returns the
103       plugin and its alias; in scalar context, it returns only the plugin. If
104       there were no elements, an empty list or "undef" will be returned.
105
106        my ($plug, $name) = $pipe->pop;
107        my $plug = $pipe->pop;
108
109   "replace"
110       Take three arguments, the old plugin or its alias, an alias for the new
111       plugin and the new plugin object itself. If the old plugin doesn't
112       exist, or if there is already a plugin with the new alias (besides the
113       old plugin), $@ will be set and "undef" will be returned. Otherwise, it
114       removes the old plugin (yielding an "plugin_del" event) and replaces it
115       with the new plugin. This will yield an "plugin_add" event. If
116       successful, it returns 1.
117
118        my $success = $pipe->replace($name, $new_name, $new_plug);
119        my $success = $pipe->replace($plug, $new_name, $new_plug);
120
121   "insert_before"
122       Takes three arguments, the plugin that is relative to the operation, an
123       alias for the new plugin and the new plugin object itself. If the first
124       plugin doesn't exist, or if there is already a plugin with the new
125       alias, $@ will be set and "undef" will be returned. Otherwise, the new
126       plugin is placed just prior to the other plugin in the pipeline. If
127       successful, it returns 1.
128
129        my $success = $pipe->insert_before($name, $new_name, $new_plug);
130        my $success = $pipe->insert_before($plug, $new_name, $new_plug);
131
132   "insert_after"
133       Takes three arguments, the plugin that is relative to the operation, an
134       alias for the new plugin and the new plugin object itself. If the first
135       plugin doesn't exist, or if there is already a plugin with the new
136       alias, $@ will be set and "undef" will be returned. Otherwise, the new
137       plugin is placed just after to the other plugin in the pipeline.  If
138       successful, it returns 1.
139
140        my $success = $pipe->insert_after($name, $new_name, $new_plug);
141        my $success = $pipe->insert_after($plug, $new_name, $new_plug);
142
143   "bump_up"
144       Takes one or two arguments, the plugin or its alias, and the distance
145       to bump the plugin. The distance defaults to 1. If the plugin doesn't
146       exist, $@ will be set and -1 will be returned, not undef. Otherwise,
147       the plugin will be moved the given distance closer to the front of the
148       pipeline. A warning is issued alerting you if it would have been moved
149       past the beginning of the pipeline, and the plugin is placed at the
150       beginning. If successful, the new index of the plugin in the pipeline
151       is returned.
152
153        my $pos = $pipe->bump_up($name);
154        my $pos = $pipe->bump_up($plug);
155        my $pos = $pipe->bump_up($name, $delta);
156        my $pos = $pipe->bump_up($plug, $delta);
157
158   "bump_down"
159       Takes one or two arguments, the plugin or its alias, and the distance
160       to bump the plugin. The distance defaults to 1. If the plugin doesn't
161       exist, $@ will be set and -1 will be returned, not "undef". Otherwise,
162       the plugin will be moved the given distance closer to the end of the
163       pipeline.  A warning is issued alerting you if it would have been moved
164       past the end of the pipeline, and the plugin is placed at the end. If
165       successful, the new index of the plugin in the pipeline is returned.
166
167        my $pos = $pipe->bump_down($name);
168        my $pos = $pipe->bump_down($plug);
169        my $pos = $pipe->bump_down($name, $delta);
170        my $pos = $pipe->bump_down($plug, $delta);
171
172   "remove"
173       Takes one argument, a plugin or its alias. If the plugin doesn't exist,
174       $@ will be set and "undef" will be returned. Otherwise, the plugin is
175       removed from the pipeline. This will yield an "plugin_del" event. In
176       list context,it returns the plugin and its alias; in scalar context, it
177       returns only the plugin.
178
179        my ($plug, $name) = $pipe->remove($the_name);
180        my ($plug, $name) = $pipe->remove($the_plug);
181        my $plug = $pipe->remove($the_name);
182        my $plug = $pipe->remove($the_plug);
183
184   "get"
185       Takes one argument, a plugin or its alias. If no such plugin exists, $@
186       will be set and "undef" will be returned. In list context, it returns
187       the plugin and its alias; in scalar context, it returns only the
188       plugin.
189
190        my ($plug, $name) = $pipe->get($the_name);
191        my ($plug, $name) = $pipe->get($the_plug);
192        my $plug = $pipe->get($the_name);
193        my $plug = $pipe->get($the_plug);
194
195   "get_index"
196       Takes one argument, a plugin or its alias. If no such plugin exists, $@
197       will be set and -1 will be returned, not "undef". Otherwise, the index
198       in the pipeline is returned.
199
200        my $pos = $pipe->get_index($name);
201        my $pos = $pipe->get_index($plug);
202

BUGS

204       None known so far.
205

AUTHOR

207       Jeff "japhy" Pinyan, japhy@perlmonk.org.
208

MAINTAINER

210       Chris "BinGOs" Williams, chris@bingosnet.co.uk.
211