MooseX::Object::Pluggable(3pm)

1MooseX::Object::PluggabUlsee(r3)Contributed Perl DocumenMtoaotsieoXn::Object::Pluggable(3)
2
3
4

NAME

6           MooseX::Object::Pluggable - Make your classes pluggable
7

SYNOPSIS

9           package MyApp;
10           use Moose;
11
12           with 'MooseX::Object::Pluggable';
13
14           ...
15
16           package MyApp::Plugin::Pretty;
17           use Moose::Role;
18
19           sub pretty{ print "I am pretty" }
20
21           1;
22
23           #
24           use MyApp;
25           my $app = MyApp->new;
26           $app->load_plugin('Pretty');
27           $app->pretty;
28

DESCRIPTION

30       This module is meant to be loaded as a role from Moose-based classes it
31       will add five methods and four attributes to assist you with the load‐
32       ing and handling of plugins and extensions for plugins. I understand
33       that this may pollute your namespace, however I took great care in
34       using the least ambiguous names possible.
35

How plugins Work

37       Plugins and extensions are just Roles by a fancy name. They are loaded
38       at runtime on demand and are instance, not class based. This means that
39       if you have more than one instance of a class they can all have differ‐
40       ent plugins loaded. This is a feature.
41
42       Plugin methods are allowed to "around", "before", "after" their consum‐
43       ing classes, so it is important to watch for load order as plugins can
44       and will overload each other. You may also add attributes through has.
45
46       Please note that when you load at runtime you lose the ability to wrap
47       "BUILD" and roles using "has" will not go through comile time checks
48       like "required" and <default>.
49
50       Even though "override" will work , I STRONGLY discourage it's use and a
51       warning will be thrown if you try to use it.  This is closely linked to
52       the way multiple roles being applies is handles and is not likely to
53       change. "override" bevavior is closely linked to inheritance and thus
54       will likely not work as you expect it in multiple inheritance situa‐
55       tions. Point being, save yourself the headache.
56

How plugins are loaded

58       When roles are applied at runtime an anonymous class will wrap your
59       class and "$self->blessed" and "ref $self" will no longer return the
60       name of your object, they will instead return the name of the anonymous
61       class created at runtime.  See "_original_class_name".
62

Usage

64       For a simple example see the tests included in this distribution.
65

Attributes

67       _plugin_ns
68
69       String. The prefix to use for plugin names provided. MyApp::Plugin is
70       sensible.
71
72       _plugin_ext
73
74       Boolean. Indicates whether we should attempt to load plugin extensions.
75       Defaults to true;
76
77       _plugin_ext_ns
78
79       String. The namespace plugin extensions have. Defaults to 'Extension‐
80       For'.
81
82       This means that is _plugin_ns is "MyApp::Plugin" and _plugin_ext_ns is
83       "ExtensionFor" loading plugin "Bar" would search for extensions in
84       "MyApp::Plugin::Bar::ExtensionFor::*".
85
86       _plugin_app_ns
87
88       ArrayRef, Accessor automatically dereferences into array on a read
89       call.  By default will be filled with the class name and it's presce‐
90       dents, it is used to determine which directories to look for plugins as
91       well as which plugins take presedence upon namespace collitions. This
92       allows you to subclass a pluggable class and still use it's plugins
93       while using yours first if they are available.
94
95       _plugin_locator
96
97       An automatically built instance of Module::Pluggable::Object used to
98       locate available plugins.
99

Public Methods

101       load_plugin $plugin
102
103       This is the only method you should be using. Load the apropriate role
104       for $plugin as well as any extensions it provides if extensions are
105       enabled.
106
107       load_plugin_ext
108
109       Will load any extensions for a particular plugin. This should be called
110       automatically by "load_plugin" so you don't need to worry about it.  It
111       basically attempts to load any extension that exists for a plugin that
112       is already loaded. The only reason for using this is if you want to
113       keep _plugin_ext as false and only load extensions manually, which I
114       don't recommend.
115
116       _original_class_name
117
118       Because of the way roles apply "$self->blessed" and "ref $self" will no
119       longer return what you expect. Instead use this class to get your orig‐
120       inal class name.
121

Private Methods

123       There's nothing stopping you from using these, but if you are using
124       them for anything thats not really complicated you are probably doing
125       something wrong. Some of these may be inlined in the future if perfor‐
126       mance becomes an issue (which I doubt).
127
128       _role_from_plugin $plugin
129
130       Creates a role name from a plugin name. If the plugin name is prepended
131       with a "+" it will be treated as a full name returned as is. Otherwise
132       a string consisting of $plugin  prepended with the "_plugin_ns" and the
133       first valid value from "_plugin_app_ns" will be returned. Example
134
135          #assuming appname MyApp and C<_plugin_ns> 'Plugin'
136          $self->_role_from_plugin("MyPlugin"); # MyApp::Plugin::MyPlugin
137
138       _load_and_apply_role $role
139
140       Require $role if it is not already loaded and apply it. This is the
141       meat of this module.
142
143       _build_plugin_app_ns
144
145       Automatically builds the _plugin_app_ns attribute with the classes in
146       the class presedence list that are not part of Moose.
147
148       _build_plugin_locator
149
150       Automatically creates a Module::Pluggable::Object instance with the
151       correct search_path.
152
153       meta
154
155       Keep tests happy. See Moose
156

AUTHOR

161       Guillermo Roditi, <groditi@cpan.org>
162

BUGS

164       Holler?
165
166       Please report any bugs or feature requests to "bug-moosex-object-plug‐
167       gable at rt.cpan.org", or through the web interface at
168       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MooseX-Object-Plug‐
169       gable>.  I will be notified, and then you'll automatically be notified
170       of progress on your bug as I make changes.
171

SUPPORT

173       You can find documentation for this module with the perldoc command.
174
175           perldoc MooseX-Object-Pluggable
176
177       You can also look for information at:
178
179       * AnnoCPAN: Annotated CPAN documentation
180           <http://annocpan.org/dist/MooseX-Object-Pluggable>
181
182       * CPAN Ratings
183           <http://cpanratings.perl.org/d/MooseX-Object-Pluggable>
184
185       * RT: CPAN's request tracker
186           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-Object-Pluggable>
187
188       * Search CPAN
189           <http://search.cpan.org/dist/MooseX-Object-Pluggable>
190

ACKNOWLEDGEMENTS

192       #Moose - Huge number of questions
193       Matt S Trout <mst@shadowcatsystems.co.uk> - ideas / planning.
194       Stevan Little - EVERYTHING. Without him this would have never happened.
195

COPYRIGHT

197       Copyright 2007 Guillermo Roditi.  All Rights Reserved.  This is free
198       software; you may redistribute it and/or modify it under the same terms
199       as Perl itself.
200
201
202
203perl v5.8.8                       2007-04-16      MooseX::Object::Pluggable(3)