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

VERSION

10       version 1.28
11

SYNOPSIS

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

DESCRIPTION

69       POE::Component::Pluggable::Pipeline defines the Plugin pipeline system
70       for POE::Component::Pluggable instances.
71

METHODS

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

BUGS

207       None known so far.
208

AUTHORS

215       •   Chris Williams <chris@bingosnet.co.uk>
216
217       •   Apocalypse <perl@0ne.us>
218
219       •   Hinrik Örn Sigurðsson
220
221       •   Jeff Pinyan
222

COPYRIGHT AND LICENSE

224       This software is copyright (c) 2017 by Chris Williams.
225
226       This is free software; you can redistribute it and/or modify it under
227       the same terms as the Perl 5 programming language system itself.
228
229
230
231perl v5.38.0                      2023-07P-O2E1::Component::Pluggable::Pipeline(3)