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

NAME

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

VERSION

9       version 0.0014
10

SYNOPSIS

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

DESCRIPTION

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

How plugins Work

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
45       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
50       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
54       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

How plugins are loaded

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

Usage

69       For a simple example see the tests included in this distribution.
70

Attributes

72   _plugin_ns
73       String. The prefix to use for plugin names provided. "MyApp::Plugin" is
74       sensible.
75
76   _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
84   _plugin_locator
85       An automatically built instance of Module::Pluggable::Object used to
86       locate available plugins.
87
88   _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

Public Methods

96   load_plugins @plugins
97   load_plugin $plugin
98       Load the appropriate role for $plugin.
99

Private Methods

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
105   _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
111          #assuming appname MyApp and C<_plugin_ns> 'Plugin'
112          $self->_role_from_plugin("MyPlugin"); # MyApp::Plugin::MyPlugin
113
114   _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
118   _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
122   _build_plugin_locator
123       Automatically creates a Module::Pluggable::Object instance with the
124       correct search_path.
125
126   meta
127       Keep tests happy. See Moose
128

SEE ALSO

130       Moose, Moose::Role, Class::Inspector
131

BUGS

133       Holler?
134
135       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

SUPPORT

143       You can find documentation for this module with the perldoc command.
144
145           perldoc MooseX-Object-Pluggable
146
147       You can also look for information at:
148
149       •   AnnoCPAN: Annotated CPAN documentation
150
151           <http://annocpan.org/dist/MooseX-Object-Pluggable>
152
153       •   CPAN Ratings
154
155           <http://cpanratings.perl.org/d/MooseX-Object-Pluggable>
156
157       •   RT: CPAN's request tracker
158
159           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-Object-Pluggable>
160
161       •   Search CPAN
162
163           <http://search.cpan.org/dist/MooseX-Object-Pluggable>
164

ACKNOWLEDGEMENTS

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

AUTHOR

172       Guillermo Roditi <groditi@cpan.org>
173
175       This software is copyright (c) 2007 by Guillermo Roditi
176       <groditi@cpan.org>.
177
178       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

CONTRIBUTORS

182       •   Karen Etheridge <ether@cpan.org>
183
184       •   Shawn M Moore <sartak@gmail.com>
185
186       •   Yuval Kogman <nothingmuch@woobling.org>
187
188       •   Robert Boone <robo4288@gmail.com>
189
190       •   David Steinbrunner <dsteinbrunner@pobox.com>
191
192       •   Todd Hepler <thepler@employees.org>
193
194
195
196perl v5.36.0                      2023-01-20      MooseX::Object::Pluggable(3)
Impressum