lib/Moose/Meta/Attribute/Native.pm

   1 package Moose::Meta::Attribute::Native;
   2
   3 our $VERSION   = '0.95';
   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
 123 =item L<String|Moose::Meta::Attribute::Native::Trait::String>
 124
 125 Common methods for string operations.
 126
 127     has 'text' => (
 128         traits    => ['String'],
 129         is        => 'rw',
 130         isa       => 'Str',
 131         default   => q{},
 132         handles   => {
 133             add_text     => 'append',
 134             replace_text => 'replace',
 135             # ...
 136         }
 137     );
 138
 139 =item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
 140
 141 Methods for incrementing and decrementing a counter attribute.
 142
 143     has 'counter' => (
 144         traits    => ['Counter'],
 145         is        => 'ro',
 146         isa       => 'Num',
 147         default   => 0,
 148         handles   => {
 149             inc_counter   => 'inc',
 150             dec_counter   => 'dec',
 151             reset_counter => 'reset',
 152             # ...
 153         }
 154     );
 155
 156 =item L<Bool|Moose::Meta::Attribute::Native::Trait::Bool>
 157
 158 Common methods for boolean values.
 159
 160     has 'is_lit' => (
 161         traits    => ['Bool'],
 162         is        => 'rw',
 163         isa       => 'Bool',
 164         default   => 0,
 165         handles   => {
 166             illuminate  => 'set',
 167             darken      => 'unset',
 168             flip_switch => 'toggle',
 169             is_dark     => 'not',
 170             # ...
 171         }
 172     );
 173
 174 =item L<Hash|Moose::Meta::Attribute::Native::Trait::Hash>
 175
 176 Common methods for hash references.
 177
 178     has 'options' => (
 179         traits    => ['Hash'],
 180         is        => 'ro',
 181         isa       => 'HashRef[Str]',
 182         default   => sub { {} },
 183         handles   => {
 184             set_option => 'set',
 185             get_option => 'get',
 186             has_option => 'exists',
 187             # ...
 188         }
 189     );
 190
 191 =item L<Array|Moose::Meta::Attribute::Native::Trait::Array>
 192
 193 Common methods for array references.
 194
 195     has 'queue' => (
 196         traits    => ['Array'],
 197         is        => 'ro',
 198         isa       => 'ArrayRef[Str]',
 199         default   => sub { [] },
 200         handles   => {
 201             add_item  => 'push',
 202             next_item => 'shift',
 203             # ...
 204         }
 205     );
 206
 207 =item L<Code|Moose::Meta::Attribute::Native::Trait::Code>
 208
 209 Common methods for code references.
 210
 211     has 'callback' => (
 212         traits    => ['Code'],
 213         is        => 'ro',
 214         isa       => 'CodeRef',
 215         default   => sub { sub { 'called' } },
 216         handles   => {
 217             call => 'execute',
 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