1POE::Component::PluggabUlsee:r:PCiopnetlriinbeu(t3e)d PePrOlE:D:oCcoummpeonnteantti:o:nPluggable::Pipeline(3)
2
3
4
6 POE::Component::Pluggable::Pipeline - the plugin pipeline for
7 POE::Component::Pluggable.
8
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
66 POE::Component::Pluggable::Pipeline defines the Plugin pipeline system
67 for POE::Component::Pluggable instances.
68
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
204 None known so far.
205
207 Jeff "japhy" Pinyan, japhy@perlmonk.org.
208
210 Chris "BinGOs" Williams, chris@bingosnet.co.uk.
211
213 POE::Component::IRC,
214
215 POE::Component::Pluggable.
216
217
218
219perl v5.12.0 2009-08P-O1E8::Component::Pluggable::Pipeline(3)