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