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