lib/Moose/Meta/Attribute/Native.pm

   1 package Moose::Meta::Attribute::Native;
   2
   3 our $VERSION   = '0.89';
   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 a way to name your accessors, readers,
  77 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 data structure 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         traits    => ['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         traits    => ['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 =item L<Hash|Moose::Meta::Attribute::Native::Trait::Hash>
 170
 171 Common methods for hash references.
 172
 173     has 'options' => (
 174         traits    => ['Hash'],
 175         is        => 'ro',
 176         isa       => 'HashRef[Str]',
 177         default   => sub { {} },
 178         handles   => {
 179             set_option => 'set',
 180             get_option => 'get',
 181             has_option => 'exists',
 182         }
 183     );
 184
 185 =item L<Array|Moose::Meta::Attribute::Native::Trait::Array>
 186
 187 Common methods for array references.
 188
 189     has 'queue' => (
 190        traits     => ['Array'],
 191        is         => 'ro',
 192        isa        => 'ArrayRef[Str]',
 193        default    => sub { [] },
 194        handles    => {
 195            add_item  => 'push',
 196            next_item => 'shift',
 197        }
 198     );
 199
 200 =back
 201
 202 =head1 BUGS
 203
 204 All complex software has bugs lurking in it, and this module is no
 205 exception. If you find a bug please either email me, or add the bug
 206 to cpan-RT.
 207
 208 =head1 AUTHOR
 209
 210 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 211
 212 B<with contributions from:>
 213
 214 Robert (rlb3) Boone
 215
 216 Paul (frodwith) Driver
 217
 218 Shawn (Sartak) Moore
 219
 220 Chris (perigrin) Prather
 221
 222 Robert (phaylon) Sedlacek
 223
 224 Tom (dec) Lanyon
 225
 226 Yuval Kogman
 227
 228 Jason May
 229
 230 Cory (gphat) Watson
 231
 232 Florian (rafl) Ragwitz
 233
 234 Evan Carroll
 235
 236 Jesse (doy) Luehrs
 237
 238 =head1 COPYRIGHT AND LICENSE
 239
 240 Copyright 2007-2009 by Infinity Interactive, Inc.
 241
 242 L<http://www.iinteractive.com>
 243
 244 This library is free software; you can redistribute it and/or modify
 245 it under the same terms as Perl itself.
 246
 247 =cut