lib/Moose/Meta/Attribute/Native.pm

   1 package Moose::Meta::Attribute::Native;
   2
   3 our $VERSION   = '0.93_03';
   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 METHOD PROVIDERS
  99
 100 =over
 101
 102 =item L<Number|Moose::Meta::Attribute::Native::Trait::Number>
 103
 104 Common numerical operations.
 105
 106     has 'integer' => (
 107         traits    => ['Number'],
 108         is        => 'ro',
 109         isa       => 'Int',
 110         default   => 5,
 111         handles   => {
 112             set => 'set',
 113             add => 'add',
 114             sub => 'sub',
 115             mul => 'mul',
 116             div => 'div',
 117             mod => 'mod',
 118             abs => 'abs',
 119         }
 120     );
 121
 122 =item L<String|Moose::Meta::Attribute::Native::Trait::String>
 123
 124 Common methods for string operations.
 125
 126     has 'text' => (
 127         traits    => ['String'],
 128         is        => 'rw',
 129         isa       => 'Str',
 130         default   => q{},
 131         handles   => {
 132             add_text     => 'append',
 133             replace_text => 'replace',
 134         }
 135     );
 136
 137 =item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
 138
 139 Methods for incrementing and decrementing a counter attribute.
 140
 141     has 'counter' => (
 142         traits    => ['Counter'],
 143         is        => 'ro',
 144         isa       => 'Num',
 145         default   => 0,
 146         handles   => {
 147             inc_counter   => 'inc',
 148             dec_counter   => 'dec',
 149             reset_counter => 'reset',
 150         }
 151     );
 152
 153 =item L<Bool|Moose::Meta::Attribute::Native::Trait::Bool>
 154
 155 Common methods for boolean values.
 156
 157     has 'is_lit' => (
 158         traits    => ['Bool'],
 159         is        => 'rw',
 160         isa       => 'Bool',
 161         default   => 0,
 162         handles   => {
 163             illuminate  => 'set',
 164             darken      => 'unset',
 165             flip_switch => 'toggle',
 166             is_dark     => 'not',
 167         }
 168     );
 169
 170 =item L<Hash|Moose::Meta::Attribute::Native::Trait::Hash>
 171
 172 Common methods for hash references.
 173
 174     has 'options' => (
 175         traits    => ['Hash'],
 176         is        => 'ro',
 177         isa       => 'HashRef[Str]',
 178         default   => sub { {} },
 179         handles   => {
 180             set_option => 'set',
 181             get_option => 'get',
 182             has_option => 'exists',
 183         }
 184     );
 185
 186 =item L<Array|Moose::Meta::Attribute::Native::Trait::Array>
 187
 188 Common methods for array references.
 189
 190     has 'queue' => (
 191        traits     => ['Array'],
 192        is         => 'ro',
 193        isa        => 'ArrayRef[Str]',
 194        default    => sub { [] },
 195        handles    => {
 196            add_item  => 'push',
 197            next_item => 'shift',
 198        }
 199     );
 200
 201 =item L<Code|Moose::Meta::Attribute::Native::Trait::Code>
 202
 203 Common methods for code references.
 204
 205     has 'callback' => (
 206        traits     => ['Code'],
 207        is         => 'ro',
 208        isa        => 'CodeRef',
 209        default    => sub { sub { 'called' } },
 210        handles    => {
 211            call => 'execute',
 212        }
 213     );
 214
 215 =back
 216
 217 =head1 BUGS
 218
 219 See L<Moose/BUGS> for details on reporting bugs.
 220
 221 =head1 AUTHOR
 222
 223 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 224
 225 B<with contributions from:>
 226
 227 Robert (rlb3) Boone
 228
 229 Paul (frodwith) Driver
 230
 231 Shawn (Sartak) Moore
 232
 233 Chris (perigrin) Prather
 234
 235 Robert (phaylon) Sedlacek
 236
 237 Tom (dec) Lanyon
 238
 239 Yuval Kogman
 240
 241 Jason May
 242
 243 Cory (gphat) Watson
 244
 245 Florian (rafl) Ragwitz
 246
 247 Evan Carroll
 248
 249 Jesse (doy) Luehrs
 250
 251 Jay Hannah
 252
 253 Robert Buels
 254
 255 =head1 COPYRIGHT AND LICENSE
 256
 257 Copyright 2007-2009 by Infinity Interactive, Inc.
 258
 259 L<http://www.iinteractive.com>
 260
 261 This library is free software; you can redistribute it and/or modify
 262 it under the same terms as Perl itself.
 263
 264 =cut