lib/Moose/Cookbook/Snack/Keywords.pod

   1 package Moose::Cookbook::Snack::Keywords;
   2
   3 # ABSTRACT: Restricted "keywords" in Moose
   4
   5 __END__
   6
   7 =pod
   8
   9 =head1 DESCRIPTION
  10
  11 Moose exports a number of sugar functions in order to emulate Perl
  12 built-in keywords. These can cause clashes with other user-defined
  13 functions. This document provides a list of those keywords for easy
  14 reference.
  15
  16 =head2 The 'meta' keyword
  17
  18 C<S<use Moose>> adds a method called C<meta> to your class. If this
  19 conflicts with a method or function you are using, you can rename it,
  20 or prevent it from being installed entirely. To do this, pass the
  21 C<-meta_name> option when you C<S<use Moose>>. For instance:
  22
  23   # install it under a different name
  24   use Moose -meta_name => 'moose_meta';
  25
  26   # don't install it at all
  27   use Moose -meta_name => undef;
  28
  29 =head2 Moose Keywords
  30
  31 If you are using L<Moose> or L<Moose::Role> it is best to avoid these
  32 keywords:
  33
  34 =over 4
  35
  36 =item extends
  37
  38 =item with
  39
  40 =item has
  41
  42 =item before
  43
  44 =item after
  45
  46 =item around
  47
  48 =item super
  49
  50 =item override
  51
  52 =item inner
  53
  54 =item augment
  55
  56 =item confess
  57
  58 =item blessed
  59
  60 =back
  61
  62 =head2 Moose::Util::TypeConstraints Keywords
  63
  64 If you are using L<Moose::Util::TypeConstraints> it is best to avoid
  65 these keywords:
  66
  67 =over 4
  68
  69 =item type
  70
  71 =item subtype
  72
  73 =item class_type
  74
  75 =item role_type
  76
  77 =item maybe_type
  78
  79 =item duck_type
  80
  81 =item as
  82
  83 =item where
  84
  85 =item message
  86
  87 =item optimize_as
  88
  89 =item inline_as
  90
  91 =item coerce
  92
  93 =item from
  94
  95 =item via
  96
  97 =item enum
  98
  99 =item find_type_constraint
 100
 101 =item register_type_constraint
 102
 103 =back
 104
 105 =head2 Avoiding collisions
 106
 107 =head3 Turning off Moose
 108
 109 To remove the sugar functions L<Moose> exports, just add C<S<no Moose>>
 110 at the bottom of your code:
 111
 112   package Thing;
 113   use Moose;
 114
 115   # code here
 116
 117   no Moose;
 118
 119 This will unexport the sugar functions that L<Moose> originally
 120 exported. The same will also work for L<Moose::Role> and
 121 L<Moose::Util::TypeConstraints>.
 122
 123 =head3 Sub::Exporter features
 124
 125 L<Moose>, L<Moose::Role> and L<Moose::Util::TypeConstraints> all use
 126 L<Sub::Exporter> to handle all their exporting needs. This means that
 127 all the features that L<Sub::Exporter> provides are also available to
 128 them.
 129
 130 For instance, with L<Sub::Exporter> you can rename keywords, like so:
 131
 132   package LOL::Cat;
 133   use Moose 'has' => { -as => 'i_can_haz' };
 134
 135   i_can_haz 'cheeseburger' => (
 136       is      => 'rw',
 137       trigger => sub { print "NOM NOM" }
 138   );
 139
 140   LOL::Cat->new->cheeseburger('KTHNXBYE');
 141
 142 See the L<Sub::Exporter> docs for more information.
 143
 144 =head3 namespace::autoclean and namespace::clean
 145
 146 You can also use L<namespace::autoclean> to clean up your namespace.
 147 This will remove all imported functions from your namespace. Note
 148 that if you are importing functions that are intended to be used as
 149 methods (this includes L<overload>, due to internal implementation
 150 details), it will remove these as well.
 151
 152 Another option is to use L<namespace::clean> directly, but
 153 you must be careful not to remove C<meta> when doing so:
 154
 155   package Foo;
 156   use Moose;
 157   use namespace::clean -except => 'meta';
 158   # ...
 159
 160 =head1 SEE ALSO
 161
 162 =over 4
 163
 164 =item L<Moose>
 165
 166 =item L<Moose::Role>
 167
 168 =item L<Moose::Utils::TypeConstraints>
 169
 170 =item L<Sub::Exporter>
 171
 172 =item L<namespace::autoclean>
 173
 174 =item L<namespace::clean>
 175
 176 =back
 177
 178 =cut