dd40d5147ea565c77487e9971bf61649ac25d116
[gitmo/Moose.git] / lib / Moose / Cookbook / Snack / Keywords.pod
1 package Moose::Cookbook::Snack::Keywords;
2
3 # ABSTRACT: Restricted "keywords" in Moose
4
5 __END__
6
7 =pod
8
9 =head1 DESCRIPTION
10
11 Moose exports a number of sugar functions in order to emulate Perl
12 built-in keywords. These can cause clashes with other user-defined
13 functions. This document provides a list of those keywords for easy
14 reference.
15
16 =head2 The 'meta' keyword
17
18 C<S<use Moose>> adds a method called C<meta> to your class. If this
19 conflicts with a method or function you are using, you can rename it,
20 or prevent it from being installed entirely. To do this, pass the
21 C<-meta_name> option when you C<S<use Moose>>. For instance:
22
23   # install it under a different name
24   use Moose -meta_name => 'moose_meta';
25
26   # don't install it at all
27   use Moose -meta_name => undef;
28
29 =head2 Moose Keywords
30
31 If you are using L<Moose> or L<Moose::Role> it is best to avoid these
32 keywords:
33
34 =over 4
35
36 =item extends
37
38 =item with
39
40 =item has
41
42 =item before
43
44 =item after
45
46 =item around
47
48 =item super
49
50 =item override
51
52 =item inner
53
54 =item augment
55
56 =item confess
57
58 =item blessed
59
60 =back
61
62 =head2 Moose::Util::TypeConstraints Keywords
63
64 If you are using L<Moose::Util::TypeConstraints> it is best to avoid
65 these keywords:
66
67 =over 4
68
69 =item type
70
71 =item subtype
72
73 =item class_type
74
75 =item role_type
76
77 =item maybe_type
78
79 =item duck_type
80
81 =item as
82
83 =item where
84
85 =item message
86
87 =item optimize_as
88
89 =item inline_as
90
91 =item coerce
92
93 =item from
94
95 =item via
96
97 =item enum
98
99 =item find_type_constraint
100
101 =item register_type_constraint
102
103 =back
104
105 =head2 Avoiding collisions
106
107 =head3 Turning off Moose
108
109 To remove the sugar functions L<Moose> exports, just add C<S<no Moose>>
110 at the bottom of your code:
111
112   package Thing;
113   use Moose;
114
115   # code here
116
117   no Moose;
118
119 This will unexport the sugar functions that L<Moose> originally
120 exported. The same will also work for L<Moose::Role> and
121 L<Moose::Util::TypeConstraints>.
122
123 =head3 Sub::Exporter features
124
125 L<Moose>, L<Moose::Role> and L<Moose::Util::TypeConstraints> all use
126 L<Sub::Exporter> to handle all their exporting needs. This means that
127 all the features that L<Sub::Exporter> provides are also available to
128 them.
129
130 For instance, with L<Sub::Exporter> you can rename keywords, like so:
131
132   package LOL::Cat;
133   use Moose 'has' => { -as => 'i_can_haz' };
134
135   i_can_haz 'cheeseburger' => (
136       is      => 'rw',
137       trigger => sub { print "NOM NOM" }
138   );
139
140   LOL::Cat->new->cheeseburger('KTHNXBYE');
141
142 See the L<Sub::Exporter> docs for more information.
143
144 =head3 namespace::autoclean and namespace::clean
145
146 You can also use L<namespace::autoclean> to clean up your namespace.
147 This will remove all imported functions from your namespace. Note
148 that if you are importing functions that are intended to be used as
149 methods (this includes L<overload>, due to internal implementation
150 details), it will remove these as well.
151
152 Another option is to use L<namespace::clean> directly, but
153 you must be careful not to remove C<meta> when doing so:
154
155   package Foo;
156   use Moose;
157   use namespace::clean -except => 'meta';
158   # ...
159
160 =head1 SEE ALSO
161
162 =over 4
163
164 =item L<Moose>
165
166 =item L<Moose::Role>
167
168 =item L<Moose::Utils::TypeConstraints>
169
170 =item L<Sub::Exporter>
171
172 =item L<namespace::autoclean>
173
174 =item L<namespace::clean>
175
176 =back
177
178 =cut