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