Tweak the cookbook intro a little

[gitmo/Moose.git] / lib / Moose / Cookbook / Snack / Keywords.pod

=pod

=head1 NAME

Moose::Cookbook::Snack::Keywords - Restricted keywords in Moose 

=head1 DESCRIPTION

There are several keywords exported by L<Moose> that can cause clashes 
against other user-defined barewords. The following document provides 
a list of those keywords in a single place 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<can not> override. Do not attempt to override
I<meta>, it will break the Moose internals.

=head2 Moose Keywords 

If you are using L<Moose> or L<Moose::Role> its best to avoid these 
keywords:

=over 4

=item extends 

=item with 

=item has 

=item before 

=item after 

=item around 

=item super 

=item override 

=item inner 

=item augment 

=item confess 

=item blessed 

=back

=head2 Moose::Util::TypeConstraints Keywords 

If you are using L<Moose::Util::TypeConstraints> its best to avoid 
these keywords 

=over 4

=item type 

=item subtype 

=item class_type 

=item role_type 

=item as 

=item where 

=item message 

=item optimize_as

=item coerce 

=item from 

=item via

=item enum

=item find_type_constraint

=item register_type_constraint

=back

=head2 Avoiding collisions

=head3 Turning off Moose

To remove the keywords L<Moose> exports just add C<no Moose> at the bottom of 
your code, like so:

  package Thing;
  use Moose;

  # code here

  no Moose;

This will unexport the keywords that L<Moose> originally exported. The same 
will also work for L<Moose::Role> and L<Moose::Util::TypeConstraints>. It is 
general L<Moose> policy that this feature is used.

=head3  Sub::Exporter

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. 

For instance, with L<Sub::Exporter> you can rename keywords, like so:

  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 also use L<namespace::clean> to clean up your namespace, but you must 
be careful not to remove C<meta> with this. Here is an example of that usage:

  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>>

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 library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut