-=pod
+package Moose::Cookbook::Snack::Keywords;
-=head1 NAME
+# ABSTRACT: Restricted "keywords" in Moose
-Moose::Cookbook::Snack::Keywords - Restricted keywords in Moose
+__END__
-=cut
+=pod
=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>.
+C<S<use Moose>> adds a method called C<meta> to your class. If this
+conflicts with a method or function you are using, you can rename it,
+or prevent it from being installed entirely. To do this, pass the
+C<-meta_name> option when you C<S<use Moose>>. For instance:
-=head2 Moose Keywords
+ # install it under a different name
+ use Moose -meta_name => 'moose_meta';
-If you are using Moose its best to avoid these keywords
+ # don't install it at all
+ use Moose -meta_name => undef;
-=over 4
+=head2 Moose Keywords
+
+If you are using L<Moose> or L<Moose::Role> its best to avoid these
+keywords:
-=item extends
+=over 4
-=item with
+=item extends
-=item has
+=item with
-=item before
+=item has
-=item after
+=item before
-=item around
+=item after
-=item super
+=item around
-=item override
+=item super
-=item inner
+=item override
-=item augment
+=item inner
-=item make_immutable
+=item augment
-=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 class_type
-=item subtype
+=item role_type
-=item class_type
+=item maybe_type
-=item role_type
+=item duck_type
-=item as
+=item as
-=item where
+=item where
-=item message
+=item message
=item optimize_as
-=item coerce
+=item inline_as
-=item from
+=item coerce
+
+=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;
+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>.
-=head3 Sub::Exporter
+=head3 Sub::Exporter features
-The L<Sub::Exporter> module can rename keywords
+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.
- package LOL::Cat;
- use Moose 'has' => { -as => 'i_can_haz' };
+For instance, with L<Sub::Exporter> you can rename keywords, like so:
- i_can_haz 'cheeseburger' => (
- is => 'rw',
- trigger => sub { print "NOM NOM" }
- );
+ package LOL::Cat;
+ use Moose 'has' => { -as => 'i_can_haz' };
- LOL::Cat->new->cheeseburger('KTHNXBYE');;
+ i_can_haz 'cheeseburger' => (
+ is => 'rw',
+ trigger => sub { print "NOM NOM" }
+ );
-=head3 namespace::clean
+ LOL::Cat->new->cheeseburger('KTHNXBYE');
-You can use L<namespace::clean> to clean up the namespace
+See the L<Sub::Exporter> docs for more information.
-=head1 AUTHOR AND COPYRIGHT
+=head3 namespace::autoclean and namespace::clean
-John Goulah C<E<lt>jgoulah@cpan.org<gt>>
+You can also use L<namespace::autoclean> to clean up your namespace.
+This will remove all imported functions from your namespace. Note
+that if you are importing functions that are intended to be used as
+methods (this includes L<overload>, due to internal implementation
+details), it will remove these as well.
-=head1 LICENSE
+Another option is to use L<namespace::clean> directly, but
+you must be careful not to remove C<meta> when doing so:
-This program is free software; you can redistribute it and/or modify
-it under the same terms as perl itself.
+ 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::autoclean>
+
+=item L<namespace::clean>
+
+=back
=cut
projects / gitmo/Moose.git / blobdiff