Object::Pluggable::Pipeline(3pm)

1Object::Pluggable::PipeUlsienre(C3o)ntributed Perl DocumOebnjteactti:o:nPluggable::Pipeline(3)
2
3
4

NAME

6       Object::Pluggable::Pipeline - The plugin pipeline for
7       Object::Pluggable.
8

SYNOPSIS

10         use Object::Pluggable;
11         use Object::Pluggable::Pipeline;
12         use My::Plugin;
13
14         my $self = Object::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       Object::Pluggable::Pipeline defines the Plugin pipeline system for
67       Object::Pluggable instances.
68

METHODS

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

BUGS

219       None known so far.
220

AUTHOR

222       Jeff "japhy" Pinyan, japhy@perlmonk.org.
223

MAINTAINER

225       Chris "BinGOs" Williams, chris@bingosnet.co.uk.
226