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 - Extend your attribute interfaces
  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
  59   # ...
  60
  61   my $obj = MyClass->new;
  62   $obj->set_quantity(10);      # quantity => 10
  63   $obj->set_mapping('foo', 4); # foo => 4
  64   $obj->set_mapping('bar', 5); # bar => 5
  65   $obj->set_mapping('baz', 6); # baz => 6
  66
  67
  68   # prints 5
  69   print $obj->get_mapping('bar') if $obj->exists_in_mapping('bar');
  70
  71   # prints 'quantity, foo, bar, baz'
  72   print join ', ', $obj->ids_in_mapping;
  73
  74 =head1 DESCRIPTION
  75
  76 While L<Moose> attributes provide a way to name your accessors, readers,
  77 writers, clearers and predicates, this set of traits provides commonly
  78 used attribute helper methods for more specific types of data.
  79
  80 As seen in the L</SYNOPSIS>, you specify the data structure via the
  81 C<trait> parameter. Available traits are below; see L</METHOD PROVIDERS>.
  82
  83 This module used to exist as the L<MooseX::AttributeHelpers> extension. It was
  84 very commonly used, so we moved it into core Moose. Since this gave us a chance
  85 to change the interface, you will have to change your code or continue using
  86 the L<MooseX::AttributeHelpers> extension. L<MooseX::AttributeHelpers> should
  87 continue to work.
  88
  89 =head1 PARAMETERS
  90
  91 =head2 handles
  92
  93 This is like C<< handles >> in L<Moose/has>, but only HASH references are
  94 allowed.  Keys are method names that you want installed locally, and values are
  95 methods from the method providers (below).  Currying with delegated methods
  96 works normally for C<< handles >>.
  97
  98 =head1 NATIVE TYPES
  99
 100 =over
 101
 102 =item L<Array|Moose::Meta::Attribute::Native::Trait::Array>
 103
 104 Common methods for array references.
 105
 106     has 'queue' => (
 107         traits    => ['Array'],
 108         is        => 'ro',
 109         isa       => 'ArrayRef[Str]',
 110         default   => sub { [] },
 111         handles   => {
 112             add_item  => 'push',
 113             next_item => 'shift',
 114             # ...
 115         }
 116     );
 117
 118 =item L<Bool|Moose::Meta::Attribute::Native::Trait::Bool>
 119
 120 Common methods for boolean values.
 121
 122     has 'is_lit' => (
 123         traits    => ['Bool'],
 124         is        => 'rw',
 125         isa       => 'Bool',
 126         default   => 0,
 127         handles   => {
 128             illuminate  => 'set',
 129             darken      => 'unset',
 130             flip_switch => 'toggle',
 131             is_dark     => 'not',
 132             # ...
 133         }
 134     );
 135
 136 =item L<Code|Moose::Meta::Attribute::Native::Trait::Code>
 137
 138 Common methods for code references.
 139
 140     has 'callback' => (
 141         traits    => ['Code'],
 142         is        => 'ro',
 143         isa       => 'CodeRef',
 144         default   => sub { sub { 'called' } },
 145         handles   => {
 146             call => 'execute',
 147             # ...
 148         }
 149     );
 150
 151 =item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
 152
 153 Methods for incrementing and decrementing a counter attribute.
 154
 155     has 'counter' => (
 156         traits    => ['Counter'],
 157         is        => 'ro',
 158         isa       => 'Num',
 159         default   => 0,
 160         handles   => {
 161             inc_counter   => 'inc',
 162             dec_counter   => 'dec',
 163             reset_counter => 'reset',
 164             # ...
 165         }
 166     );
 167
 168 =item L<Hash|Moose::Meta::Attribute::Native::Trait::Hash>
 169
 170 Common methods for hash references.
 171
 172     has 'options' => (
 173         traits    => ['Hash'],
 174         is        => 'ro',
 175         isa       => 'HashRef[Str]',
 176         default   => sub { {} },
 177         handles   => {
 178             set_option => 'set',
 179             get_option => 'get',
 180             has_option => 'exists',
 181             # ...
 182         }
 183     );
 184
 185 =item L<Number|Moose::Meta::Attribute::Native::Trait::Number>
 186
 187 Common numerical operations.
 188
 189     has 'integer' => (
 190         traits    => ['Number'],
 191         is        => 'ro',
 192         isa       => 'Int',
 193         default   => 5,
 194         handles   => {
 195             set => 'set',
 196             add => 'add',
 197             sub => 'sub',
 198             mul => 'mul',
 199             div => 'div',
 200             mod => 'mod',
 201             abs => 'abs',
 202             # ...
 203         }
 204     );
 205
 206 =item L<String|Moose::Meta::Attribute::Native::Trait::String>
 207
 208 Common methods for string operations.
 209
 210     has 'text' => (
 211         traits    => ['String'],
 212         is        => 'rw',
 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 BUGS
 225
 226 See L<Moose/BUGS> for details on reporting bugs.
 227
 228 =head1 AUTHOR
 229
 230 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 231
 232 B<with contributions from:>
 233
 234 Robert (rlb3) Boone
 235
 236 Paul (frodwith) Driver
 237
 238 Shawn (Sartak) Moore
 239
 240 Chris (perigrin) Prather
 241
 242 Robert (phaylon) Sedlacek
 243
 244 Tom (dec) Lanyon
 245
 246 Yuval Kogman
 247
 248 Jason May
 249
 250 Cory (gphat) Watson
 251
 252 Florian (rafl) Ragwitz
 253
 254 Evan Carroll
 255
 256 Jesse (doy) Luehrs
 257
 258 Jay Hannah
 259
 260 Robert Buels
 261
 262 =head1 COPYRIGHT AND LICENSE
 263
 264 Copyright 2007-2009 by Infinity Interactive, Inc.
 265
 266 L<http://www.iinteractive.com>
 267
 268 This library is free software; you can redistribute it and/or modify
 269 it under the same terms as Perl itself.
 270
 271 =cut