=head1 NAME
-Moose::Cookbook::Snack::Keywords - Restricted keywords in Moose
-
-=cut
+Moose::Cookbook::Snack::Keywords - Restricted "keywords" in Moose
=head1 DESCRIPTION
-There are several keywords exported in L<Moose> that cause clashes against
-any barewords such as attribute names, sub names, and globs.
-
+Moose exports a number of sugar functions in order to emulate Perl
+built-in keywords. These can cause clashes with other user-defined
+functions. This document provides a list of those keywords for easy
+reference.
=head2 The 'meta' keyword
-While most of the reserved keywords collisions can be avoided, however
-I<meta> is the only one you B<cant> override. Do not attempt to override
-I<meta>.
+While most collisions can be avoided, you cannot avoid importing a
+C<meta> method when you C<S<use Moose>>. If you try to override or
+change what C<meta> does, you could end up breaking Moose internals.
-=head2 Moose Keywords
+=head2 Moose Keywords
-If you are using Moose its best to avoid these keywords
+If you are using L<Moose> or L<Moose::Role> its best to avoid these
+keywords:
=over 4
-=item extends
+=item extends
-=item with
+=item with
-=item has
+=item has
-=item before
+=item before
-=item after
+=item after
-=item around
+=item around
-=item super
+=item super
-=item override
+=item override
-=item inner
+=item inner
-=item augment
+=item augment
-=item make_immutable
+=item confess
-=item confess
-
-=item blessed
+=item blessed
=back
-=head2 Moose::Util::TypeConstraints Keywords
+=head2 Moose::Util::TypeConstraints Keywords
-If you are using Moose::Util::TypeConstraints its best to avoid
-these keywords
+If you are using L<Moose::Util::TypeConstraints> its best to avoid
+these keywords
=over 4
-=item type
+=item type
+
+=item subtype
-=item subtype
+=item class_type
-=item class_type
+=item role_type
-=item role_type
+=item maybe_type
-=item as
+=item as
-=item where
+=item where
-=item message
+=item message
=item optimize_as
-=item coerce
+=item coerce
-=item from
+=item from
=item via
=back
=head2 Avoiding collisions
-
+
=head3 Turning off Moose
-To remove the keywords Moose exports using no Moose at the bottom of your code
+To remove the sugar functions L<Moose> exports just add C<S<no Moose>>
+at the bottom of your code:
- package Thing;
- use Moose;
+ package Thing;
+ use Moose;
- # code here
+ # code here
- no Moose;
+ no Moose;
-=head3 Sub::Exporter
+This will unexport the sugar functions that L<Moose> originally
+exported. The same will also work for L<Moose::Role> and
+L<Moose::Util::TypeConstraints>.
-The L<Sub::Exporter> module can rename keywords
+=head3 Sub::Exporter features
- package LOL::Cat;
- use Moose 'has' => { -as => 'i_can_haz' };
+L<Moose>, L<Moose::Role> and L<Moose::Util::TypeConstraints> all use
+L<Sub::Exporter> to handle all their exporting needs. This means that
+all the features that L<Sub::Exporter> provides are also available to
+them.
- i_can_haz 'cheeseburger' => (
- is => 'rw',
- trigger => sub { print "NOM NOM" }
- );
+For instance, with L<Sub::Exporter> you can rename keywords, like so:
- LOL::Cat->new->cheeseburger('KTHNXBYE');;
+ package LOL::Cat;
+ use Moose 'has' => { -as => 'i_can_haz' };
+
+ i_can_haz 'cheeseburger' => (
+ is => 'rw',
+ trigger => sub { print "NOM NOM" }
+ );
+
+ LOL::Cat->new->cheeseburger('KTHNXBYE');
+
+See the L<Sub::Exporter> docs for more information.
=head3 namespace::clean
-You can use L<namespace::clean> to clean up the namespace
+You can also use L<namespace::clean> to clean up your namespace, but
+you must be careful not to remove C<meta> when doing so:
-=head1 AUTHOR AND COPYRIGHT
+ package Foo;
+ use Moose;
+ use namespace::clean -except => 'meta';
+ # ...
+
+=head1 SEE ALSO
+
+=over 4
+
+=item L<Moose>
+
+=item L<Moose::Role>
+
+=item L<Moose::Utils::TypeConstraints>
+
+=item L<Sub::Exporter>
+
+=item L<namespace::clean>
+
+=back
+
+=head1 AUTHOR
John Goulah C<E<lt>jgoulah@cpan.org<gt>>
-=head1 LICENSE
+Stevan Little E<lt>stevan@iinteractive.comE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2006-2009 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
-This program is free software; you can redistribute it and/or modify
-it under the same terms as perl itself.
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
=cut
projects / gitmo/Moose.git / blobdiff