lib/Moose/Meta/Attribute/Native.pm

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