Mojo/Base.pm

filter: Statementstmt 96.4% 137 / 142 Branchbran 93.5% 101 / 108 Conditioncond 66.6% 8 / 12 MC/DCmcdc 28.5% 2 / 7 Subroutinesub 96.8% 31 / 32 Podpod 100% 4 / 4 totaltotal 92.7% 283 / 305 CC 219 SCAR 14.0
CC
219
Cov
94%
attr
17.0
import
14.4
__ANON__
5.0
CRAP 4.1
« Mojo/Headers.pm ↑ Summary Test/Mojo.pm »
1 package Mojo::Base;
2  
3 73 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 73 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 73 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 73 ▶use feature ':5.16';
Subroutine BEGIN: called CC=1 SCAR=0.0
7 73 ▶use mro;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 # No imports because we get subclassed, a lot!
10 73 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
11 73 ▶use Scalar::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
12 73 ▶use Mojo::BaseUtil ();
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 # Role support requires Role::Tiny 2.000001+
15 73 ▶use constant ROLES => !!(eval { require Role::Tiny; Role::Tiny->VERSION('2.000001'); 1 });
Subroutine BEGIN: called CC=1 SCAR=0.0
16  
17 # async/await support requires Future::AsyncAwait 0.52+
18 73 ▶use constant ASYNC => $ENV{MOJO_NO_ASYNC}
Subroutine BEGIN: called CC=2 SCAR=7.9
19 ? 0
20 0 ▶ : !!(eval { require Future::AsyncAwait; Future::AsyncAwait->VERSION('0.52'); 1 });
Branch: 1 branch
BranchTrueFalseTotal
$ENV{'MOJO_NO_ASYNC'} ? : 0 73 73
21  
22 # Protect subclasses using AUTOLOAD
23 0 ▶sub DESTROY { }
Subroutine DESTROY: not called CC=1 SCAR=0.0
24  
25 4834 ▶sub attr {
Subroutine attr: called CC=17 SCAR=28.3
Pod documented
26 4834 my ($self, $attrs, $value, %kv) = @_;
27 4834 ▶ return unless (my $class = ref $self || $self) && $attrs;
Branch: 1 branch
BranchTrueFalseTotal
unless my $class = ref $self || $self and $attrs 0 4834 4834
Condition50%3/6
my $class = ref $self || $self and $attrs
!ll&&!rl&&r
004834
ref $self || $self
l!l&&r!l&&!r
248320
MC/DC0%0/3
my $class = ref $self || $self and $attrs
ref $self $self $attrs
Truth table40%2/5
A || B and C
A= ref $selfB= $selfC= $attrs
ABCresult
00X0
1X00
0100
1X11
0111
28  
29 4834 ▶ Carp::croak 'Default has to be a code reference or constant value' if ref $value && ref $value ne 'CODE';
Branch: 1 branch
BranchTrueFalseTotal
if ref $value and ref $value ne "CODE" 1 4833 4834
Condition100%3/3
ref $value and ref $value ne "CODE"
!ll&&!rl&&r
206827651
MC/DC100%2/2
ref $value and ref $value ne "CODE"
ref $value ref $value ne "CODE"
Truth table100%3/3
A and B
A= ref $valueB= ref $value ne "CODE"
ABresult
0X0
100
111
30 4833 ▶ Carp::croak 'Unsupported attribute option' if grep { $_ ne 'weak' } keys %kv;
Branch: 1 branch
BranchTrueFalseTotal
if grep {$_ ne "weak";} keys %kv 1 4832 4833
31  
32 # Weaken
33 4832 ▶ if ($kv{weak}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($kv{"weak"}) 265 4567 4832
34 265 state %weak_names;
35 265 ▶ unless ($weak_names{$class}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($weak_names{$class}) 263 2 265
36 263 my $names = $weak_names{$class} = [];
37 80 ▶ my $sub = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
38 80 my $self = shift->next::method(@_);
39 80 ▶ ref $self->{$_} and Scalar::Util::weaken $self->{$_} for @$names;
Branch: 1 branch
BranchTrueFalseTotal
ref $self->{$_} and builtin::weaken($self->{$_}) 31 67 98
40 80 return $self;
41 263 };
42 263 Mojo::BaseUtil::monkey_patch(my $base = $class . '::_Base', 'new', $sub);
43 73 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
44 263 unshift @{"${class}::ISA"}, $base;
45 }
46 265 ▶ push @{$weak_names{$class}}, ref $attrs eq 'ARRAY' ? @$attrs : $attrs;
Branch: 1 branch
BranchTrueFalseTotal
ref $attrs eq 'ARRAY' ? : 22 243 265
47 }
48  
49 4832 ▶ for my $attr (@{ref $attrs eq 'ARRAY' ? $attrs : [$attrs]}) {
Branch: 1 branch
BranchTrueFalseTotal
ref $attrs eq 'ARRAY' ? : 760 4072 4832
50 6423 ▶ Carp::croak qq{Attribute "$attr" invalid} unless $attr =~ /^[a-zA-Z_]\w*$/;
Branch: 1 branch
BranchTrueFalseTotal
unless $attr =~ /^[a-zA-Z_]\w*$/u 1 6422 6423
51  
52 # Very performance-sensitive code with lots of micro-optimizations
53 6422 my $sub;
54 6422 ▶ if ($kv{weak}) {
Branch: 3 branches
BranchTrueFalseTotal
if ($kv{'weak'}) { } 286 6136 6422
elsif (ref $value) { } 2803 3333 6136
elsif (defined $value) { } 1369 1964 3333
55 286 ▶ if (ref $value) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $value) { } 221 65 286
56 18924 ▶ $sub = sub {
Subroutine __ANON__: called CC=5 SCAR=16.1
57 return
58 exists $_[0]{$attr}
59 ? $_[0]{$attr}
60 18924 ▶ : (ref($_[0]{$attr} = $value->($_[0])) && Scalar::Util::weaken($_[0]{$attr}), $_[0]{$attr})
Branch: 3 branches
BranchTrueFalseTotal
if @_ == 1 18866 58 18924
exists $_[0]{$attr} ? : 18855 11 18866
ref($_[0]{$attr} = &$value($_[0])) and builtin::weaken($_[0]{$attr}) 11 0 11
61 if @_ == 1;
62 58 ▶ ref($_[0]{$attr} = $_[1]) and Scalar::Util::weaken($_[0]{$attr});
Branch: 1 branch
BranchTrueFalseTotal
ref($_[0]{$attr} = $_[1]) and builtin::weaken($_[0]{$attr}) 57 1 58
63 58 $_[0];
64 221 };
65 }
66 else {
67 139 ▶ $sub = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
Subroutine four: called CC=3 SCAR=11.0
68 139 ▶ return $_[0]{$attr} if @_ == 1;
Branch: 2 branches
BranchTrueFalseTotal
if @_ == 1 138 1 139
if @_ == 1 21942 9834 31776
69 1 ▶ ref($_[0]{$attr} = $_[1]) and Scalar::Util::weaken($_[0]{$attr});
Branch: 2 branches
BranchTrueFalseTotal
ref($_[0]{$attr} = $_[1]) and builtin::weaken($_[0]{$attr}) 1 0 1
ref($_[0]{$attr} = $_[1]) and builtin::weaken($_[0]{$attr}) 24243 5847 30090
70 1 $_[0];
71 65 };
72 }
73 }
74 elsif (ref $value) {
75 727 ▶ $sub = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
Subroutine handle: called CC=3 SCAR=11.0
76 727 ▶ return exists $_[0]{$attr} ? $_[0]{$attr} : ($_[0]{$attr} = $value->($_[0])) if @_ == 1;
Branch: 7 branches
BranchTrueFalseTotal
if @_ == 1 633 94 727
exists $_[0]{$attr} ? : 545 88 633
if @_ == 1 108510 10093 118603
exists $_[0]{$attr} ? : 90893 14585 105478
if @_ == 1 11352 926 12278
exists $_[0]{$attr} ? : 2016 313 2329
if @_ == 1 1422 507 1929
77 94 $_[0]{$attr} = $_[1];
78 94 $_[0];
79 2803 };
80 }
81 elsif (defined $value) {
82 885 ▶ $sub = sub {
Subroutine start_range: called CC=3 SCAR=11.0
Subroutine __ANON__: called CC=3 SCAR=11.0
83 885 ▶ return exists $_[0]{$attr} ? $_[0]{$attr} : ($_[0]{$attr} = $value) if @_ == 1;
Branch: 4 branches
BranchTrueFalseTotal
if @_ == 1 802 83 885
exists $_[0]{$attr} ? : 592 210 802
if @_ == 1 6700 3103 9803
exists $_[0]{$attr} ? : 1651 586 2237
84 83 $_[0]{$attr} = $_[1];
85 83 $_[0];
86 1369 };
87 }
88 else {
89 1964 ▶ $sub = sub { return $_[0]{$attr} if @_ == 1; $_[0]{$attr} = $_[1]; $_[0] };
Subroutine path: called CC=2 SCAR=6.9
Subroutine __ANON__: called CC=2 SCAR=6.9
Subroutine mojo: called CC=2 SCAR=6.9
Branch: 4 branches
BranchTrueFalseTotal
if @_ == 1 6566 3000 9566
if @_ == 1 35154 2779 37933
if @_ == 1 12278 2607 14885
if @_ == 1 1125 891 2016
90 }
91 6422 Mojo::BaseUtil::monkey_patch($class, $attr, $sub);
92 }
93 }
94  
95 5006 ▶sub import {
Subroutine import: called CC=14 SCAR=26.6
96 5006 my ($class, $caller) = (shift, caller);
97 5006 ▶ return unless my @flags = @_;
Branch: 1 branch
BranchTrueFalseTotal
unless my(@flags) = 2327 2679 5006
98  
99 # Mojo modules are strict!
100 2679 $_->import for qw(strict warnings utf8);
101 2679 feature->import(':5.16');
102  
103 2679 ▶ while (my $flag = shift @flags) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $flag = shift @flags) 3624 2678 6302
104  
105 # Base
106 3624 ▶ if ($flag eq '-base') { push @flags, $class }
Branch: 6 branches
BranchTrueFalseTotal
if ($flag eq '-base') { } 941 2683 3624
elsif ($flag eq '-role') { } 2 2681 2683
elsif ($flag eq '-async_await') { } 0 2681 2681
elsif ($flag eq '-signatures') { } 3 2678 2681
elsif (not $flag =~ /^-/u) { } 1969 709 2678
elsif ($flag ne '-strict') { } 1 708 709
107  
108 # Role
109 elsif ($flag eq '-role') {
110 2 Carp::croak 'Role::Tiny 2.000001+ is required for roles' unless ROLES;
111 2 ▶ Mojo::BaseUtil::monkey_patch($caller, 'has', sub { attr($caller, @_) });
Subroutine __ANON__: called CC=1 SCAR=0.0
112 2 ▶ eval "package $caller; use Role::Tiny; 1" or die $@;
Branch: 1 branch
BranchTrueFalseTotal
eval "package $caller; use Role::Tiny; 1" or die $@ 2 0 2
113 }
114  
115 # async/await
116 elsif ($flag eq '-async_await') {
117 0 Carp::croak 'Future::AsyncAwait 0.52+ is required for async/await' unless ASYNC;
118 0 require Mojo::Promise;
119 0 Future::AsyncAwait->import_into($caller, future_class => 'Mojo::Promise');
120 }
121  
122 # Signatures (Perl 5.20+)
123 elsif ($flag eq '-signatures') {
124 3 ▶ Carp::croak 'Subroutine signatures require Perl 5.20+' if $] < 5.020;
Branch: 1 branch
BranchTrueFalseTotal
if $] < "5.02" 0 3 3
125 3 require experimental;
126 3 experimental->import($_) for qw(signatures postderef);
127 }
128  
129 # Module
130 elsif ($flag !~ /^-/) {
131 73 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
132 1969 ▶ require(Mojo::BaseUtil::class_to_path($flag)) unless $flag->can('new');
Branch: 1 branch
BranchTrueFalseTotal
unless $flag->can("new") 314 1655 1969
133 1969 push @{"${caller}::ISA"}, $flag;
134 1969 ▶ Mojo::BaseUtil::monkey_patch($caller, 'has', sub { attr($caller, @_) });
Subroutine has: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
135 }
136  
137 1 elsif ($flag ne '-strict') { Carp::croak "Unsupported flag: $flag" }
138 }
139 }
140  
141 20426 ▶sub new {
Subroutine new: called CC=4 SCAR=13.9
Pod documented
142 20426 my $class = shift;
143 20426 ▶ bless @_ ? @_ > 1 ? {@_} : {%{$_[0]}} : {}, ref $class || $class;
Branch: 2 branches
BranchTrueFalseTotal
@_ ? : 3705 16721 20426
@_ > 1 ? : 3620 85 3705
Condition66%2/3
ref $class || $class
l!l&&r!l&&!r
2129182970
MC/DC0%0/2
ref $class || $class
ref $class $class
Truth table66%2/3
A || B
A= ref $classB= $class
ABresult
1X1
011
000
144 }
145  
146 22 ▶sub tap {
Subroutine tap: called CC=2 SCAR=6.9
Pod documented
147 22 my ($self, $cb) = (shift, shift);
148 22 $_->$cb(@_) for $self;
149 22 return $self;
150 }
151  
152 13 ▶sub with_roles {
Subroutine with_roles: called CC=5 SCAR=16.1
Pod documented
153 13 Carp::croak 'Role::Tiny 2.000001+ is required for roles' unless ROLES;
154 13 my ($self, @roles) = @_;
155 13 ▶ return $self unless @roles;
Branch: 1 branch
BranchTrueFalseTotal
unless @roles 2 11 13
156  
157 11 ▶ return Role::Tiny->create_class_with_roles($self, map { /^\+(.+)$/ ? "${self}::Role::$1" : $_ } @roles)
Branch: 2 branches
BranchTrueFalseTotal
unless my $class = builtin::blessed($self) 10 1 11
/^\+(.+)$/u ? : 5 9 14
158 unless my $class = Scalar::Util::blessed $self;
159  
160 1 ▶ return Role::Tiny->apply_roles_to_object($self, map { /^\+(.+)$/ ? "${class}::Role::$1" : $_ } @roles);
Branch: 1 branch
BranchTrueFalseTotal
/^\+(.+)$/u ? : 1 1 2
161 }
162  
163 73 1;
164  
165 =encoding utf8
166  
167 =head1 NAME
168  
169 Mojo::Base - Minimal base class for Mojo projects
170  
171 =head1 SYNOPSIS
172  
173 package Cat;
174 use Mojo::Base -base;
175  
176 has name => 'Nyan';
177 has ['age', 'weight'] => 4;
178  
179 package Tiger;
180 use Mojo::Base 'Cat';
181  
182 has friend => sub { Cat->new };
183 has stripes => 42;
184  
185 package main;
186 use Mojo::Base -strict;
187  
188 my $mew = Cat->new(name => 'Longcat');
189 say $mew->age;
190 say $mew->age(3)->weight(5)->age;
191  
192 my $rawr = Tiger->new(stripes => 38, weight => 250);
193 say $rawr->tap(sub { $_->friend->name('Tacgnol') })->weight;
194  
195 =head1 DESCRIPTION
196  
197 L<Mojo::Base> is a simple base class for L<Mojo> projects with fluent interfaces.
198  
199 # Automatically enables "strict", "warnings", "utf8" and Perl 5.16 features
200 use Mojo::Base -strict;
201 use Mojo::Base -base;
202 use Mojo::Base 'SomeBaseClass';
203 use Mojo::Base -role;
204  
205 All four forms save a lot of typing. Note that role support depends on L<Role::Tiny> (2.000001+).
206  
207 # use Mojo::Base -strict;
208 use strict;
209 use warnings;
210 use utf8;
211 use feature ':5.16';
212 use mro;
213  
214 # use Mojo::Base -base;
215 use strict;
216 use warnings;
217 use utf8;
218 use feature ':5.16';
219 use mro;
220 push @ISA, 'Mojo::Base';
221 sub has { Mojo::Base::attr(__PACKAGE__, @_) }
222  
223 # use Mojo::Base 'SomeBaseClass';
224 use strict;
225 use warnings;
226 use utf8;
227 use feature ':5.16';
228 use mro;
229 require SomeBaseClass;
230 push @ISA, 'SomeBaseClass';
231 sub has { Mojo::Base::attr(__PACKAGE__, @_) }
232  
233 # use Mojo::Base -role;
234 use strict;
235 use warnings;
236 use utf8;
237 use feature ':5.16';
238 use mro;
239 use Role::Tiny;
240 sub has { Mojo::Base::attr(__PACKAGE__, @_) }
241  
242 On Perl 5.20+ you can also use the C<-signatures> flag with all four forms and enable support for L<subroutine
243 signatures|perlsub/"Signatures">.
244  
245 # Also enable signatures
246 use Mojo::Base -strict, -signatures;
247 use Mojo::Base -base, -signatures;
248 use Mojo::Base 'SomeBaseClass', -signatures;
249 use Mojo::Base -role, -signatures;
250  
251 If you have L<Future::AsyncAwait> 0.52+ installed you can also use the C<-async_await> flag to activate the C<async>
252 and C<await> keywords to deal much more efficiently with promises.
253  
254 # Also enable async/await
255 use Mojo::Base -strict, -async_await;
256 use Mojo::Base -base, -signatures, -async_await;
257  
258 This will also disable experimental warnings on versions of Perl where this feature was still experimental.
259  
260 =head1 FLUENT INTERFACES
261  
262 Fluent interfaces are a way to design object-oriented APIs around method chaining to create domain-specific languages,
263 with the goal of making the readability of the source code close to written prose.
264  
265 package Duck;
266 use Mojo::Base -base, -signatures;
267  
268 has 'name';
269  
270 sub quack ($self) {
271 my $name = $self->name;
272 say "$name: Quack!"
273 }
274  
275 L<Mojo::Base> will help you with this by having all attribute accessors created with L</"has"> (or L</"attr">) return
276 their invocant (C<$self>) whenever they are used to assign a new attribute value.
277  
278 Duck->new->name('Donald')->quack;
279  
280 In this case the C<name> attribute accessor is called on the object created by C<Duck-E<gt>new>. It assigns a new
281 attribute value and then returns the C<Duck> object, so the C<quack> method can be called on it afterwards. These
282 method chains can continue until one of the methods called does not return the C<Duck> object.
283  
284 =head1 FUNCTIONS
285  
286 L<Mojo::Base> implements the following functions, which can be imported with the C<-base> flag or by setting a base
287 class.
288  
289 =head2 has
290  
291 has 'name';
292 has ['name1', 'name2', 'name3'];
293 has name => 'foo';
294 has name => sub {...};
295 has ['name1', 'name2', 'name3'] => 'foo';
296 has ['name1', 'name2', 'name3'] => sub {...};
297 has name => sub {...}, weak => 1;
298 has name => undef, weak => 1;
299 has ['name1', 'name2', 'name3'] => sub {...}, weak => 1;
300  
301 Create attributes for hash-based objects, just like the L</"attr"> method.
302  
303 =head1 METHODS
304  
305 L<Mojo::Base> implements the following methods.
306  
307 =head2 attr
308  
309 $object->attr('name');
310 SubClass->attr('name');
311 SubClass->attr(['name1', 'name2', 'name3']);
312 SubClass->attr(name => 'foo');
313 SubClass->attr(name => sub {...});
314 SubClass->attr(['name1', 'name2', 'name3'] => 'foo');
315 SubClass->attr(['name1', 'name2', 'name3'] => sub {...});
316 SubClass->attr(name => sub {...}, weak => 1);
317 SubClass->attr(name => undef, weak => 1);
318 SubClass->attr(['name1', 'name2', 'name3'] => sub {...}, weak => 1);
319  
320 Create attribute accessors for hash-based objects, an array reference can be used to create more than one at a time.
321 Pass an optional second argument to set a default value, it should be a constant or a callback. The callback will be
322 executed at accessor read time if there's no set value, and gets passed the current instance of the object as first
323 argument. Accessors can be chained, that means they return their invocant when they are called with an argument.
324  
325 These options are currently available:
326  
327 =over 2
328  
329 =item weak
330  
331 weak => $bool
332  
333 Weaken attribute reference to avoid L<circular references|perlref/"Circular-References"> and memory leaks.
334  
335 =back
336  
337 =head2 new
338  
339 my $object = SubClass->new;
340 my $object = SubClass->new(name => 'value');
341 my $object = SubClass->new({name => 'value'});
342  
343 This base class provides a basic constructor for hash-based objects. You can pass it either a hash or a hash reference
344 with attribute values.
345  
346 =head2 tap
347  
348 $object = $object->tap(sub {...});
349 $object = $object->tap('some_method');
350 $object = $object->tap('some_method', @args);
351  
352 Tap into a method chain to perform operations on an object within the chain (also known as a K combinator or Kestrel).
353 The object will be the first argument passed to the callback, and is also available as C<$_>. The callback's return
354 value will be ignored; instead, the object (the callback's first argument) will be the return value. In this way,
355 arbitrary code can be used within (i.e., spliced or tapped into) a chained set of object method calls.
356  
357 # Longer version
358 $object = $object->tap(sub { $_->some_method(@args) });
359  
360 # Inject side effects into a method chain
361 $object->foo('A')->tap(sub { say $_->foo })->foo('B');
362  
363 =head2 with_roles
364  
365 my $new_class = SubClass->with_roles('SubClass::Role::One');
366 my $new_class = SubClass->with_roles('+One', '+Two');
367 $object = $object->with_roles('+One', '+Two');
368  
369 Create a new class with one or more L<Role::Tiny> roles. If called on a class returns the new class, or if called on an
370 object reblesses the object into the new class. For roles following the naming scheme C<MyClass::Role::RoleName> you
371 can use the shorthand C<+RoleName>. Note that role support depends on L<Role::Tiny> (2.000001+).
372  
373 # Create a new class with the role "SubClass::Role::Foo" and instantiate it
374 my $new_class = SubClass->with_roles('+Foo');
375 my $object = $new_class->new;
376  
377 =head1 SEE ALSO
378  
379 L<Mojolicious>, L<Mojolicious::Guides>, L<https://mojolicious.org>.
380  
381 =cut
« Mojo/Headers.pm ↑ Summary Test/Mojo.pm »