lib/Moose/Meta/Attribute/Native/Trait/Hash.pm

   1
   2 package Moose::Meta::Attribute::Native::Trait::Hash;
   3 use Moose::Role;
   4
   5 our $VERSION   = '1.15';
   6 $VERSION = eval $VERSION;
   7 our $AUTHORITY = 'cpan:STEVAN';
   8
   9 use Moose::Meta::Method::Accessor::Native::Hash::accessor;
  10 use Moose::Meta::Method::Accessor::Native::Hash::clear;
  11 use Moose::Meta::Method::Accessor::Native::Hash::count;
  12 use Moose::Meta::Method::Accessor::Native::Hash::defined;
  13 use Moose::Meta::Method::Accessor::Native::Hash::delete;
  14 use Moose::Meta::Method::Accessor::Native::Hash::elements;
  15 use Moose::Meta::Method::Accessor::Native::Hash::exists;
  16 use Moose::Meta::Method::Accessor::Native::Hash::get;
  17 use Moose::Meta::Method::Accessor::Native::Hash::is_empty;
  18 use Moose::Meta::Method::Accessor::Native::Hash::keys;
  19 use Moose::Meta::Method::Accessor::Native::Hash::kv;
  20 use Moose::Meta::Method::Accessor::Native::Hash::set;
  21 use Moose::Meta::Method::Accessor::Native::Hash::values;
  22
  23 with 'Moose::Meta::Attribute::Native::Trait';
  24
  25 sub _helper_type { 'HashRef' }
  26
  27 no Moose::Role;
  28
  29 1;
  30
  31 __END__
  32
  33 =pod
  34
  35 =head1 NAME
  36
  37 Moose::Meta::Attribute::Native::Trait::Hash - Helper trait for HashRef attributes
  38
  39 =head1 SYNOPSIS
  40
  41   package Stuff;
  42   use Moose;
  43
  44   has 'options' => (
  45       traits    => ['Hash'],
  46       is        => 'ro',
  47       isa       => 'HashRef[Str]',
  48       default   => sub { {} },
  49       handles   => {
  50           set_option     => 'set',
  51           get_option     => 'get',
  52           has_no_options => 'is_empty',
  53           num_options    => 'count',
  54           delete_option  => 'delete',
  55           option_pairs   => 'kv',
  56       },
  57   );
  58
  59 =head1 DESCRIPTION
  60
  61 This module provides a Hash attribute which provides a number of
  62 hash-like operations.
  63
  64 =head1 PROVIDED METHODS
  65
  66 =over 4
  67
  68 =item B<get($key, $key2, $key3...)>
  69
  70 Returns values from the hash.
  71
  72 In list context it returns a list of values in the hash for the given keys. In
  73 scalar context it returns the value for the last key specified.
  74
  75 This method requires at least one argument.
  76
  77 =item B<set($key =E<gt> $value, $key2 =E<gt> $value2...)>
  78
  79 Sets the elements in the hash to the given values. It returns the new values
  80 set for each key, in the same order as the keys passed to the method.
  81
  82 This method requires at least two arguments, and expects an even number of
  83 arguments.
  84
  85 =item B<delete($key, $key2, $key3...)>
  86
  87 Removes the elements with the given keys.
  88
  89 In list context it returns a list of values in the hash for the deleted
  90 keys. In scalar context it returns the value for the last key specified.
  91
  92 =item B<keys>
  93
  94 Returns the list of keys in the hash.
  95
  96 This method does not accept any arguments.
  97
  98 =item B<exists($key)>
  99
 100 Returns true if the given key is present in the hash.
 101
 102 This method requires a single argument.
 103
 104 =item B<defined($key)>
 105
 106 Returns true if the value of a given key is defined.
 107
 108 This method requires a single argument.
 109
 110 =item B<values>
 111
 112 Returns the list of values in the hash.
 113
 114 This method does not accept any arguments.
 115
 116 =item B<kv>
 117
 118 Returns the key/value pairs in the hash as an array of array references.
 119
 120   for my $pair ( $object->options->pairs ) {
 121       print "$pair->[0] = $pair->[1]\n";
 122   }
 123
 124 This method does not accept any arguments.
 125
 126 =item B<elements>
 127
 128 Returns the key/value pairs in the hash as a flattened list..
 129
 130 This method does not accept any arguments.
 131
 132 =item B<clear>
 133
 134 Resets the hash to an empty value, like C<%hash = ()>.
 135
 136 This method does not accept any arguments.
 137
 138 =item B<count>
 139
 140 Returns the number of elements in the hash. Also useful for not empty:
 141 C<< has_options => 'count' >>.
 142
 143 This method does not accept any arguments.
 144
 145 =item B<is_empty>
 146
 147 If the hash is populated, returns false. Otherwise, returns true.
 148
 149 This method does not accept any arguments.
 150
 151 =item B<accessor($key)>
 152
 153 =item B<accessor($key, $value)>
 154
 155 If passed one argument, returns the value of the specified key. If passed two
 156 arguments, sets the value of the specified key.
 157
 158 When called as a setter, this method returns the value that was set.
 159
 160 =back
 161
 162 =head1 METHODS
 163
 164 =over 4
 165
 166 =item B<meta>
 167
 168 =back
 169
 170 =head1 BUGS
 171
 172 See L<Moose/BUGS> for details on reporting bugs.
 173
 174 =head1 AUTHOR
 175
 176 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 177
 178 =head1 COPYRIGHT AND LICENSE
 179
 180 Copyright 2007-2009 by Infinity Interactive, Inc.
 181
 182 L<http://www.iinteractive.com>
 183
 184 This library is free software; you can redistribute it and/or modify
 185 it under the same terms as Perl itself.
 186
 187 =cut