Dzil-ize all the .pod files so they can be pod-woven

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

package Moose::Cookbook::Snack::Keywords;

# ABSTRACT: Restricted "keywords" in Moose

__END__

=pod

=head1 DESCRIPTION

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

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 maybe_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 sugar functions L<Moose> exports just add C<S<no Moose>>
at the bottom of your code:

  package Thing;
  use Moose;

  # code here

  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 features

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> when doing so:

  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

=cut