lib/Moose/AttributeHelpers.pm

   1
   2 package Moose::AttributeHelpers;
   3
   4 our $VERSION   = '0.84';
   5 $VERSION = eval $VERSION;
   6 our $AUTHORITY = 'cpan:STEVAN';
   7
   8 use Moose;
   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 1;
  21
  22 __END__
  23
  24 =pod
  25
  26 =head1 NAME
  27
  28 Moose::AttributeHelpers - Extend your attribute interfaces
  29
  30 =head1 SYNOPSIS
  31
  32   package MyClass;
  33   use Moose;
  34   use Moose::AttributeHelpers;
  35
  36   has 'mapping' => (
  37       traits    => [ 'Collection::Hash' ],
  38       is        => 'rw',
  39       isa       => 'HashRef[Str]',
  40       default   => sub { {} },
  41       handles   => {
  42           exists_in_mapping => 'exists',
  43           ids_in_mapping    => 'keys',
  44           get_mapping       => 'get',
  45           set_mapping       => 'set',
  46           set_quantity      => [ set => [ 'quantity' ] ],
  47       },
  48   );
  49
  50
  51   # ...
  52
  53   my $obj = MyClass->new;
  54   $obj->set_quantity(10);      # quantity => 10
  55   $obj->set_mapping(4, 'foo'); # 4 => 'foo'
  56   $obj->set_mapping(5, 'bar'); # 5 => 'bar'
  57   $obj->set_mapping(6, 'baz'); # 6 => 'baz'
  58
  59
  60   # prints 'bar'
  61   print $obj->get_mapping(5) if $obj->exists_in_mapping(5);
  62
  63   # prints '4, 5, 6'
  64   print join ', ', $obj->ids_in_mapping;
  65
  66 =head1 DESCRIPTION
  67
  68 While L<Moose> attributes provide you with a way to name your accessors,
  69 readers, writers, clearers and predicates, this library provides commonly
  70 used attribute helper methods for more specific types of data.
  71
  72 As seen in the L</SYNOPSIS>, you specify the extension via the
  73 C<trait> parameter. Available meta classes are below; see L</METHOD PROVIDERS>.
  74
  75 =head1 PARAMETERS
  76
  77 =head2 handles
  78
  79 This is like C<< handles >> in L<Moose/has>, but only HASH references are
  80 allowed.  Keys are method names that you want installed locally, and values are
  81 methods from the method providers (below).  Currying with delegated methods works normally for C<< handles >>.
  82
  83 =head1 METHOD PROVIDERS
  84
  85 =over
  86
  87 =item L<Number|Moose::AttributeHelpers::Trait::Number>
  88
  89 Common numerical operations.
  90
  91 =item L<String|Moose::AttributeHelpers::Trait::String>
  92
  93 Common methods for string operations.
  94
  95 =item L<Counter|Moose::AttributeHelpers::Trait::Counter>
  96
  97 Methods for incrementing and decrementing a counter attribute.
  98
  99 =item L<Bool|Moose::AttributeHelpers::Trait::Bool>
 100
 101 Common methods for boolean values.
 102
 103 =item L<Collection::Hash|Moose::AttributeHelpers::Trait::Collection::Hash>
 104
 105 Common methods for hash references.
 106
 107 =item L<Collection::ImmutableHash|Moose::AttributeHelpers::Trait::Collection::ImmutableHash>
 108
 109 Common methods for inspecting hash references.
 110
 111 =item L<Collection::Array|Moose::AttributeHelpers::Trait::Collection::Array>
 112
 113 Common methods for array references.
 114
 115 =item L<Collection::List|Moose::AttributeHelpers::Trait::Collection::List>
 116
 117 Common list methods for array references.
 118
 119 =back
 120
 121 =head1 CAVEAT
 122
 123 This is an early release of this module. Right now it is in great need
 124 of documentation and tests in the test suite. However, we have used this
 125 module to great success at C<$work> where it has been tested very thoroughly
 126 and deployed into a major production site.
 127
 128 I plan on getting better docs and tests in the next few releases, but until
 129 then please refer to the few tests we do have and feel free email and/or
 130 message me on irc.perl.org if you have any questions.
 131
 132 =head1 TODO
 133
 134 We need tests and docs badly.
 135
 136 =head1 BUGS
 137
 138 All complex software has bugs lurking in it, and this module is no
 139 exception. If you find a bug please either email me, or add the bug
 140 to cpan-RT.
 141
 142 =head1 AUTHOR
 143
 144 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 145
 146 B<with contributions from:>
 147
 148 Robert (rlb3) Boone
 149
 150 Paul (frodwith) Driver
 151
 152 Shawn (Sartak) Moore
 153
 154 Chris (perigrin) Prather
 155
 156 Robert (phaylon) Sedlacek
 157
 158 Tom (dec) Lanyon
 159
 160 Yuval Kogman
 161
 162 Jason May
 163
 164 Cory (gphat) Watson
 165
 166 Florian (rafl) Ragwitz
 167
 168 Evan Carroll
 169
 170 Jesse (doy) Luehrs
 171
 172 =head1 COPYRIGHT AND LICENSE
 173
 174 Copyright 2007-2009 by Infinity Interactive, Inc.
 175
 176 L<http://www.iinteractive.com>
 177
 178 This library is free software; you can redistribute it and/or modify
 179 it under the same terms as Perl itself.
 180
 181 =cut