lib/Moose/Cookbook/Snack/Keywords.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Moose::Cookbook::Snack::Keywords - Restricted "keywords" in Moose
   6
   7 =head1 DESCRIPTION
   8
   9 Moose exports a number of sugar functions in order to emulate Perl
  10 built-in keywords. These can cause clashes with other user-defined
  11 functions. This document provides a list of those keywords for easy
  12 reference.
  13
  14 =head2 The 'meta' keyword
  15
  16 While most collisions can be avoided, you cannot avoid importing a
  17 C<meta> method when you C<S<use Moose>>. If you try to override or
  18 change what C<meta> does, you could end up breaking Moose internals.
  19
  20 =head2 Moose Keywords
  21
  22 If you are using L<Moose> or L<Moose::Role> its best to avoid these
  23 keywords:
  24
  25 =over 4
  26
  27 =item extends
  28
  29 =item with
  30
  31 =item has
  32
  33 =item before
  34
  35 =item after
  36
  37 =item around
  38
  39 =item super
  40
  41 =item override
  42
  43 =item inner
  44
  45 =item augment
  46
  47 =item confess
  48
  49 =item blessed
  50
  51 =back
  52
  53 =head2 Moose::Util::TypeConstraints Keywords
  54
  55 If you are using L<Moose::Util::TypeConstraints> its best to avoid
  56 these keywords
  57
  58 =over 4
  59
  60 =item type
  61
  62 =item subtype
  63
  64 =item class_type
  65
  66 =item role_type
  67
  68 =item maybe_type
  69
  70 =item as
  71
  72 =item where
  73
  74 =item message
  75
  76 =item optimize_as
  77
  78 =item coerce
  79
  80 =item from
  81
  82 =item via
  83
  84 =item enum
  85
  86 =item find_type_constraint
  87
  88 =item register_type_constraint
  89
  90 =back
  91
  92 =head2 Avoiding collisions
  93
  94 =head3 Turning off Moose
  95
  96 To remove the sugar functions L<Moose> exports just add C<S<no Moose>>
  97 at the bottom of your code:
  98
  99   package Thing;
 100   use Moose;
 101
 102   # code here
 103
 104   no Moose;
 105
 106 This will unexport the sugar functions that L<Moose> originally
 107 exported. The same will also work for L<Moose::Role> and
 108 L<Moose::Util::TypeConstraints>.
 109
 110 =head3 Sub::Exporter features
 111
 112 L<Moose>, L<Moose::Role> and L<Moose::Util::TypeConstraints> all use
 113 L<Sub::Exporter> to handle all their exporting needs. This means that
 114 all the features that L<Sub::Exporter> provides are also available to
 115 them.
 116
 117 For instance, with L<Sub::Exporter> you can rename keywords, like so:
 118
 119   package LOL::Cat;
 120   use Moose 'has' => { -as => 'i_can_haz' };
 121
 122   i_can_haz 'cheeseburger' => (
 123       is      => 'rw',
 124       trigger => sub { print "NOM NOM" }
 125   );
 126
 127   LOL::Cat->new->cheeseburger('KTHNXBYE');
 128
 129 See the L<Sub::Exporter> docs for more information.
 130
 131 =head3 namespace::clean
 132
 133 You can also use L<namespace::clean> to clean up your namespace, but
 134 you must be careful not to remove C<meta> when doing so:
 135
 136   package Foo;
 137   use Moose;
 138   use namespace::clean -except => 'meta';
 139   # ...
 140
 141 =head1 SEE ALSO
 142
 143 =over 4
 144
 145 =item L<Moose>
 146
 147 =item L<Moose::Role>
 148
 149 =item L<Moose::Utils::TypeConstraints>
 150
 151 =item L<Sub::Exporter>
 152
 153 =item L<namespace::clean>
 154
 155 =back
 156
 157 =head1 AUTHOR
 158
 159 John Goulah C<E<lt>jgoulah@cpan.org<gt>>
 160
 161 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 162
 163 =head1 COPYRIGHT AND LICENSE
 164
 165 Copyright 2006-2009 by Infinity Interactive, Inc.
 166
 167 L<http://www.iinteractive.com>
 168
 169 This library is free software; you can redistribute it and/or modify
 170 it under the same terms as Perl itself.
 171
 172 =cut