Tweak the cookbook intro a little
[gitmo/Moose.git] / lib / Moose / Cookbook / Snack / Keywords.pod
CommitLineData
4499a7ab 1=pod
2
3=head1 NAME
4
5Moose::Cookbook::Snack::Keywords - Restricted keywords in Moose
6
4499a7ab 7=head1 DESCRIPTION
8
47b19570 9There are several keywords exported by L<Moose> that can cause clashes
10against other user-defined barewords. The following document provides
11a list of those keywords in a single place for easy reference.
4499a7ab 12
13=head2 The 'meta' keyword
14
15While most of the reserved keywords collisions can be avoided, however
47b19570 16I<meta> is the only one you B<can not> override. Do not attempt to override
17I<meta>, it will break the Moose internals.
4499a7ab 18
19=head2 Moose Keywords
20
47b19570 21If you are using L<Moose> or L<Moose::Role> its best to avoid these
22keywords:
4499a7ab 23
24=over 4
25
26=item extends
27
28=item with
29
30=item has
31
32=item before
33
34=item after
35
36=item around
37
38=item super
39
40=item override
41
42=item inner
43
44=item augment
45
4499a7ab 46=item confess
47
48=item blessed
49
50=back
51
52=head2 Moose::Util::TypeConstraints Keywords
53
47b19570 54If you are using L<Moose::Util::TypeConstraints> its best to avoid
4499a7ab 55these keywords
56
57=over 4
58
59=item type
60
61=item subtype
62
63=item class_type
64
65=item role_type
66
67=item as
68
69=item where
70
71=item message
72
73=item optimize_as
74
75=item coerce
76
77=item from
78
79=item via
80
81=item enum
82
83=item find_type_constraint
84
85=item register_type_constraint
86
87=back
88
89=head2 Avoiding collisions
47b19570 90
4499a7ab 91=head3 Turning off Moose
92
47b19570 93To remove the keywords L<Moose> exports just add C<no Moose> at the bottom of
94your code, like so:
95
96 package Thing;
97 use Moose;
4499a7ab 98
47b19570 99 # code here
4499a7ab 100
47b19570 101 no Moose;
4499a7ab 102
6549b0d1 103This will unexport the keywords that L<Moose> originally exported. The same
47b19570 104will also work for L<Moose::Role> and L<Moose::Util::TypeConstraints>. It is
105general L<Moose> policy that this feature is used.
4499a7ab 106
107=head3 Sub::Exporter
108
47b19570 109L<Moose>, L<Moose::Role> and L<Moose::Util::TypeConstraints> all use
110L<Sub::Exporter> to handle all their exporting needs. This means that all the
111features that L<Sub::Exporter> provides are also available to them.
4499a7ab 112
47b19570 113For instance, with L<Sub::Exporter> you can rename keywords, like so:
4499a7ab 114
47b19570 115 package LOL::Cat;
116 use Moose 'has' => { -as => 'i_can_haz' };
117
118 i_can_haz 'cheeseburger' => (
119 is => 'rw',
120 trigger => sub { print "NOM NOM" }
121 );
122
123 LOL::Cat->new->cheeseburger('KTHNXBYE');
4499a7ab 124
47b19570 125See the L<Sub::Exporter> docs for more information.
4499a7ab 126
127=head3 namespace::clean
128
47b19570 129You can also use L<namespace::clean> to clean up your namespace, but you must
130be careful not to remove C<meta> with this. Here is an example of that usage:
131
132 package Foo;
133 use Moose;
134 use namespace::clean -except => 'meta';
135 # ...
136
137=head1 SEE ALSO
138
139=over 4
140
141=item L<Moose>
4499a7ab 142
47b19570 143=item L<Moose::Role>
144
145=item L<Moose::Utils::TypeConstraints>
146
147=item L<Sub::Exporter>
148
149=item L<namespace::clean>
150
151=back
152
153=head1 AUTHOR
4499a7ab 154
155John Goulah C<E<lt>jgoulah@cpan.org<gt>>
156
47b19570 157Stevan Little E<lt>stevan@iinteractive.comE<gt>
158
159=head1 COPYRIGHT AND LICENSE
160
2840a3b2 161Copyright 2006-2009 by Infinity Interactive, Inc.
47b19570 162
163L<http://www.iinteractive.com>
4499a7ab 164
47b19570 165This library is free software; you can redistribute it and/or modify
166it under the same terms as Perl itself.
4499a7ab 167
168=cut