lib/MooseX/AttributeHelpers.pm

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