1MooseX::Object::PluggabUlsee(r3)Contributed Perl DocumenMtoaotsieoXn::Object::Pluggable(3)
2
6 MooseX::Object::Pluggable - Make your classes pluggable
7
9 version 0.0014
10
12 package MyApp;
13 use Moose;
14 with 'MooseX::Object::Pluggable';
16 ...
18 package MyApp::Plugin::Pretty;
20 use Moose::Role;
21 sub pretty{ print "I am pretty" }
23 1;
25 #
27 use MyApp;
28 my $app = MyApp->new;
29 $app->load_plugin('Pretty');
30 $app->pretty;
31
33 This module is meant to be loaded as a role from Moose-based classes.
34 It will add five methods and four attributes to assist you with the
35 loading and handling of plugins and extensions for plugins. I
36 understand that this may pollute your namespace, however I took great
37 care in using the least ambiguous names possible.
38
40 Plugins and extensions are just Roles by a fancy name. They are loaded
41 at runtime on demand and are instance, not class based. This means that
42 if you have more than one instance of a class they can all have
43 different plugins loaded. This is a feature.
44 Plugin methods are allowed to "around", "before", "after" their
46 consuming classes, so it is important to watch for load order as
47 plugins can and will overload each other. You may also add attributes
48 through "has".
49 Please note that when you load at runtime you lose the ability to wrap
51 "BUILD" and roles using "has" will not go through compile time checks
52 like "required" and "default".
53 Even though "override" will work, I STRONGLY discourage its use and a
55 warning will be thrown if you try to use it. This is closely linked to
56 the way multiple roles being applied is handled and is not likely to
57 change. "override" behavior is closely linked to inheritance and thus
58 will likely not work as you expect it in multiple inheritance
59 situations. Point being, save yourself the headache.
60
62 When roles are applied at runtime an anonymous class will wrap your
63 class and "$self->blessed", "ref $self" and "$self->meta->name" will no
64 longer return the name of your object; they will instead return the
65 name of the anonymous class created at runtime. See
66 "_original_class_name".
67
69 For a simple example see the tests included in this distribution.
70
72 _plugin_ns
73 String. The prefix to use for plugin names provided. "MyApp::Plugin" is
74 sensible.
75 _plugin_app_ns
77 An ArrayRef accessor that automatically dereferences into array on a
78 read call. By default it will be filled with the class name and its
79 precedents. It is used to determine which directories to look for
80 plugins as well as which plugins take precedence upon namespace
81 collisions. This allows you to subclass a pluggable class and still use
82 its plugins while using yours first if they are available.
83 _plugin_locator
85 An automatically built instance of Module::Pluggable::Object used to
86 locate available plugins.
87 _original_class_name
89 Because of the way roles apply, "$self->blessed", "ref $self" and
90 "$self->meta->name" will no longer return what you expect. Instead,
91 upon instantiation, the name of the class instantiated will be stored
92 in this attribute if you need to access the name the class held before
93 any runtime roles were applied.
94
96 load_plugins @plugins
97 load_plugin $plugin
98 Load the appropriate role for $plugin.
99
101 There's nothing stopping you from using these, but if you are using
102 them for anything that's not really complicated you are probably doing
103 something wrong.
104 _role_from_plugin $plugin
106 Creates a role name from a plugin name. If the plugin name is prepended
107 with a "+" it will be treated as a full name returned as is. Otherwise
108 a string consisting of $plugin prepended with the "_plugin_ns" and the
109 first valid value from "_plugin_app_ns" will be returned. Example
110 #assuming appname MyApp and C<_plugin_ns> 'Plugin'
112 $self->_role_from_plugin("MyPlugin"); # MyApp::Plugin::MyPlugin
113 _load_and_apply_role @roles
115 Require $role if it is not already loaded and apply it. This is the
116 meat of this module.
117 _build_plugin_app_ns
119 Automatically builds the _plugin_app_ns attribute with the classes in
120 the class precedence list that are not part of Moose.
121 _build_plugin_locator
123 Automatically creates a Module::Pluggable::Object instance with the
124 correct search_path.
125 meta
127 Keep tests happy. See Moose
128
130 Moose, Moose::Role, Class::Inspector
131
133 Holler?
134 Please report any bugs or feature requests to
136 "bug-MooseX-Object-Pluggable at rt.cpan.org", or through the web
137 interface at
138 <http://rt.cpan.org/Public/Dist/Display.html?Name=MooseX-Object-Pluggable>.
139 I will be notified, and then you'll automatically be notified of
140 progress on your bug as I make changes.
141
143 You can find documentation for this module with the perldoc command.
144 perldoc MooseX-Object-Pluggable
146 You can also look for information at:
148 • AnnoCPAN: Annotated CPAN documentation
150 <http://annocpan.org/dist/MooseX-Object-Pluggable>
152 • CPAN Ratings
154 <http://cpanratings.perl.org/d/MooseX-Object-Pluggable>
156 • RT: CPAN's request tracker
158 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-Object-Pluggable>
160 • Search CPAN
162 <http://search.cpan.org/dist/MooseX-Object-Pluggable>
164
166 #Moose - Huge number of questions
167 Matt S Trout <mst@shadowcatsystems.co.uk> - ideas / planning.
168 Stevan Little - EVERYTHING. Without him this would have never happened.
169 Shawn M Moore - bugfixes
170
172 Guillermo Roditi <groditi@cpan.org>
173
175 This software is copyright (c) 2007 by Guillermo Roditi
176 <groditi@cpan.org>.
177 This is free software; you can redistribute it and/or modify it under
179 the same terms as the Perl 5 programming language system itself.
180
182 • Karen Etheridge <ether@cpan.org>
183 • Shawn M Moore <sartak@gmail.com>
185 • Yuval Kogman <nothingmuch@woobling.org>
187 • Robert Boone <robo4288@gmail.com>
189 • David Steinbrunner <dsteinbrunner@pobox.com>
191 • Todd Hepler <thepler@employees.org>
193perl v5.34.0 2021-07-22 MooseX::Object::Pluggable(3)