lib/MooseX/AttributeHelpers.pm

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