lib/MooseX/AttributeHelpers.pm

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