File Coverage

blib/lib/Moose/Meta/Attribute/Native.pm
Criterion Covered Total %
statement 11 11 100.0
branch n/a
condition n/a
subroutine 10 10 100.0
pod n/a
total 21 21 100.0


line stmt bran cond sub pod time code
1 388     388   2597 use strict;
  388         846  
  388         11073  
2 388     388   1845 use warnings;
  388         796  
  388         19196  
3             package Moose::Meta::Attribute::Native;
4             our $VERSION = '2.2203';
5              
6 388     388   2314 use Module::Runtime 'require_module';
  388         748  
  388         3267  
7              
8             my @trait_names = qw(Bool Counter Number String Array Hash Code);
9              
10             for my $trait_name (@trait_names) {
11             my $trait_class = "Moose::Meta::Attribute::Native::Trait::$trait_name";
12             my $meta = Class::MOP::Class->initialize(
13             "Moose::Meta::Attribute::Custom::Trait::$trait_name"
14             );
15              
16             if ($meta->find_method_by_name('register_implementation')) {
17             my $class = $meta->name->register_implementation;
18             die "An implementation for $trait_name already exists " .
19             "(found '$class' when trying to register '$trait_class')"
20             }
21             $meta->add_method(register_implementation => sub {
22             # resolve_metatrait_alias will load classes anyway, but throws away
23             # their error message; we WANT to die if there's a problem
24 59     59   284 require_module($trait_class);
        59      
        59      
        59      
        59      
        59      
        59      
25 59         762 return $trait_class;
26             });
27             }
28              
29             1;
30              
31             # ABSTRACT: Delegate to native Perl types
32              
33             __END__
34              
35             =pod
36              
37             =encoding UTF-8
38              
39             =head1 NAME
40              
41             Moose::Meta::Attribute::Native - Delegate to native Perl types
42              
43             =head1 VERSION
44              
45             version 2.2203
46              
47             =head1 SYNOPSIS
48              
49             package MyClass;
50             use Moose;
51              
52             has 'mapping' => (
53             traits => ['Hash'],
54             is => 'rw',
55             isa => 'HashRef[Str]',
56             default => sub { {} },
57             handles => {
58             exists_in_mapping => 'exists',
59             ids_in_mapping => 'keys',
60             get_mapping => 'get',
61             set_mapping => 'set',
62             set_quantity => [ set => 'quantity' ],
63             },
64             );
65              
66             my $obj = MyClass->new;
67             $obj->set_quantity(10); # quantity => 10
68             $obj->set_mapping('foo', 4); # foo => 4
69             $obj->set_mapping('bar', 5); # bar => 5
70             $obj->set_mapping('baz', 6); # baz => 6
71              
72             # prints 5
73             print $obj->get_mapping('bar') if $obj->exists_in_mapping('bar');
74              
75             # prints 'quantity, foo, bar, baz'
76             print join ', ', $obj->ids_in_mapping;
77              
78             =head1 DESCRIPTION
79              
80             Native delegations allow you to delegate to native Perl data
81             structures as if they were objects. For example, in the L</SYNOPSIS> you can
82             see a hash reference being treated as if it has methods named C<exists()>,
83             C<keys()>, C<get()>, and C<set()>.
84              
85             The delegation methods (mostly) map to Perl builtins and operators. The return
86             values of these delegations should be the same as the corresponding Perl
87             operation. Any deviations will be explicitly documented.
88              
89             =head1 API
90              
91             Native delegations are enabled by passing certain options to C<has> when
92             creating an attribute.
93              
94             =head2 traits
95              
96             To enable this feature, pass the appropriate name in the C<traits> array
97             reference for the attribute. For example, to enable this feature for hash
98             reference, we include C<'Hash'> in the list of traits.
99              
100             =head2 isa
101              
102             You will need to make sure that the attribute has an appropriate type. For
103             example, to use this with a Hash you must specify that your attribute is some
104             sort of C<HashRef>.
105              
106             =head2 handles
107              
108             This is just like any other delegation, but only a hash reference is allowed
109             when defining native delegations. The keys are the methods to be created in
110             the class which contains the attribute. The values are the methods provided by
111             the associated trait. Currying works the same way as it does with any other
112             delegation.
113              
114             See the docs for each native trait for details on what methods are available.
115              
116             =head1 TRAITS FOR NATIVE DELEGATIONS
117              
118             Below are some simple examples of each native trait. More features are
119             available than what is shown here; this is just a quick synopsis.
120              
121             =over
122              
123             =item Array (L<Moose::Meta::Attribute::Native::Trait::Array>)
124              
125             has 'queue' => (
126             traits => ['Array'],
127             is => 'ro',
128             isa => 'ArrayRef[Str]',
129             default => sub { [] },
130             handles => {
131             add_item => 'push',
132             next_item => 'shift',
133             # ...
134             }
135             );
136              
137             =item Bool (L<Moose::Meta::Attribute::Native::Trait::Bool>)
138              
139             has 'is_lit' => (
140             traits => ['Bool'],
141             is => 'ro',
142             isa => 'Bool',
143             default => 0,
144             handles => {
145             illuminate => 'set',
146             darken => 'unset',
147             flip_switch => 'toggle',
148             is_dark => 'not',
149             # ...
150             }
151             );
152              
153             =item Code (L<Moose::Meta::Attribute::Native::Trait::Code>)
154              
155             has 'callback' => (
156             traits => ['Code'],
157             is => 'ro',
158             isa => 'CodeRef',
159             default => sub {
160             sub {'called'}
161             },
162             handles => {
163             call => 'execute',
164             # ...
165             }
166             );
167              
168             =item Counter (L<Moose::Meta::Attribute::Native::Trait::Counter>)
169              
170             has 'counter' => (
171             traits => ['Counter'],
172             is => 'ro',
173             isa => 'Num',
174             default => 0,
175             handles => {
176             inc_counter => 'inc',
177             dec_counter => 'dec',
178             reset_counter => 'reset',
179             # ...
180             }
181             );
182              
183             =item Hash (L<Moose::Meta::Attribute::Native::Trait::Hash>)
184              
185             has 'options' => (
186             traits => ['Hash'],
187             is => 'ro',
188             isa => 'HashRef[Str]',
189             default => sub { {} },
190             handles => {
191             set_option => 'set',
192             get_option => 'get',
193             has_option => 'exists',
194             # ...
195             }
196             );
197              
198             =item Number (L<Moose::Meta::Attribute::Native::Trait::Number>)
199              
200             has 'integer' => (
201             traits => ['Number'],
202             is => 'ro',
203             isa => 'Int',
204             default => 5,
205             handles => {
206             set => 'set',
207             add => 'add',
208             sub => 'sub',
209             mul => 'mul',
210             div => 'div',
211             mod => 'mod',
212             abs => 'abs',
213             # ...
214             }
215             );
216              
217             =item String (L<Moose::Meta::Attribute::Native::Trait::String>)
218              
219             has 'text' => (
220             traits => ['String'],
221             is => 'ro',
222             isa => 'Str',
223             default => q{},
224             handles => {
225             add_text => 'append',
226             replace_text => 'replace',
227             # ...
228             }
229             );
230              
231             =back
232              
233             =head1 COMPATIBILITY WITH MooseX::AttributeHelpers
234              
235             This feature used to be a separated CPAN distribution called
236             L<MooseX::AttributeHelpers>.
237              
238             When the feature was incorporated into the Moose core, some of the API details
239             were changed. The underlying capabilities are the same, but some details of
240             the API were changed.
241              
242             =head1 BUGS
243              
244             See L<Moose/BUGS> for details on reporting bugs.
245              
246             =head1 AUTHORS
247              
248             =over 4
249              
250             =item *
251              
252             Stevan Little <stevan@cpan.org>
253              
254             =item *
255              
256             Dave Rolsky <autarch@urth.org>
257              
258             =item *
259              
260             Jesse Luehrs <doy@cpan.org>
261              
262             =item *
263              
264             Shawn M Moore <sartak@cpan.org>
265              
266             =item *
267              
268             יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
269              
270             =item *
271              
272             Karen Etheridge <ether@cpan.org>
273              
274             =item *
275              
276             Florian Ragwitz <rafl@debian.org>
277              
278             =item *
279              
280             Hans Dieter Pearcey <hdp@cpan.org>
281              
282             =item *
283              
284             Chris Prather <chris@prather.org>
285              
286             =item *
287              
288             Matt S Trout <mstrout@cpan.org>
289              
290             =back
291              
292             =head1 COPYRIGHT AND LICENSE
293              
294             This software is copyright (c) 2006 by Infinity Interactive, Inc.
295              
296             This is free software; you can redistribute it and/or modify it under
297             the same terms as the Perl 5 programming language system itself.
298              
299             =cut