blib/lib/MooX/EventHandler.pm untested

filter: Statementstmt 0.0% 0 / 46 Branchbran 0.0% 0 / 16 Conditioncond 0.0% 0 / 16 MC/DCmcdc 0.0% 0 / 10 Subroutinesub 0.0% 0 / 3 Podpod 0.0% 0 / 1 totaltotal 0.0% 0 / 92 CC 9 SCAR 43.0
CC
9
Cov
0%
import
90.0
BEGIN
2.0
BEGIN
2.0
CRAP 74.0
1 package MooX::EventHandler;
2  
3 our $VERSION = '0.000';
4 $VERSION = eval $VERSION;
5  
6 use Moo ();
7 use strictures 2;
8  
9 our %TRACKED_EVENTS;
10 our %TRACKED_EVENTS_TRACKER;
11  
12 sub import {
13 my $class = shift;
14 my %extra = @_;
15 my $target = caller;
16 my $has = $target->can('has');
17  
18 $TRACKED_EVENTS{$target} //= [];
19 Moo::_install_tracked $target, has_event => sub {
20 if (exists $extra{-tracked} and not $TRACKED_EVENTS_TRACKER{$target}) {
21 $TRACKED_EVENTS_TRACKER{$target} = 1;
22 $has->($extra{-tracked} =>
23 is => 'ro',
24 default => sub { %TRACKED_EVENTS{$target} },
25 );
26 }
27 my @all_names = ref $_[0] eq 'ARRAY' ? @{ shift() } : ( shift );
28 my %proto = @_; # Should take advantage of Moo's own error handling here
29 $proto{is} //= 'lazy';
30 for my $event (@all_names) {
31 my $attribute = "_${event}_event";
32 my %spec = %proto;
33 $spec{init_arg} = $event unless exists $spec{init_arg};
34 if ($spec{is} eq 'lazy' or $spec{lazy}) {
35 my $default_name = "_build_$event";
36 my $can = ref $spec{builder} eq 'CODE'
37 ? delete $spec{builder}
38 : $target->can($default_name)
39 // ($spec{required}
40 ? sub { sub { die "Unimplemented event handler $event" } }
41 : sub { sub {} });
42 $spec{builder} //= $default_name;
43 Moo::_install_coderef("${target}::$spec{builder}" => sub {
44 my $self = shift;
45 $can = $can->();
46 sub { $self->$can(@_) }
47 });
48 }
49 $has->($attribute => %spec);
50 Moo::_install_coderef("${target}::${event}" =>
51 sub { $_[0]->$attribute->(@_[1..$#_]) })
52 unless $target->can($event);
53 push @{$TRACKED_EVENTS{$target}}, $event if exists $extra{-tracked};
54 }
55 };
56 }
57  
58 1;
59  
60 =head1 NAME
61  
62 MooX::EventHandler - Use Moo modules with event handlers.
63  
64 =head1 SYNOPSIS
65  
66 package Daisy;
67 use Moo;
68 use MooX::EventHandler;
69  
70 has_event 'on_abattoir';
71  
72 sub on_abattoir { die } # Cannot be replaced by users
73  
74 has_event 'on_new_grass' => builder => sub { sub { # Yes, two
75 my $self = shift;
76 $self->eat();
77 }};
78  
79 has_event 'on_bull' => builder => 'make_calf';
80  
81 sub make_calf { sub { # Two again
82 Daisy->new();
83 }}
84  
85 =head1 DESCRIPTION
86  
87 Exports a function C<has_event> which creates an attribute with
88 settings useful for writing event-driven code.
89  
90 Specifically:
91  
92 =over
93  
94 =item * Event attributes are lazy by default.
95  
96 =item * The attribute is named C<_${event}_event> so that C<$event()>
97 calls the event handler rather than returning the coderef which
98 implements it. The C<init_arg> remains C<$event> and the default
99 builder C<_build_$event>.
100  
101 =item * C<required> now means that the default event handler will die,
102 not that a handler must be passed to the constructor.
103  
104 =item * (Optionally) Another attribute is added to the class which
105 returns a listref of this object's event.
106  
107 =back
108  
109 =head1 BUGS
110  
111 =over
112  
113 =item Tracked events do not work correctly with inheritence or roles.
114  
115 =item Double-layered subs are ugly.
116  
117 =item This was written primarily for use with L<IO::Async> and has not
118 been tested with other event libraries.
119  
120 =item Overriding/updating attribute options in subclasses has no
121 explicit support and probably doesn't work.
122  
123 =item There are no tests.
124  
125 =back
126  
127 =head1 EVENT ATTRIBUTES
128  
129 Event attributes are simply regular L<Moo> attributes with defaults
130 useful for writing event-driven code and as such can be treated like
131 any other attribute, but see L</BUGS>.
132  
133 There are 3 different ways to assign handlers to an event.
134  
135 =over
136  
137 =item A lazy builder.
138  
139 A coderef can be returned from an event attribute's C<builder> or
140 C<default> in the usual way.
141  
142 =item Passed to the constructor.
143  
144 Coderefs can be passed to the constructor with the name of the event
145 just like any other attribute.
146  
147 =item Directly in the object.
148  
149 The event handler can be installed as a regular method in the
150 class. This B<overrides> the ability to pass event handlers to the
151 constructor.
152  
153 =back
154  
155 =head1 EVENT TRACKING
156  
157 If MooX::EventHandler is imported with the C<-tracked> option and the
158 name of an attribute, that attribute is created and set up to return a
159 list of all of the object's events. This feature is buggy and does not
160 work properly with inheritence.
161  
162 package Foo;
163 use Moo;
164 use MooX::EventHandler -tracked => 'all_events';
165 has_event 'on_foo';
166 has_event 'on_bar';
167  
168 # Foo->new->all_events will now return ['on_foo', 'on_bar'];
169  
170 =head1 SEE ALSO
171  
172 L<Moo>
173  
174 =head1 AUTHOR
175  
176 Matthew King <chohag@jtan.com>
177  
178 =cut