lib/MooseX/AttributeHelpers.pm

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