lib/Moose/AttributeHelpers.pm

   1
   2 package Moose::AttributeHelpers;
   3
   4 our $VERSION   = '0.83';
   5 $VERSION = eval $VERSION;
   6 our $AUTHORITY = 'cpan:STEVAN';
   7
   8 use Moose 0.56 ();
   9
  10 use Moose::AttributeHelpers::Trait::Bool;
  11 use Moose::AttributeHelpers::Trait::Counter;
  12 use Moose::AttributeHelpers::Trait::Number;
  13 use Moose::AttributeHelpers::Trait::String;
  14 use Moose::AttributeHelpers::Trait::Collection::List;
  15 use Moose::AttributeHelpers::Trait::Collection::Array;
  16 use Moose::AttributeHelpers::Trait::Collection::Hash;
  17 use Moose::AttributeHelpers::Trait::Collection::ImmutableHash;
  18 use Moose::AttributeHelpers::Trait::Collection::Bag;
  19
  20 use Moose::AttributeHelpers::Counter;
  21 use Moose::AttributeHelpers::Number;
  22 use Moose::AttributeHelpers::String;
  23 use Moose::AttributeHelpers::Bool;
  24 use Moose::AttributeHelpers::Collection::List;
  25 use Moose::AttributeHelpers::Collection::Array;
  26 use Moose::AttributeHelpers::Collection::Hash;
  27 use Moose::AttributeHelpers::Collection::ImmutableHash;
  28 use Moose::AttributeHelpers::Collection::Bag;
  29
  30 1;
  31
  32 __END__
  33
  34 =pod
  35
  36 =head1 NAME
  37
  38 Moose::AttributeHelpers - Extend your attribute interfaces
  39
  40 =head1 SYNOPSIS
  41
  42   package MyClass;
  43   use Moose;
  44   use Moose::AttributeHelpers;
  45
  46   has 'mapping' => (
  47       metaclass => 'Collection::Hash',
  48       is        => 'rw',
  49       isa       => 'HashRef[Str]',
  50       default   => sub { {} },
  51       handles   => {
  52           exists_in_mapping => 'exists',
  53           ids_in_mapping    => 'keys',
  54           get_mapping       => 'get',
  55           set_mapping       => 'set',
  56           set_quantity      => [ set => [ 'quantity' ] ],
  57       },
  58   );
  59
  60
  61   # ...
  62
  63   my $obj = MyClass->new;
  64   $obj->set_quantity(10);      # quantity => 10
  65   $obj->set_mapping(4, 'foo'); # 4 => 'foo'
  66   $obj->set_mapping(5, 'bar'); # 5 => 'bar'
  67   $obj->set_mapping(6, 'baz'); # 6 => 'baz'
  68
  69
  70   # prints 'bar'
  71   print $obj->get_mapping(5) if $obj->exists_in_mapping(5);
  72
  73   # prints '4, 5, 6'
  74   print join ', ', $obj->ids_in_mapping;
  75
  76 =head1 DESCRIPTION
  77
  78 While L<Moose> attributes provide you with a way to name your accessors,
  79 readers, writers, clearers and predicates, this library provides commonly
  80 used attribute helper methods for more specific types of data.
  81
  82 As seen in the L</SYNOPSIS>, you specify the extension via the
  83 C<metaclass> parameter. Available meta classes are:
  84
  85 =head1 PARAMETERS
  86
  87 =head2 handles
  88
  89 This points to a hashref that uses C<method> for the keys and
  90 C<stuff> for the values.  The method will be added to
  91 the object itself and do what you want.
  92
  93 =head2 curries
  94
  95 This points to a hashref that uses C<provider> for the keys and
  96 has two choices for the value:
  97
  98 You can supply C<< {method => [ @args ]} >> for the values.  The method will be
  99 added to the object itself (always using C<@args> as the beginning arguments).
 100
 101 Another approach to curry a method provider is to supply a coderef instead of an
 102 arrayref. The code ref takes C<$self>, C<$body>, and any additional arguments
 103 passed to the final method.
 104
 105   # ...
 106
 107   curries => {
 108       grep => {
 109           times_with_day => sub {
 110               my ($self, $body, $datetime) = @_;
 111               $body->($self, sub { $_->ymd eq $datetime->ymd });
 112           }
 113       }
 114   }
 115
 116   # ...
 117
 118   $obj->times_with_day(DateTime->now); # takes datetime argument, checks day
 119
 120
 121 =head1 METHOD PROVIDERS
 122
 123 =over
 124
 125 =item L<Number|Moose::AttributeHelpers::Number>
 126
 127 Common numerical operations.
 128
 129 =item L<String|Moose::AttributeHelpers::String>
 130
 131 Common methods for string operations.
 132
 133 =item L<Counter|Moose::AttributeHelpers::Counter>
 134
 135 Methods for incrementing and decrementing a counter attribute.
 136
 137 =item L<Bool|Moose::AttributeHelpers::Bool>
 138
 139 Common methods for boolean values.
 140
 141 =item L<Collection::Hash|Moose::AttributeHelpers::Collection::Hash>
 142
 143 Common methods for hash references.
 144
 145 =item L<Collection::ImmutableHash|Moose::AttributeHelpers::Collection::ImmutableHash>
 146
 147 Common methods for inspecting hash references.
 148
 149 =item L<Collection::Array|Moose::AttributeHelpers::Collection::Array>
 150
 151 Common methods for array references.
 152
 153 =item L<Collection::List|Moose::AttributeHelpers::Collection::List>
 154
 155 Common list methods for array references.
 156
 157 =back
 158
 159 =head1 CAVEAT
 160
 161 This is an early release of this module. Right now it is in great need
 162 of documentation and tests in the test suite. However, we have used this
 163 module to great success at C<$work> where it has been tested very thoroughly
 164 and deployed into a major production site.
 165
 166 I plan on getting better docs and tests in the next few releases, but until
 167 then please refer to the few tests we do have and feel free email and/or
 168 message me on irc.perl.org if you have any questions.
 169
 170 =head1 TODO
 171
 172 We need tests and docs badly.
 173
 174 =head1 BUGS
 175
 176 All complex software has bugs lurking in it, and this module is no
 177 exception. If you find a bug please either email me, or add the bug
 178 to cpan-RT.
 179
 180 =head1 AUTHOR
 181
 182 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 183
 184 B<with contributions from:>
 185
 186 Robert (rlb3) Boone
 187
 188 Paul (frodwith) Driver
 189
 190 Shawn (Sartak) Moore
 191
 192 Chris (perigrin) Prather
 193
 194 Robert (phaylon) Sedlacek
 195
 196 Tom (dec) Lanyon
 197
 198 Yuval Kogman
 199
 200 Jason May
 201
 202 Cory (gphat) Watson
 203
 204 Florian (rafl) Ragwitz
 205
 206 Evan Carroll
 207
 208 Jesse (doy) Luehrs
 209
 210 =head1 COPYRIGHT AND LICENSE
 211
 212 Copyright 2007-2009 by Infinity Interactive, Inc.
 213
 214 L<http://www.iinteractive.com>
 215
 216 This library is free software; you can redistribute it and/or modify
 217 it under the same terms as Perl itself.
 218
 219 =cut