lib/Moose/Meta/Attribute/Native.pm

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