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 While most collisions can be avoided, you cannot avoid importing a
  19 C<meta> method when you C<S<use Moose>>. If you try to override or
  20 change what C<meta> does, you could end up breaking Moose internals.
  21
  22 =head2 Moose Keywords
  23
  24 If you are using L<Moose> or L<Moose::Role> its best to avoid these
  25 keywords:
  26
  27 =over 4
  28
  29 =item extends
  30
  31 =item with
  32
  33 =item has
  34
  35 =item before
  36
  37 =item after
  38
  39 =item around
  40
  41 =item super
  42
  43 =item override
  44
  45 =item inner
  46
  47 =item augment
  48
  49 =item confess
  50
  51 =item blessed
  52
  53 =back
  54
  55 =head2 Moose::Util::TypeConstraints Keywords
  56
  57 If you are using L<Moose::Util::TypeConstraints> its best to avoid
  58 these keywords
  59
  60 =over 4
  61
  62 =item type
  63
  64 =item subtype
  65
  66 =item class_type
  67
  68 =item role_type
  69
  70 =item maybe_type
  71
  72 =item as
  73
  74 =item where
  75
  76 =item message
  77
  78 =item optimize_as
  79
  80 =item coerce
  81
  82 =item from
  83
  84 =item via
  85
  86 =item enum
  87
  88 =item find_type_constraint
  89
  90 =item register_type_constraint
  91
  92 =back
  93
  94 =head2 Avoiding collisions
  95
  96 =head3 Turning off Moose
  97
  98 To remove the sugar functions L<Moose> exports just add C<S<no Moose>>
  99 at the bottom of your code:
 100
 101   package Thing;
 102   use Moose;
 103
 104   # code here
 105
 106   no Moose;
 107
 108 This will unexport the sugar functions that L<Moose> originally
 109 exported. The same will also work for L<Moose::Role> and
 110 L<Moose::Util::TypeConstraints>.
 111
 112 =head3 Sub::Exporter features
 113
 114 L<Moose>, L<Moose::Role> and L<Moose::Util::TypeConstraints> all use
 115 L<Sub::Exporter> to handle all their exporting needs. This means that
 116 all the features that L<Sub::Exporter> provides are also available to
 117 them.
 118
 119 For instance, with L<Sub::Exporter> you can rename keywords, like so:
 120
 121   package LOL::Cat;
 122   use Moose 'has' => { -as => 'i_can_haz' };
 123
 124   i_can_haz 'cheeseburger' => (
 125       is      => 'rw',
 126       trigger => sub { print "NOM NOM" }
 127   );
 128
 129   LOL::Cat->new->cheeseburger('KTHNXBYE');
 130
 131 See the L<Sub::Exporter> docs for more information.
 132
 133 =head3 namespace::clean
 134
 135 You can also use L<namespace::clean> to clean up your namespace, but
 136 you must be careful not to remove C<meta> when doing so:
 137
 138   package Foo;
 139   use Moose;
 140   use namespace::clean -except => 'meta';
 141   # ...
 142
 143 =head1 SEE ALSO
 144
 145 =over 4
 146
 147 =item L<Moose>
 148
 149 =item L<Moose::Role>
 150
 151 =item L<Moose::Utils::TypeConstraints>
 152
 153 =item L<Sub::Exporter>
 154
 155 =item L<namespace::clean>
 156
 157 =back
 158
 159 =cut