File Coverage

blib/lib/Devel/Events/Generator/LineTrace.pm
Criterion Covered Total %
statement 2 4 50.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 4 6 66.6


line stmt bran cond sub pod time code
1             #!/usr/bin/perl
2              
3 2     2   26662 BEGIN { $^P |= 0x02 }
4              
5             package Devel::Events::Generator::LineTrace;
6 2     2   938 use Moose;
  0            
  0            
7              
8             with qw/Devel::Events::Generator/;
9              
10             use Scalar::Util qw/weaken/;
11              
12             my $SINGLETON;
13              
14             sub DB::DB {
15             if ( $SINGLETON ) {
16             my ( $package, $file, $line ) = caller;
17             return if $package =~ /^Devel::Events::/;
18             $SINGLETON->line( package => $package, file => $file, line => $line );
19             }
20             }
21              
22             sub enable {
23             my $self = shift;
24             $SINGLETON = $self;
25             weaken($SINGLETON);
26             }
27              
28             sub disable {
29             $SINGLETON = undef;
30             }
31              
32             sub line {
33             my ( $self, @args ) = @_;
34             $self->send_event( executing_line => @args );
35             }
36              
37             __PACKAGE__;
38              
39             __END__
40              
41             =pod
42              
43             =head1 NAME
44              
45             Devel::Events::Generator::LineTrace - generate C<executing_line> events using
46             the perl debugger api.
47              
48             =head1 SYNOPSIS
49              
50             my $g = Devel::Events::Generator::LineTrace->new( handler => $h );
51              
52             $g->enable();
53              
54             # every line of code will fire an event until
55              
56             $g->disable();
57              
58             =head1 DESCRIPTION
59              
60             This L<Devel::Events> generator will fire line tracing events using C<DB::DB>,
61             a perl debugger hook.
62              
63             Only one instance may be enabled at a given time. Use
64             L<Devel::Events::Handler::Multiplex> to deliver events to multiple handlers.
65              
66             =head1 EVENTS
67              
68             =over 4
69              
70             =item executing_line
71              
72             When the generator is enabled, this event will fire for every line of code just
73             before it is executed.
74              
75             Lines in a package starting with C<Devel::Events::> will not be reported.
76              
77             =over 4
78              
79             =item package
80              
81             The package the line is in.
82              
83             =item file
84              
85             The file of the line being executed.
86              
87             =item line
88              
89             The line number of the line being executed.
90              
91             =back
92              
93             =back
94              
95             =head1 METHODS
96              
97             =over 4
98              
99             =item enable
100              
101             Enable this generator instance, disabling any other instance of
102             L<Devel::Events::Generator::LineTrace>.
103              
104             =item disable
105              
106             Stop firing events.
107              
108             =item line
109              
110             Called by C<DB::DB>. Used to generate the event.
111              
112             =back
113              
114             =head1 CAVEATS
115              
116             Apparently this must be run under C<perl -d>. This is very strange, since
117             L<Devel::Events::Generator::SubTrace> doesn't need the C<-d> flag set.
118              
119             The L<Enbugger> module can help overcome this limitation.
120              
121             =head1 SEE ALSO
122              
123             L<perldebguts>, L<Devel::LineTrace>, L<DB>, L<Devel::ebug>, L<perl5db.pl>
124              
125             =cut