lib/Moose/Meta/Attribute/Native.pm

   1 package Moose::Meta::Attribute::Native;
   2
   3 my @trait_names = qw(Bool Counter Number String Array Hash Code);
   4
   5 for my $trait_name (@trait_names) {
   6     my $trait_class = "Moose::Meta::Attribute::Native::Trait::$trait_name";
   7     my $meta = Class::MOP::Class->initialize(
   8         "Moose::Meta::Attribute::Custom::Trait::$trait_name"
   9     );
  10     if ($meta->find_method_by_name('register_implementation')) {
  11         my $class = $meta->name->register_implementation;
  12         Moose->throw_error(
  13             "An implementation for $trait_name already exists " .
  14             "(found '$class' when trying to register '$trait_class')"
  15         );
  16     }
  17     $meta->add_method(register_implementation => sub {
  18         # resolve_metatrait_alias will load classes anyway, but throws away
  19         # their error message; we WANT to die if there's a problem
  20         Class::MOP::load_class($trait_class);
  21         return $trait_class;
  22     });
  23 }
  24
  25 1;
  26
  27 # ABSTRACT: Delegate to native Perl types
  28
  29 __END__
  30
  31 =pod
  32
  33 =head1 SYNOPSIS
  34
  35   package MyClass;
  36   use Moose;
  37
  38   has 'mapping' => (
  39       traits  => ['Hash'],
  40       is      => 'rw',
  41       isa     => 'HashRef[Str]',
  42       default => sub { {} },
  43       handles => {
  44           exists_in_mapping => 'exists',
  45           ids_in_mapping    => 'keys',
  46           get_mapping       => 'get',
  47           set_mapping       => 'set',
  48           set_quantity      => [ set => 'quantity' ],
  49       },
  50   );
  51
  52   my $obj = MyClass->new;
  53   $obj->set_quantity(10);      # quantity => 10
  54   $obj->set_mapping('foo', 4); # foo => 4
  55   $obj->set_mapping('bar', 5); # bar => 5
  56   $obj->set_mapping('baz', 6); # baz => 6
  57
  58   # prints 5
  59   print $obj->get_mapping('bar') if $obj->exists_in_mapping('bar');
  60
  61   # prints 'quantity, foo, bar, baz'
  62   print join ', ', $obj->ids_in_mapping;
  63
  64 =head1 DESCRIPTION
  65
  66 Native delegations allow you to delegate to native Perl data
  67 structures as if they were objects. For example, in the L</SYNOPSIS> you can
  68 see a hash reference being treated as if it has methods named C<exists()>,
  69 C<keys()>, C<get()>, and C<set()>.
  70
  71 The delegation methods (mostly) map to Perl builtins and operators. The return
  72 values of these delegations should be the same as the corresponding Perl
  73 operation. Any deviations will be explicitly documented.
  74
  75 =head1 API
  76
  77 Native delegations are enabled by passing certain options to C<has> when
  78 creating an attribute.
  79
  80 =head2 traits
  81
  82 To enable this feature, pass the appropriate name in the C<traits> array
  83 reference for the attribute. For example, to enable this feature for hash
  84 reference, we include C<'Hash'> in the list of traits.
  85
  86 =head2 isa
  87
  88 You will need to make sure that the attribute has an appropriate type. For
  89 example, to use this with a Hash you must specify that your attribute is some
  90 sort of C<HashRef>.
  91
  92 If you I<don't> specify a type, each trait has a default type it will use.
  93
  94 =head2 handles
  95
  96 This is just like any other delegation, but only a hash reference is allowed
  97 when defining native delegations. The keys are the methods to be created in
  98 the class which contains the attribute. The values are the methods provided by
  99 the associated trait. Currying works the same way as it does with any other
 100 delegation.
 101
 102 See the docs for each native trait for details on what methods are available.
 103
 104 =head2 is
 105
 106 Some traits provide a default C<is> for historical reasons. This behavior is
 107 deprecated, and you are strongly encouraged to provide a value. If you don't
 108 plan to read and write the attribute value directly, you can set C<< is =>
 109 'bare' >> to prevent standard accessor generation.
 110
 111 =head2 default or builder
 112
 113 Some traits provide a default C<default> for historical reasons. This behavior
 114 is deprecated, and you are strongly encouraged to provide a default value or
 115 make the attribute required.
 116
 117 =head1 TRAITS FOR NATIVE DELEGATIONS
 118
 119 =over
 120
 121 =item L<Array|Moose::Meta::Attribute::Native::Trait::Array>
 122
 123     has 'queue' => (
 124         traits  => ['Array'],
 125         is      => 'ro',
 126         isa     => 'ArrayRef[Str]',
 127         default => sub { [] },
 128         handles => {
 129             add_item  => 'push',
 130             next_item => 'shift',
 131             # ...
 132         }
 133     );
 134
 135 =item L<Bool|Moose::Meta::Attribute::Native::Trait::Bool>
 136
 137     has 'is_lit' => (
 138         traits  => ['Bool'],
 139         is      => 'ro',
 140         isa     => 'Bool',
 141         default => 0,
 142         handles => {
 143             illuminate  => 'set',
 144             darken      => 'unset',
 145             flip_switch => 'toggle',
 146             is_dark     => 'not',
 147             # ...
 148         }
 149     );
 150
 151 =item L<Code|Moose::Meta::Attribute::Native::Trait::Code>
 152
 153     has 'callback' => (
 154         traits  => ['Code'],
 155         is      => 'ro',
 156         isa     => 'CodeRef',
 157         default => sub {
 158             sub {'called'}
 159         },
 160         handles => {
 161             call => 'execute',
 162             # ...
 163         }
 164     );
 165
 166 =item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
 167
 168     has 'counter' => (
 169         traits  => ['Counter'],
 170         is      => 'ro',
 171         isa     => 'Num',
 172         default => 0,
 173         handles => {
 174             inc_counter   => 'inc',
 175             dec_counter   => 'dec',
 176             reset_counter => 'reset',
 177             # ...
 178         }
 179     );
 180
 181 =item L<Hash|Moose::Meta::Attribute::Native::Trait::Hash>
 182
 183     has 'options' => (
 184         traits  => ['Hash'],
 185         is      => 'ro',
 186         isa     => 'HashRef[Str]',
 187         default => sub { {} },
 188         handles => {
 189             set_option => 'set',
 190             get_option => 'get',
 191             has_option => 'exists',
 192             # ...
 193         }
 194     );
 195
 196 =item L<Number|Moose::Meta::Attribute::Native::Trait::Number>
 197
 198     has 'integer' => (
 199         traits  => ['Number'],
 200         is      => 'ro',
 201         isa     => 'Int',
 202         default => 5,
 203         handles => {
 204             set => 'set',
 205             add => 'add',
 206             sub => 'sub',
 207             mul => 'mul',
 208             div => 'div',
 209             mod => 'mod',
 210             abs => 'abs',
 211             # ...
 212         }
 213     );
 214
 215 =item L<String|Moose::Meta::Attribute::Native::Trait::String>
 216
 217     has 'text' => (
 218         traits  => ['String'],
 219         is      => 'ro',
 220         isa     => 'Str',
 221         default => q{},
 222         handles => {
 223             add_text     => 'append',
 224             replace_text => 'replace',
 225             # ...
 226         }
 227     );
 228
 229 =back
 230
 231 =head1 COMPATIBILITY WITH MooseX::AttributeHelpers
 232
 233 This feature used to be a separated CPAN distribution called
 234 L<MooseX::AttributeHelpers>.
 235
 236 When the feature was incorporated into the Moose core, some of the API details
 237 were changed. The underlying capabilities are the same, but some details of
 238 the API were changed.
 239
 240 =head1 BUGS
 241
 242 See L<Moose/BUGS> for details on reporting bugs.
 243
 244 =cut