Commit | Line | Data |
17e5e226 |
1 | package Moose::Meta::Attribute::Native; |
e3c07b19 |
2 | |
cdf3cae6 |
3 | my @trait_names = qw(Bool Counter Number String Array Hash Code); |
fafc8b9b |
4 | |
5 | for my $trait_name (@trait_names) { |
c466e58f |
6 | my $trait_class = "Moose::Meta::Attribute::Native::Trait::$trait_name"; |
fafc8b9b |
7 | my $meta = Class::MOP::Class->initialize( |
8 | "Moose::Meta::Attribute::Custom::Trait::$trait_name" |
9 | ); |
10 | if ($meta->find_method_by_name('register_implementation')) { |
11 | my $class = $meta->name->register_implementation; |
12 | Moose->throw_error( |
13 | "An implementation for $trait_name already exists " . |
14 | "(found '$class' when trying to register '$trait_class')" |
15 | ); |
16 | } |
17 | $meta->add_method(register_implementation => sub { |
18 | # resolve_metatrait_alias will load classes anyway, but throws away |
19 | # their error message; we WANT to die if there's a problem |
20 | Class::MOP::load_class($trait_class); |
21 | return $trait_class; |
22 | }); |
23 | } |
e3c07b19 |
24 | |
e3c07b19 |
25 | 1; |
26 | |
ad46f524 |
27 | # ABSTRACT: Delegate to native Perl types |
28 | |
e3c07b19 |
29 | __END__ |
30 | |
31 | =pod |
32 | |
e3c07b19 |
33 | =head1 SYNOPSIS |
34 | |
35 | package MyClass; |
36 | use Moose; |
e3c07b19 |
37 | |
38 | has 'mapping' => ( |
e132fd56 |
39 | traits => ['Hash'], |
40 | is => 'rw', |
41 | isa => 'HashRef[Str]', |
42 | default => sub { {} }, |
43 | handles => { |
e3c07b19 |
44 | exists_in_mapping => 'exists', |
45 | ids_in_mapping => 'keys', |
46 | get_mapping => 'get', |
47 | set_mapping => 'set', |
cb562ad2 |
48 | set_quantity => [ set => 'quantity' ], |
e3c07b19 |
49 | }, |
50 | ); |
51 | |
e3c07b19 |
52 | my $obj = MyClass->new; |
53 | $obj->set_quantity(10); # quantity => 10 |
2420461c |
54 | $obj->set_mapping('foo', 4); # foo => 4 |
55 | $obj->set_mapping('bar', 5); # bar => 5 |
56 | $obj->set_mapping('baz', 6); # baz => 6 |
e3c07b19 |
57 | |
2420461c |
58 | # prints 5 |
59 | print $obj->get_mapping('bar') if $obj->exists_in_mapping('bar'); |
e3c07b19 |
60 | |
2420461c |
61 | # prints 'quantity, foo, bar, baz' |
e3c07b19 |
62 | print join ', ', $obj->ids_in_mapping; |
63 | |
64 | =head1 DESCRIPTION |
65 | |
e132fd56 |
66 | Native delegations allow you to delegate to native Perl data |
e11cc42d |
67 | structures as if they were objects. For example, in the L</SYNOPSIS> you can |
e132fd56 |
68 | see a hash reference being treated as if it has methods named C<exists()>, |
69 | C<keys()>, C<get()>, and C<set()>. |
70 | |
71 | The delegation methods (mostly) map to Perl builtins and operators. The return |
72 | values of these delegations should be the same as the corresponding Perl |
73 | operation. Any deviations will be explicitly documented. |
74 | |
75 | =head1 API |
e3c07b19 |
76 | |
e132fd56 |
77 | Native delegations are enabled by passing certain options to C<has> when |
78 | creating an attribute. |
e3c07b19 |
79 | |
e132fd56 |
80 | =head2 traits |
87b4e821 |
81 | |
e132fd56 |
82 | To enable this feature, pass the appropriate name in the C<traits> array |
83 | reference for the attribute. For example, to enable this feature for hash |
84 | reference, we include C<'Hash'> in the list of traits. |
85 | |
86 | =head2 isa |
87 | |
88 | You will need to make sure that the attribute has an appropriate type. For |
89 | example, to use this with a Hash you must specify that your attribute is some |
90 | sort of C<HashRef>. |
91 | |
92 | If you I<don't> specify a type, each trait has a default type it will use. |
e3c07b19 |
93 | |
94 | =head2 handles |
95 | |
e132fd56 |
96 | This is just like any other delegation, but only a hash reference is allowed |
97 | when defining native delegations. The keys are the methods to be created in |
98 | the class which contains the attribute. The values are the methods provided by |
99 | the associated trait. Currying works the same way as it does with any other |
100 | delegation. |
e3c07b19 |
101 | |
e132fd56 |
102 | See the docs for each native trait for details on what methods are available. |
103 | |
b79a1a50 |
104 | =head2 is |
105 | |
106 | Some traits provide a default C<is> for historical reasons. This behavior is |
c33c3630 |
107 | deprecated, and you are strongly encouraged to provide a value. If you don't |
b79a1a50 |
108 | plan to read and write the attribute value directly, you can set C<< is => |
109 | 'bare' >> to prevent standard accessor generation. |
110 | |
b6bf6592 |
111 | =head2 default or builder |
112 | |
b79a1a50 |
113 | Some traits provide a default C<default> for historical reasons. This behavior |
b6bf6592 |
114 | is deprecated, and you are strongly encouraged to provide a default value or |
115 | make the attribute required. |
116 | |
e132fd56 |
117 | =head1 TRAITS FOR NATIVE DELEGATIONS |
e3c07b19 |
118 | |
119 | =over |
120 | |
66cce11c |
121 | =item L<Array|Moose::Meta::Attribute::Native::Trait::Array> |
e3c07b19 |
122 | |
66cce11c |
123 | has 'queue' => ( |
e132fd56 |
124 | traits => ['Array'], |
125 | is => 'ro', |
126 | isa => 'ArrayRef[Str]', |
127 | default => sub { [] }, |
128 | handles => { |
66cce11c |
129 | add_item => 'push', |
130 | next_item => 'shift', |
39ab25ce |
131 | # ... |
52e0d71f |
132 | } |
133 | ); |
134 | |
66cce11c |
135 | =item L<Bool|Moose::Meta::Attribute::Native::Trait::Bool> |
e3c07b19 |
136 | |
66cce11c |
137 | has 'is_lit' => ( |
e132fd56 |
138 | traits => ['Bool'], |
139 | is => 'ro', |
140 | isa => 'Bool', |
141 | default => 0, |
142 | handles => { |
66cce11c |
143 | illuminate => 'set', |
144 | darken => 'unset', |
145 | flip_switch => 'toggle', |
146 | is_dark => 'not', |
147 | # ... |
148 | } |
149 | ); |
150 | |
151 | =item L<Code|Moose::Meta::Attribute::Native::Trait::Code> |
152 | |
66cce11c |
153 | has 'callback' => ( |
e132fd56 |
154 | traits => ['Code'], |
155 | is => 'ro', |
156 | isa => 'CodeRef', |
157 | default => sub { |
158 | sub {'called'} |
159 | }, |
160 | handles => { |
66cce11c |
161 | call => 'execute', |
39ab25ce |
162 | # ... |
52e0d71f |
163 | } |
164 | ); |
165 | |
c466e58f |
166 | =item L<Counter|Moose::Meta::Attribute::Native::Trait::Counter> |
e3c07b19 |
167 | |
52e0d71f |
168 | has 'counter' => ( |
e132fd56 |
169 | traits => ['Counter'], |
170 | is => 'ro', |
171 | isa => 'Num', |
172 | default => 0, |
173 | handles => { |
52e0d71f |
174 | inc_counter => 'inc', |
175 | dec_counter => 'dec', |
176 | reset_counter => 'reset', |
39ab25ce |
177 | # ... |
52e0d71f |
178 | } |
179 | ); |
180 | |
c466e58f |
181 | =item L<Hash|Moose::Meta::Attribute::Native::Trait::Hash> |
e3c07b19 |
182 | |
52e0d71f |
183 | has 'options' => ( |
e132fd56 |
184 | traits => ['Hash'], |
185 | is => 'ro', |
186 | isa => 'HashRef[Str]', |
187 | default => sub { {} }, |
188 | handles => { |
9958cbe1 |
189 | set_option => 'set', |
190 | get_option => 'get', |
191 | has_option => 'exists', |
39ab25ce |
192 | # ... |
52e0d71f |
193 | } |
194 | ); |
e3c07b19 |
195 | |
66cce11c |
196 | =item L<Number|Moose::Meta::Attribute::Native::Trait::Number> |
e3c07b19 |
197 | |
66cce11c |
198 | has 'integer' => ( |
e132fd56 |
199 | traits => ['Number'], |
200 | is => 'ro', |
201 | isa => 'Int', |
202 | default => 5, |
203 | handles => { |
66cce11c |
204 | set => 'set', |
205 | add => 'add', |
206 | sub => 'sub', |
207 | mul => 'mul', |
208 | div => 'div', |
209 | mod => 'mod', |
210 | abs => 'abs', |
754a4833 |
211 | # ... |
212 | } |
52e0d71f |
213 | ); |
e3c07b19 |
214 | |
66cce11c |
215 | =item L<String|Moose::Meta::Attribute::Native::Trait::String> |
b86a4688 |
216 | |
66cce11c |
217 | has 'text' => ( |
e132fd56 |
218 | traits => ['String'], |
219 | is => 'ro', |
220 | isa => 'Str', |
221 | default => q{}, |
222 | handles => { |
66cce11c |
223 | add_text => 'append', |
224 | replace_text => 'replace', |
754a4833 |
225 | # ... |
226 | } |
b86a4688 |
227 | ); |
228 | |
e3c07b19 |
229 | =back |
230 | |
e132fd56 |
231 | =head1 COMPATIBILITY WITH MooseX::AttributeHelpers |
232 | |
233 | This feature used to be a separated CPAN distribution called |
234 | L<MooseX::AttributeHelpers>. |
235 | |
236 | When the feature was incorporated into the Moose core, some of the API details |
237 | were changed. The underlying capabilities are the same, but some details of |
238 | the API were changed. |
239 | |
e3c07b19 |
240 | =head1 BUGS |
241 | |
d4048ef3 |
242 | See L<Moose/BUGS> for details on reporting bugs. |
e3c07b19 |
243 | |
e3c07b19 |
244 | =cut |