Class/AttributesHandler.pm

filter: Statementstmt 91.8% 158 / 172 Branchbran 80.4% 37 / 46 Conditioncond 83.3% 10 / 12 MC/DCmcdc 75.0% 6 / 8 Subroutinesub 96.0% 24 / 25 Podpod 100% 5 / 5 totaltotal 89.5% 240 / 268 CC 35 SCAR 16.1
CC
35
Cov
89%
register_attributes
11.1
_attribute_handler
7.0
_resolve_sub
6.1
CRAP 5.0
« Class/Attributes.pm ↑ Summary Class/Implements.pm »
1 package Fukurama::Class::AttributesHandler;
2 4 ▶use Fukurama::Class::Version(0.01);
Subroutine BEGIN: called CC=1 SCAR=0.0
3 4 ▶use Fukurama::Class::Rigid;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 4 ▶use Fukurama::Class::Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
5
6 4 my $ATT_METHODS;
7 my $EXPORTED;
8 4 my $LAST_ATTRIBUTE_METHOD;
9 4 my $SUBS;
10 4 my $HELPER_METHODS;
11 4 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
12 4 $ATT_METHODS = {};
13 4 $EXPORTED = {};
14 4 $SUBS = {};
15 4 $LAST_ATTRIBUTE_METHOD = undef;
16 4 $HELPER_METHODS = {};
17 }
18
19 =head1 NAME
20
21 Fukurama::Class::AttributesHandler - Helper class to provide corrrect handling of attributes
22
23 =head1 VERSION
24
25 Version 0.01 (beta)
26
27 =head1 SYNOPSIS
28
29 {
30 package MyAttributeHandler;
31 sub MyAttribute {
32 my $class = $_[0];
33 my $method_data = $_[1];
34
35 warn("Method '$method_data->{'sub_name'}' was resolved at compiletime with data: '$method_data->{'data'}'");
36 # says: Method 'my_own_method' was resolved at compiletime with data: 'foo, bar'
37 }
38 }
39 {
40 package MyClass;
41 use Fukurama::Class::AttributesHandler();
42 Fukurama::Class::AttributesHandler->register_attributes('MyAttributeHandler');
43 Fukurama::Class::AttributesHandler->export('MyClass');
44
45 sub my_own_method : MyAttribute(foo, bar) {}
46 }
47
48 =head1 DESCRIPTION
49
50 This module enables the possibility to define your own subroutine-attributes. This is also done with the CPAN L<Attribute> module
51 but here you get extra information for the subroutine, which use the attribute. E.g. the resolved methodname.
52
53 This helper class is used from Fukurama::Class::Attribute::OOStandard to enable the OO-method-signatures.
54
55 =head1 EXPORT
56
57 =over 4
58
59 =item MODIFY_CODE_ATTRIBUTES
60
61 would be decorated if it exist or created if it isn't in the current class.
62
63 =back
64
65 =head1 METHODS
66
67 =over 4
68
69 =item register_attributes( attribute_handler_class:STRING ) return:BOOLEAN
70
71 Register a handler class which defines attributes. See L<How to define an attribute-handler-class> below
72
73 =item export( export_to_class:STRING ) return:BOOLEAN
74
75 This will export or decorate the MODIFY_CODE_ATTRIBUTES to the export_to_class class. Be sure that you call this method
76 in a BEGIN block. Perl check them all at compiletime and croak, if some is not defined.
77
78 =item get_registered_subs( ) return:HASHREF
79
80 Get the method-definitions from all methods in your code, which use attributes over this attribute handler.
81 This is to check th code structure (or to create some documentation...)
82
83 =item register_helper_method( methodname:STRING ) return:VOID
84
85 All registered methodnames would be omitted as attributes, when a attribute-handler-class is parsed. But
86 if they are missed in a attribute-handler-class, the registration would fail.
87
88 =item run_check( ) return:VOID
89
90 Resolve all method names, which are unresolved at compiletime, and calls the atribute-definition-methods
91 in the handler-class. This is a helper method for static perl (see Fukurama::Class > BUGS)
92
93 =back
94
95 =head1 How to define an attribute-handler-class
96
97 All methods of an attribute-handler-class have to be attribute-definitions, except these, which are registered via register helper methods.
98 This methods have to start with an uppercase letter (it is a perl specification). They will get a hash reference as single parameter.
99 In this hash you will find information of the method which use your attribute. They are:
100
101 =over 4
102
103 =item class:STRING
104
105 The name of the class, which contain the subroutine which use the attribute (*puh*). Can be empty in some cases. Look at L<resolved>.
106
107 =item sub_name:STRING
108
109 The resolved name of the subroutine, which use the attribute. Perls attributes doesn't resolve the name by itself,
110 so you will normally only get the sub-reference and not the name. It can be empty in some cases. Look at L<resolved>.
111
112 =item data:STRING
113
114 The defined attribute-data. if you say 'sub new : MyAtt(this is a $test)' you will get the string 'this is a $test'.
115
116 =item sub:CODEREF
117
118 The code-refrence of the subroutine, which use the attribute.
119
120 =item resolved:BOOLEAN
121
122 A flag for the status of method name resolving for this method. In some cases, if you force a call, this flag will
123 be FALSE and the B<sub_name> will be empty.
124
125 =item attribute:STRING
126
127 The name of the attribute. This is the same like the name of your attribute-method.
128
129 =item handler:HASHREF
130
131 A reference to your attribute class and to the actual attribute method.
132
133 =item executed: BOOLEAN
134
135 An internal flag to avoid double callings of your attribute-methods.
136
137 =back
138
139 =head1 AUTHOR, BUGS, SUPPORT, ACKNOWLEDGEMENTS, COPYRIGHT & LICENSE
140
141 see perldoc of L<Fukurama::Class>
142
143 =cut
144
145 # STATIC boolean
146 6 ▶sub register_attributes {
Subroutine register_attributes: called CC=11 SCAR=24.0
Pod documented
147 6 my $class = $_[0];
148 6 my $attribute_class = $_[1];
149
150 6 my @subs = ();
151 6 my $check_methods_exist = {};
152 {
153
154 4 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
155
156 6 my %symbols = %{$attribute_class . '::'};
157 0 ▶ if(!scalar(%symbols) && !eval("use $attribute_class;return 1;")) {
Subroutine BEGIN: called CC=1 SCAR=0.4
Branch: 1 branch
BranchTrueFalseTotal
unless (scalar %symbols or eval "use $attribute_class;return 1;") 1 5 6
Condition66%2/3
scalar %symbols or eval "use $attribute_class;return 1;"
l!l&&r!l&&!r
501
MC/DC50%1/2
scalar %symbols or eval "use $attribute_class;return 1;"
scalar %symbols eval "use $attribute_class;return 1;"
Truth table66%2/3
A or B
A= scalar %symbolsB= eval "use $attribute_class;return 1;"
ABresult
1X1
011
000
158 1 _croak("Failed to load attribute-class '$attribute_class' (maybe this class is empty?): $@\n");
159 0 return 0;
160 }
161 5 foreach my $name (keys(%symbols)) {
162 40 ▶ next if(!*{$attribute_class . '::' . $name}{'CODE'});
Branch: 1 branch
BranchTrueFalseTotal
unless *{$attribute_class . '::' . $name;}{"CODE"} 29 11 40
163 11 ▶ if($HELPER_METHODS->{$name}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($HELPER_METHODS->{$name}) 4 7 11
164 4 $check_methods_exist->{$name} = 1;
165 4 next;
166 }
167 7 push(@subs, $name);
168 }
169 }
170
171 5 my @missed_helper_methods = ();
172 5 foreach my $name (keys(%$HELPER_METHODS)) {
173 5 ▶ next if($check_methods_exist->{$name});
Branch: 1 branch
BranchTrueFalseTotal
if $check_methods_exist->{$name} 4 1 5
174 1 push(@missed_helper_methods, $name);
175 }
176 5 ▶ if(scalar(@missed_helper_methods)) {
Branch: 1 branch
BranchTrueFalseTotal
if (scalar @missed_helper_methods) 1 4 5
177 1 my $msg = join("', '", @missed_helper_methods);
178 1 _croak("Needed helper method(s) '$msg' is/are not defined in attribute-class '$attribute_class'. (Maybe class is not compiled yet?)");
179 }
180
181 4 foreach my $name (@subs) {
182 6 $class->_register_attribute($attribute_class, $name, 0);
183 }
184 3 foreach my $name (@subs) {
185 5 $class->_register_attribute($attribute_class, $name, 1);
186 }
187 3 return 1;
188 }
189 # STATIC hashref
190 0 ▶sub get_registered_subs {
Subroutine get_registered_subs: not called CC=1 SCAR=6.9
Pod documented
191 0 my $class = $_[0];
192
193 0 return $SUBS;
194 }
195 # STATIC void
196 11 ▶sub _register_attribute {
Subroutine _register_attribute: called CC=4 SCAR=14.0
197 11 my $class = $_[0];
198 11 my $attribute_class = $_[1];
199 11 my $name = $_[2];
200 11 my $execute_register = $_[3];
201
202 11 ▶ if($ATT_METHODS->{$name}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($ATT_METHODS->{$name}) 0 11 11
203 0 _croak("Attribute '$name' from attribute-class '$attribute_class' always registered for '$ATT_METHODS->{$name}->{'class'}'", 1);
204 0 return;
205 }
206 11 ▶ if($name !~ m/^[A-Z]/) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($name =~ /^[A-Z]/) 1 10 11
207 1 my $helper_msg = "'" . join("', '", keys(%$HELPER_METHODS)) . "'";
208 1 _croak("Every attribute must start with an uppercase letter (except the helper-method(s) $helper_msg " .
209 "which is/are not an attribute).\n" .
210 "Attribute '$name' from attribute-class '$attribute_class' is not allowed.", 1);
211 0 return;
212 }
213
214 10 ▶ return if(!$execute_register);
Branch: 1 branch
BranchTrueFalseTotal
unless $execute_register 5 5 10
215 {
216
217 4 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
218
219 $ATT_METHODS->{$name} = {
220 class => $attribute_class,
221 5 coderef => *{$attribute_class . '::' . $name}{'CODE'},
222 };
223 }
224 5 return;
225 }
226 # STATIC boolean
227 9 ▶sub export {
Subroutine export: called CC=2 SCAR=6.9
Pod documented
228 9 my $class = $_[0];
229 9 my $export_to_class = $_[1];
230
231 9 ▶ return 0 if($EXPORTED->{$export_to_class});
Branch: 1 branch
BranchTrueFalseTotal
if $EXPORTED->{$export_to_class} 2 7 9
232 7 $EXPORTED->{$export_to_class} = 1;
233 7 $class->_decorate_attribute_handler($export_to_class, "$export_to_class\::MODIFY_CODE_ATTRIBUTES");
234 7 return 1;
235 }
236 # STATIC void
237 3 ▶sub register_helper_method {
Subroutine register_helper_method: called CC=1 SCAR=0.0
Pod documented
238 3 my $class = $_[0];
239 3 my $methodname = $_[1];
240
241 3 $HELPER_METHODS->{$methodname} = 1;
242 3 return;
243 }
244 # STATIC void
245 7 ▶sub _decorate_attribute_handler {
Subroutine _decorate_attribute_handler: called CC=1 SCAR=0.0
246 7 my $class = $_[0];
247 7 my $caller_class = $_[1];
248 7 my $identifier = $_[2];
249
250 4 ▶ no warnings 'redefine';
Subroutine BEGIN: called CC=1 SCAR=0.0
251 4 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
252
253 7 my $old = *{$identifier}{CODE};
254 7 ▶ *{$identifier} = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
255 18 my @unknown_attributes = &_attribute_handler(@_);
256 18 ▶ if($old && @unknown_attributes) {
Branch: 1 branch
BranchTrueFalseTotal
if ($old and @unknown_attributes) 4 14 18
Condition100%3/3
$old and @unknown_attributes
!ll&&!rl&&r
1224
MC/DC100%2/2
$old and @unknown_attributes
$old @unknown_attributes
Truth table100%3/3
A and B
A= $oldB= @unknown_attributes
ABresult
0X0
100
111
257 4 my $caller_class = $_[0];
258 4 my $sub_ref = $_[1];
259
260 4 @_ = ($caller_class, $sub_ref, @unknown_attributes);
261 4 goto &$old;
262 }
263 14 return @unknown_attributes;
264 7 };
265 7 return;
266 }
267 # AUTOMAGIC string()
268 18 ▶sub _attribute_handler {
Subroutine _attribute_handler: called CC=7 SCAR=19.5
269 18 my $caller_class = shift(@_);
270 18 my $sub_ref = shift(@_);
271 18 my @attributes = @_;
272
273 18 ▶ if($LAST_ATTRIBUTE_METHOD && !$LAST_ATTRIBUTE_METHOD->{'resolved'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($LAST_ATTRIBUTE_METHOD and not $LAST_ATTRIBUTE_METHOD->{"resolved"}) 14 4 18
Condition100%3/3
$LAST_ATTRIBUTE_METHOD and not $LAST_ATTRIBUTE_METHOD->{"resolved"}
!ll&&!rl&&r
2214
MC/DC100%2/2
$LAST_ATTRIBUTE_METHOD and not $LAST_ATTRIBUTE_METHOD->{"resolved"}
$LAST_ATTRIBUTE_METHOD not $LAST_ATTRIBUTE_METHOD->{"resolved"}
Truth table100%3/3
A and not(B)
A= $LAST_ATTRIBUTE_METHODB= not $LAST_ATTRIBUTE_METHOD->{"resolved"}
ABresult
0X0
100
111
274 14 my $succes = __PACKAGE__->_resolve_sub($LAST_ATTRIBUTE_METHOD);
275 14 ▶ if(!$LAST_ATTRIBUTE_METHOD->{'executed'}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($LAST_ATTRIBUTE_METHOD->{"executed"}) 14 0 14
276 14 my $success = __PACKAGE__->_exec_attribute($LAST_ATTRIBUTE_METHOD);
277 }
278 }
279 18 my @unknown_attributes = ();
280 18 foreach my $attribute_string (@attributes) {
281 22 my ($name, $data) = __PACKAGE__->_split_attribute($attribute_string);
282 22 my $handler = $ATT_METHODS->{$name};
283 22 ▶ if(!$handler) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($handler) 6 16 22
284 6 push(@unknown_attributes, $attribute_string);
285 6 next;
286 }
287 16 ▶ if($SUBS->{int($sub_ref)}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($$SUBS{int $sub_ref}) 0 16 16
288 0 _croak("Internal failure: subroutine '$sub_ref' allways registered");
289 }
290 $LAST_ATTRIBUTE_METHOD = {
291 16 'attribute' => $name,
292 'handler' => $handler,
293 'sub' => $sub_ref,
294 'class' => $caller_class,
295 'data' => $data,
296 'resolved' => 0,
297 'executed' => 0,
298 };
299 16 $SUBS->{int($sub_ref)} = $LAST_ATTRIBUTE_METHOD;
300 }
301 18 return @unknown_attributes;
302 }
303 # STATIC boolean
304 16 ▶sub _resolve_sub {
Subroutine _resolve_sub: called CC=6 SCAR=18.0
305 16 my $class = $_[0];
306 16 my $sub_data = $_[1];
307
308 16 ▶ return 1 if($sub_data->{'resolved'});
Branch: 1 branch
BranchTrueFalseTotal
if $sub_data->{"resolved"} 0 16 16
309
310 4 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
311
312 16 my $symbols = \%{$sub_data->{'class'} . '::'};
313 16 foreach my $key (keys(%$symbols)) {
314 59 ▶ next if(!$symbols->{$key} || !*{$symbols->{$key}}{CODE});
Branch: 1 branch
BranchTrueFalseTotal
unless $symbols->{$key} and *{$symbols->{$key};}{"CODE"} 32 27 59
Condition66%2/3
$symbols->{$key} and *{$symbols->{$key};}{"CODE"}
!ll&&!rl&&r
03227
MC/DC50%1/2
$symbols->{$key} and *{$symbols->{$key};}{"CODE"}
$symbols->{$key} *{$symbols->{$key};}{"CODE"}
Truth table66%2/3
A and B
A= $symbols->{$key}B= *{$symbols->{$key};}{"CODE"}
ABresult
0X0
100
111
315 27 ▶ if(*{$symbols->{$key}}{CODE} == $sub_data->{'sub'}) {
Branch: 1 branch
BranchTrueFalseTotal
if (*{$symbols->{$key};}{"CODE"} == $sub_data->{"sub"}) 16 11 27
316 16 $sub_data->{'sub_name'} = $key;
317 16 $sub_data->{'resolved'} = 1;
318 16 return 1;
319 }
320 }
321 0 return 0;
322 }
323 # STATIC string()
324 22 ▶sub _split_attribute {
Subroutine _split_attribute: called CC=2 SCAR=7.2
325 22 my $class = $_[0];
326 22 my $string = $_[1];
327
328 22 my ($name, $data) = $string =~ m/^([^\(]*)(?:\((.*)\)|)$/i;
329 22 ▶ if(!$name) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($name) 0 22 22
330 0 _croak("Attribute '$string' is malformed", 1);
331 }
332 22 return ($name, $data);
333 }
334 # STATIC sub
335 16 ▶sub _exec_attribute {
Subroutine _exec_attribute: called CC=3 SCAR=11.3
336 16 my $class = $_[0];
337 16 my $sub_data = $_[1];
338
339 16 ▶ return 1 if($sub_data->{'executed'});
Branch: 1 branch
BranchTrueFalseTotal
if $sub_data->{"executed"} 0 16 16
340 16 my $att_class = $sub_data->{'handler'}->{'class'};
341 16 my $att_method = $sub_data->{'handler'}->{'coderef'};
342
343 16 local $Carp::CarpLevel = $Carp::CarpLevel + 2;
344 16 ▶ if($att_class->$att_method($sub_data)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($att_class->$att_method($sub_data)) 16 0 16
345 16 $sub_data->{'executed'} = 1;
346 16 return 1;
347 }
348 0 return 0;
349 }
350 # STATIC void
351 15 ▶sub run_check {
Subroutine run_check: called CC=5 SCAR=17.0
Pod documented
352 15 my $class = $_[0];
353
354 15 foreach my $ref_no (keys %$SUBS) {
355 59 my $entry = $SUBS->{$ref_no};
356 59 ▶ if(!$entry->{'executed'}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($entry->{"executed"}) 2 57 59
357 2 ▶ if(!__PACKAGE__->_resolve_sub($entry)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (__PACKAGE__->_resolve_sub($entry)) 0 2 2
358 0 _croak("Internal error: can't resolve sub '$entry->{'sub'}'");
359 }
360 2 ▶ if(!__PACKAGE__->_exec_attribute($entry)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (__PACKAGE__->_exec_attribute($entry)) 0 2 2
361 0 _croak("Internal error: can't execute attribute '$entry->{'attribute'}' for sub '$entry->{'class'}->$entry->{'sub_name'}'");
362 }
363 }
364 }
365 15 return;
366 }
367
368 4 ▶no warnings 'void'; # avoid 'Too late to run CHECK/INIT block'
Subroutine BEGIN: called CC=1 SCAR=0.0
369
370 # AUTOMAGIC
371 4 ▶CHECK {
Subroutine CHECK: called CC=1 SCAR=0.0
372 4 __PACKAGE__->run_check();
373 }
374 # AUTOMAGIC
375 4 ▶END {
Subroutine END: called CC=1 SCAR=0.0
376 4 __PACKAGE__->run_check();
377 }
378 4 1;
« Class/Attributes.pm ↑ Summary Class/Implements.pm »