lib/Moose/Meta/Attribute/Native.pm

   1 package Moose::Meta::Attribute::Native;
   2
   3 our $VERSION   = '0.87';
   4 $VERSION = eval $VERSION;
   5 our $AUTHORITY = 'cpan:STEVAN';
   6
   7 my @trait_names = qw(Bool Counter Number String Array Hash);
   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(4, 'foo'); # 4 => 'foo'
  64   $obj->set_mapping(5, 'bar'); # 5 => 'bar'
  65   $obj->set_mapping(6, 'baz'); # 6 => 'baz'
  66
  67
  68   # prints 'bar'
  69   print $obj->get_mapping(5) if $obj->exists_in_mapping(5);
  70
  71   # prints '4, 5, 6'
  72   print join ', ', $obj->ids_in_mapping;
  73
  74 =head1 DESCRIPTION
  75
  76 While L<Moose> attributes provide you with a way to name your accessors,
  77 readers, writers, clearers and predicates, this library provides commonly
  78 used attribute helper methods for more specific types of data.
  79
  80 As seen in the L</SYNOPSIS>, you specify the extension via the
  81 C<trait> parameter. Available meta classes 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.
  87
  88 =head1 PARAMETERS
  89
  90 =head2 handles
  91
  92 This is like C<< handles >> in L<Moose/has>, but only HASH references are
  93 allowed.  Keys are method names that you want installed locally, and values are
  94 methods from the method providers (below).  Currying with delegated methods
  95 works normally for C<< handles >>.
  96
  97 =head1 METHOD PROVIDERS
  98
  99 =over
 100
 101 =item L<Number|Moose::Meta::Attribute::Native::Trait::Number>
 102
 103 Common numerical operations.
 104
 105     has 'integer' => (
 106         metaclass => 'Number',
 107         is        => 'ro',
 108         isa       => 'Int',
 109         default   => 5,
 110         handles  => {
 111             set => 'set',
 112             add => 'add',
 113             sub => 'sub',
 114             mul => 'mul',
 115             div => 'div',
 116             mod => 'mod',
 117             abs => 'abs',
 118         }
 119     );
 120
 121 =item L<String|Moose::Meta::Attribute::Native::Trait::String>
 122
 123 Common methods for string operations.
 124
 125     has 'text' => (
 126         metaclass => 'String',
 127         is        => 'rw',
 128         isa       => 'Str',
 129         default   => q{},
 130         handles  => {
 131             add_text     => 'append',
 132             replace_text => 'replace',
 133         }
 134     );
 135
 136 =item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
 137
 138 Methods for incrementing and decrementing a counter attribute.
 139
 140     has 'counter' => (
 141         traits => ['Counter'],
 142         is        => 'ro',
 143         isa       => 'Num',
 144         default   => 0,
 145         handles   => {
 146             inc_counter   => 'inc',
 147             dec_counter   => 'dec',
 148             reset_counter => 'reset',
 149         }
 150     );
 151
 152 =item L<Bool|Moose::Meta::Attribute::Native::Trait::Bool>
 153
 154 Common methods for boolean values.
 155
 156     has 'is_lit' => (
 157         traits => ['Bool'],
 158         is        => 'rw',
 159         isa       => 'Bool',
 160         default   => 0,
 161         handles   => {
 162             illuminate  => 'set',
 163             darken      => 'unset',
 164             flip_switch => 'toggle',
 165             is_dark     => 'not',
 166         }
 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 =back
 202
 203 =head1 BUGS
 204
 205 All complex software has bugs lurking in it, and this module is no
 206 exception. If you find a bug please either email me, or add the bug
 207 to cpan-RT.
 208
 209 =head1 AUTHOR
 210
 211 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 212
 213 B<with contributions from:>
 214
 215 Robert (rlb3) Boone
 216
 217 Paul (frodwith) Driver
 218
 219 Shawn (Sartak) Moore
 220
 221 Chris (perigrin) Prather
 222
 223 Robert (phaylon) Sedlacek
 224
 225 Tom (dec) Lanyon
 226
 227 Yuval Kogman
 228
 229 Jason May
 230
 231 Cory (gphat) Watson
 232
 233 Florian (rafl) Ragwitz
 234
 235 Evan Carroll
 236
 237 Jesse (doy) Luehrs
 238
 239 =head1 COPYRIGHT AND LICENSE
 240
 241 Copyright 2007-2009 by Infinity Interactive, Inc.
 242
 243 L<http://www.iinteractive.com>
 244
 245 This library is free software; you can redistribute it and/or modify
 246 it under the same terms as Perl itself.
 247
 248 =cut