Commit | Line | Data |
82cfc049 |
1 | package Moose::Policy; |
4fe62f68 |
2 | use Moose 'confess', 'blessed'; |
82cfc049 |
3 | |
4fe62f68 |
4 | our $VERSION = '0.03'; |
5 | our $AUTHORITY = 'cpan:STEVAN'; |
b9238462 |
6 | |
2756232e |
7 | sub import { |
8 | shift; |
9 | |
10 | my $policy = shift || return; |
11 | |
95c5abfd |
12 | unless (Class::MOP::is_class_loaded($policy)) { |
83d85197 |
13 | # otherwise require it ... |
4fe62f68 |
14 | eval { Class::MOP::load_class($policy) }; |
15 | confess "Could not load policy module '$policy' because : $@" |
83d85197 |
16 | if $@; |
2756232e |
17 | } |
18 | |
19 | my $package = caller(); |
20 | $package->can('meta') and |
09eff61e |
21 | croak("'$package' already has a meta() method, this is very problematic"); |
2756232e |
22 | |
23 | my $metaclass = 'Moose::Meta::Class'; |
24 | $metaclass = $policy->metaclass($package) |
25 | if $policy->can('metaclass'); |
26 | |
27 | my %options; |
28 | |
29 | # build options out of policy's constants |
4fe62f68 |
30 | $policy->can($_) and $options{"$_"} = $policy->$_($package) |
2756232e |
31 | for (qw( |
32 | attribute_metaclass |
33 | instance_metaclass |
34 | method_metaclass |
35 | )); |
36 | |
37 | # create a meta object so we can install &meta |
38 | my $meta = $metaclass->initialize($package => %options); |
39 | $meta->add_method('meta' => sub { |
40 | # we must re-initialize so that it works as expected in |
41 | # subclasses, since metaclass instances are singletons, this is |
42 | # not really a big deal anyway. |
43 | $metaclass->initialize((blessed($_[0]) || $_[0]) => %options) |
44 | }); |
45 | } |
46 | |
47 | 1; |
48 | |
49 | __END__ |
50 | |
51 | =pod |
52 | |
8e7059d6 |
53 | =head1 NAME |
54 | |
4fe62f68 |
55 | Moose::Policy - Moose-mounted police |
8e7059d6 |
56 | |
57 | =head1 SYNOPSIS |
58 | |
8e7059d6 |
59 | package Foo; |
60 | |
09eff61e |
61 | use Moose::Policy 'Moose::Policy::FollowPBP'; |
8e7059d6 |
62 | use Moose; |
63 | |
64 | has 'bar' => (is => 'rw', default => 'Foo::bar'); |
65 | has 'baz' => (is => 'ro', default => 'Foo::baz'); |
66 | |
09eff61e |
67 | # Foo now has (get, set)_bar methods as well as get_baz |
68 | |
2756232e |
69 | =head1 DESCRIPTION |
8e7059d6 |
70 | |
09eff61e |
71 | This module allows you to specify your project-wide or even company-wide |
72 | Moose meta-policy. |
8e7059d6 |
73 | |
09eff61e |
74 | Most all of Moose's features can be customized through the use of custom |
75 | metaclasses, however fiddling with the metaclasses can be hairy. Moose::Policy |
76 | removes most of that hairiness and makes it possible to cleanly contain |
77 | a set of meta-level customizations in one easy to use module. |
2756232e |
78 | |
4fe62f68 |
79 | This is still an release of this module and it should not be considered to |
1c037baf |
80 | be complete by any means. It is very basic implemenation at this point and |
09eff61e |
81 | will likely get more feature-full over time, as people request features. |
82 | So if you have a suggestion/need/idea, please speak up. |
83 | |
84 | =head2 What is a meta-policy? |
85 | |
86 | A meta-policy is a set of custom Moose metaclasses which can be used to |
87 | implement a number of customizations and restrictions on a particular |
88 | Moose class. |
89 | |
90 | For instance, L<Moose::Policy::SingleInheritence> enforces that all |
91 | specified Moose classes can only use single inheritence. It does this |
92 | by trapping the call to C<superclasses> on the metaclass and only allowing |
93 | you to assign a single superclass. |
94 | |
95 | The L<Moose::Policy::FollowPBP> policy changes the default behavior of |
96 | accessors to fit the recomendations found in Perl Best Practices. |
97 | |
98 | =head1 CAVEATS |
8e7059d6 |
99 | |
09eff61e |
100 | =head2 Always load Moose::Policy first. |
101 | |
102 | You B<must> put the following line of code: |
8e7059d6 |
103 | |
104 | use Moose::Policy 'My::Policy'; |
105 | |
09eff61e |
106 | before this line: |
8e7059d6 |
107 | |
108 | use Moose; |
109 | |
09eff61e |
110 | This is because Moose::Policy must be given the opportunity to set the |
111 | custom metaclass before Moose has set it's default metaclass. In fact, if |
112 | you try to set a Moose::Policy and there is a C<meta> method available, |
113 | not only will kittens die, but your program will too. |
114 | |
115 | =head2 Policys are class scoped |
116 | |
117 | You must repeat the policy for each class you want to us it. It is B<not> |
118 | inherited. This may change in the future, probably it will be a Moose::Policy |
119 | itself to allow Moose policys to be inherited. |
8e7059d6 |
120 | |
09eff61e |
121 | =head1 THE POLICY |
8e7059d6 |
122 | |
09eff61e |
123 | A Policy is set by passing C<Moose::Polocy::import()> a package name. This |
124 | package is then queried for what metaclasses it should use. The possible |
125 | metaclass values are: |
8e7059d6 |
126 | |
127 | =over |
128 | |
09eff61e |
129 | =item B<metaclass> |
8e7059d6 |
130 | |
09eff61e |
131 | This defaults to C<Moose::Meta::Class>. |
8e7059d6 |
132 | |
09eff61e |
133 | =item B<attribute_metaclass> |
8e7059d6 |
134 | |
09eff61e |
135 | =item B<instance_metaclass> |
8e7059d6 |
136 | |
09eff61e |
137 | =item B<method_metaclass> |
8e7059d6 |
138 | |
139 | =back |
140 | |
09eff61e |
141 | For examples of what a Policy actually looks like see the examples in |
142 | C<Moose::Policy::> and the test suite. More docs to come on this later (probably |
143 | a cookbook or something). |
8e7059d6 |
144 | |
4fe62f68 |
145 | =head1 METHODS |
146 | |
147 | =over 4 |
148 | |
149 | =item B<meta> |
150 | |
151 | =back |
152 | |
09eff61e |
153 | =head1 FUTURE PLANS |
8e7059d6 |
154 | |
09eff61e |
155 | As I said above, this is the first release and it is by no means feature complete. |
156 | There are a number of thoughts on the future direction of this module. Here are |
157 | some random thoughts on that, in no particular order. |
8e7059d6 |
158 | |
09eff61e |
159 | =over 4 |
8e7059d6 |
160 | |
09eff61e |
161 | =item Make set of policy roles |
8e7059d6 |
162 | |
09eff61e |
163 | Roles are an excellent way to combine sets of behaviors together into one, and |
164 | custom metaclasses are actually better composed by roles then by inheritence. |
165 | The ideal situation is that this module will provide a set of roles which can be |
166 | used to compose you meta-policy with relative ease. |
8e7059d6 |
167 | |
09eff61e |
168 | =back |
8e7059d6 |
169 | |
2756232e |
170 | =head1 BUGS |
8e7059d6 |
171 | |
2756232e |
172 | All complex software has bugs lurking in it, and this module is no |
173 | exception. If you find a bug please either email me, or add the bug |
174 | to cpan-RT. |
8e7059d6 |
175 | |
2756232e |
176 | =head1 AUTHOR |
8e7059d6 |
177 | |
2756232e |
178 | Stevan Little E<lt>stevan@iinteractive.comE<gt> |
8e7059d6 |
179 | |
83d85197 |
180 | Eric Wilhelm |
8e7059d6 |
181 | |
2756232e |
182 | =head1 COPYRIGHT AND LICENSE |
8e7059d6 |
183 | |
4fe62f68 |
184 | Copyright 2006-2007 by Infinity Interactive, Inc. |
b9238462 |
185 | |
2756232e |
186 | L<http://www.iinteractive.com> |
82cfc049 |
187 | |
2756232e |
188 | This library is free software; you can redistribute it and/or modify |
189 | it under the same terms as Perl itself. |
82cfc049 |
190 | |
2756232e |
191 | =cut |
bfacd619 |
192 | |