blib/lib/Parse/Crontab/English.pm

filter: Statementstmt 97.2% 141 / 145 Branchbran 87.0% 47 / 54 Conditioncond 80.0% 4 / 5 MC/DCmcdc 33.3% 1 / 3 Subroutinesub 100% 9 / 9 Podpod 100% 4 / 4 totaltotal 93.6% 206 / 220 CC 35 SCAR 27.8
CC
35
Cov
94%
load
24.2
determine_ranges
10.0
new
2.0
CRAP 16.1
↑ Summary
1 package Parse::Crontab::English;
2  
3 2 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 2 ▶use Parse::Crontab;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 2 ▶use List::Util qw/uniq/;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 =head1 NAME
11  
12 Parse::Crontab::English - Generate useful English documentation on how often a crontab command runs.
13  
14 =head1 VERSION
15  
16 Version 0.01
17  
18 =cut
19  
20 2 our $VERSION = '0.01';
21  
22  
23 =head1 SYNOPSIS
24  
25 Parses the supplied crontab (using Parse::Crontab) and then examines the data
26 in order to create a comprehensive English explanation of how often a command
27 runs.
28  
29 Perhaps a little code snippet.
30  
31 use Parse::Crontab::English;
32  
33 my $foo = Parse::Crontab::English->new( file => 'crontab.lst');
34  
35 We now have the full details of each relevant crontab line in $foo->{ base },
36 and a summary in $foo->{ summary } as a HoA (hash of arrays). The hash key is
37 the command line (the last entry in the line from crontab), and the detail
38 consists of the months, days of the month, days of the week, a complete list of
39 the times (hours and minutes) of each run, and a summary of the same times.
40  
41 Because a command may have multiple entries (perhaps a weekday run and a
42 different weekend run), the result is held in an array.
43  
44 So, for the crontab line
45  
46 15 9-17 * * 0-2,4,6 cd /home/xyz/extra && ./several_days.sh >sev.out 2>sev.err
47  
48 the detail for 'cd /home/xyz/extra && ./several_days.sh >sev.out 2>sev.err'
49 will contain a single element, with the following hash values:
50  
51 'month_desc' => 'every month'
52 'day_desc' => 'every day of the month'
53 'dow_desc' => 'Sunday to Tuesday, Thursday, and Saturday'
54 'hours_minutes' => 'at the hours 9h00, 10h00, 11h00, 12h00, 13h00, 14h00, 15h00, 16h00, and 17h00, at :15 after the hour'
55 'hm_desc' => '9 times daily, starting at 9h15, and ending at 17h15'
56  
57 The example script 'explain_crontab' shows the following result for this line:
58  
59 Command line: cd /home/xyz/extra && ./several_days.sh >sev.out 2>sev.err
60 --> Detail (line 1):
61 --> Description of Days of the week: the following 5 days of the week: Sunday to Tuesday, Thursday, and Saturday
62 --> Description of Hours and Minutes: 9 times daily, starting at 9h15, and ending at 17h15
63 --> Detail of Hours and Minutes: at the hours 9h00, 10h00, 11h00, 12h00, 13h00, 14h00, 15h00, 16h00, and 17h00, at :15 after the hour
64  
65 Since both 'every day of the month' and 'every month' are the defaults, the
66 script omits those comments from the summary.
67  
68 =head1 SUBROUTINES/METHODS
69  
70 =head2 C<new>
71  
72 my $foo = Parse::Crontab::English->new( file => $filename);
73  
74 Loads the crontab definition contained in the named file, and generates a
75 summary of each line.
76  
77 The result is a hash whose key is the command line executed by cron; since
78 command lines can be duplciated, the value is an AoH, with the hash containing
79 the base values from Parse::Crontab and the summary containing English
80 descriptions of when the job will run.
81  
82 =head2 C<load>
83  
84 Internal routine, called from C<new>.
85  
86 =head2 C<hm>
87  
88 Internal routine, called from C<load> to format hour (and possibly) minutes
89 into a nice output string.
90  
91 =head2 C<determine_ranges>
92  
93 Internal routine, called from C<load> to build an AoA containing the value
94 ranges.
95  
96 =head2 Values straight from Parse::Crontab:
97  
98 =head3 C<mon_range>
99  
100 The sorted list of months that the job will run. Values range from 1 to 12.
101  
102 =head3 C<day_range>
103  
104 The sorted list of days of the month that the job will run. Values range from 1
105 to 31.
106  
107 =head3 C<dow_range>
108  
109 The sorted list of days of the week that the job will run. Values run from 0 to
110 7, and there may be both 0 and 7 (Sunday).
111  
112 =head3 C<hour_range>
113  
114 Ths sorted list of hours that the job will run. Values run from 0 to 23.
115  
116 =head3 C<min_range>
117  
118 The sorted list of minutes that the job will run. Values run from 0 to 59.
119  
120 =head2 Values from Parse::Crontab::English
121  
122 =head3 C<mon_desc>
123  
124 The sorted list of months that the job will run.
125 This will be 'every month', 'just the month of xx', or a list of months.
126  
127 =head3 C<day_desc>
128  
129 The sorted list of days of the month that the job will run.
130 This will be 'every day of the month', 'just on day xx', or a list of days.
131  
132 =head3 C<dow_desc>
133  
134 This is the sorted list of days of the week that the job will run.
135 This will be 'every day of the week', 'just on xx', or a list of week days.
136  
137 =head3 C<hours_minutes>
138  
139 If a job runs every minute, this contains 'every minute, for xx hours, from yy
140 to zz', where xx is the number of hours, yy is the first time, and zz is the
141 last time the job runs.
142  
143 Otherwise, this contains 'at the hours C<list of hours>, at C<list of minutes> after the
144 hour'.
145  
146 =head3 C<hm_desc>
147  
148 If a job is running every minute, this short version of 'hours_minutes'
149 contains 'every minute, for x times, from y to z' where x is how often the job
150 runs in an hour, y is the first time it runs, and z is the last time it runs.
151  
152 Otherwise, this contains 'x times daily (y times an hour), starting at z and
153 ending at w', where x is how many times it runs in total, y is how many times
154 it runs per hour, z is the first time it runs and w is the last time it runs.
155  
156 =head3 C<line_num>
157  
158 This is the line number from the original file -- this is useful if you want to
159 go and adjust the crontab after reading the explanation.
160  
161 =cut
162  
163 sub new
164 1 ▶{
Subroutine new: called CC=2 SCAR=7.0
Pod documented
165 1 my ( $class, $args ) = @_;
166  
167 1 my $base = Parse::Crontab->new ( file => $args->{ file } );
168 1 ▶ defined $base or return undef;
Branch: 1 branch
BranchTrueFalseTotal
defined $base or return undef 1 0 1
169  
170 1 my $self = { base => $base };
171  
172 1 bless ( $self, $class );
173  
174 1 $self->load;
175 1 return $self;
176 }
177  
178 sub load
179 1 ▶{
Subroutine load: called CC=24 SCAR=31.9
Pod documented
180 1 my ( $self ) = @_;
181  
182 1 my %data;
183 1 my $line_num = 0; # Line number from original entry.
184  
185 1 foreach my $line ( @{ $self->{ base }{ entries } } ) {
186  
187 # First, skip everything that Parse::Crontab didn't find useful.
188  
189 54 ▶ if ( !exists $line->{ schedule } ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $line->{"schedule"}) 0 54 54
190  
191 0 $line_num++;
192 0 next;
193 }
194  
195 # Next, save the good stuff.
196  
197 54 push ( @{ $data{ $line->{ command } } },
198 { mon_range => $line->{ schedule }{ month }{ expanded },
199 day_range => $line->{ schedule }{ day }{ expanded },
200 dow_range => $line->{ schedule }{ day_of_week }{ expanded },
201 hour_range => $line->{ schedule }{ hour }{ expanded },
202 54 min_range => $line->{ schedule }{ minute }{ expanded } } );
203  
204 # Get the entry so we have less typing to do. Then, if we see the range
205 # of days is min to max, add 'all days' to the english description. More
206 # to come, obviously.
207  
208 54 my $entry = $data{ $line->{ command } }[ -1 ];
209  
210 # Look at the month.
211  
212 54 my %months = (
213 1 => 'January', 2 => 'February', 3 => 'March', 4 => 'April',
214 5 => 'May', 6 => 'June', 7 => 'July', 8 => 'August',
215 9 => 'September', 10 => 'October', 11 => 'November', 12 => 'December',
216 );
217  
218 54 ▶ if ( @{ $entry->{ mon_range } } == 12 ) {
Branch: 2 branches
BranchTrueFalseTotal
if (@{$entry->{'mon_range'};} == 12) { } 52 2 54
elsif (@{$entry->{'mon_range'};} == 1) { } 1 1 2
219  
220 52 $entry->{ month_desc } = 'every month';
221  
222 2 } elsif ( @{ $entry->{ mon_range } } == 1 ) {
223  
224 1 $entry->{ month_desc } = "just the month of $months{ $entry->{ mon_range }[ 0 ] }";
225  
226 } else {
227  
228 1 my $ranges = determine_ranges ( $entry->{ mon_range }, [ sort keys %months ] );
229  
230 # Create a list of months using the ranges we've found.
231  
232 1 my @month_list;
233 1 foreach my $r ( @$ranges ) {
234  
235 4 ▶ if ( $r->[ 0 ] == $r->[ 1 ] ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($r->[0] == $r->[1]) { } 4 0 4
236  
237 4 push ( @month_list, $months{ $r->[ 0 ] } );
238  
239 } else {
240  
241 0 push ( @month_list, "$months{ $r->[ 0 ] } to $months{ $r->[ 1 ] }" );
242 }
243 }
244  
245 # Commify the result.
246  
247 1 my $list = join ( ', ', @month_list );
248 1 ▶ if ( $list =~ /, / ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($list =~ /, /) 1 0 1
249  
250 1 $list =~ s/(.+), /$1, and /;
251 }
252  
253 1 $entry->{ month_desc } = "the following " . scalar @month_list . " months: $list";
254 }
255  
256 # Look at day of month.
257  
258 54 ▶ if ( @{ $entry->{ day_range } } == 31 ) {
Branch: 2 branches
BranchTrueFalseTotal
if (@{$entry->{'day_range'};} == 31) { } 52 2 54
elsif (@{$entry->{'day_range'};} == 1) { } 1 1 2
259  
260 52 $entry->{ day_desc } = 'every day of the month';
261  
262 2 } elsif ( @{ $entry->{ day_range } } == 1 ) {
263  
264 1 $entry->{ day_desc } = "Just on day $entry->{ day_range }[ 0 ]";
265  
266 } else {
267  
268 1 my $ranges = determine_ranges ( $entry->{ day_range }, [ 1 .. 31 ] );
269  
270 # Create a list of days using the ranges we've found.
271  
272 1 my @day_list;
273 1 foreach my $r ( @$ranges ) {
274  
275 3 ▶ if ( $r->[ 0 ] == $r->[ 1 ] ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($r->[0] == $r->[1]) { } 1 2 3
276  
277 1 push ( @day_list, $r->[ 0 ] );
278  
279 } else {
280  
281 2 push ( @day_list, "$r->[ 0 ]-$r->[ 1 ]" );
282 }
283 }
284  
285 # Commify the result.
286  
287 1 my $list = join ( ', ', @day_list );
288 1 ▶ if ( $list =~ /, / ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($list =~ /, /) 1 0 1
289  
290 1 $list =~ s/(.+), /$1, and /;
291 }
292  
293 1 $entry->{ day_desc } = "the following " . scalar @day_list . " days: $list";
294 1 ▶ if ( $entry->{ day_range } =~ /, / ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($entry->{"day_range"} =~ /, /) 0 1 1
295  
296 0 $entry->{ day_desc } =~ s/(.+), /$1, and /;
297 }
298 }
299  
300 # Look at the day of the week
301  
302 # Well, it looks like the parent module sometimes messes up and reads 7
303 # (Sunday) as both 0 and 7 -- meaning that we get two entries, both of
304 # them Sunday. So now I'm going to do some de-duplication on that mess.
305 # One side effect is that I won't have to pop off the last element of
306 # the array, since we'll now have a maximum of seven items.
307  
308 $entry->{ dow_range } =
309 54 [ uniq ( map { $_ % 7 } @{ $entry->{ dow_range } } ) ];
310  
311 54 my %days = (
312 0 => 'Sunday', 1 => 'Monday', 2 => 'Tuesday', 3 => 'Wednesday',
313 4 => 'Thursday', 5 => 'Friday', 6 => 'Saturday',
314 );
315  
316 54 ▶ if ( @{ $entry->{ dow_range } } == 7 ) {
Branch: 2 branches
BranchTrueFalseTotal
if (@{$entry->{'dow_range'};} == 7) { } 32 22 54
elsif (@{$entry->{'dow_range'};} == 1) { } 5 17 22
317  
318 32 $entry->{ dow_desc } = 'every day of the week';
319  
320 22 } elsif ( @{ $entry->{ dow_range } } == 1 ) {
321  
322 5 $entry->{ dow_desc } = 'just on ' . $days{ $entry->{ dow_range }[ 0 ] };
323  
324 } else {
325  
326 17 my $ranges = determine_ranges ( $entry->{ dow_range }, [ sort keys %days ] );
327  
328 # Create day_name_range using the ranges we've found.
329  
330 17 my @day_list;
331 17 foreach my $r ( @$ranges ) {
332  
333 21 ▶ if ( $r->[ 0 ] == $r->[ 1 ] ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($r->[0] == $r->[1]) { } 5 16 21
334  
335 5 push ( @day_list, $days{ $r->[ 0 ] } );
336  
337 } else {
338  
339 16 push ( @day_list, "$days{ $r->[ 0 ] } to $days{ $r->[ 1 ] }" );
340 }
341 }
342  
343 $entry->{ dow_desc } = "the following " .
344 17 ( scalar @{ $entry->{ dow_range } } ) . " days of the week: " .
345 join ( ', ', @day_list );
346  
347 17 ▶ if ( $entry->{ dow_desc } =~ /, / ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($entry->{"dow_desc"} =~ /, /) 2 15 17
348  
349 2 $entry->{ dow_desc } =~ s/(.+), /$1, and /;
350 }
351 }
352  
353 # If it's every minute, then just show that, plus the hours.
354  
355 54 my $hours = join ( ', ', map { "${_}h00" } @{ $entry->{ hour_range } } );
356 54 ▶ if ( $hours =~ /, / ) { $hours =~ s/(.+), /$1, and /; }
Branch: 1 branch
BranchTrueFalseTotal
if ($hours =~ /, /) 27 27 54
357  
358 54 ▶ if ( @{ $entry->{ min_range } } == 60 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$entry->{'min_range'};} == 60) { } 1 53 54
359  
360 1 $entry->{ hours_minutes } = "every minute of the following hours: $hours";
361  
362 # Later, we can convert the 24 hour values to am/pm if necessary. Or I
363 # might have a function that takes the hour and minute and returns an
364 # appropriately formatted time. (There's a bit of copy-pasta going on
365 # here, obviously.)
366  
367 $entry->{ hm_desc } = "every minute, for " .
368 1 ( scalar @{ $entry->{ hour_range } } ) . " hours, from " .
369 1 hm ( @{ $entry->{ hour_range } }[ 0 ] ) . " to " .
370 1 hm ( @{ $entry->{ hour_range } }[ -1 ] );
371  
372 } else {
373  
374 # We're going to show the hours and minutes in a list. The shorter
375 # version of the list follows.
376  
377 my $minutes =
378 53 join ( ', ', map { sprintf ( ":%02d", $_ ) } @{ $entry->{ min_range } } );
379 53 ▶ if ( $minutes =~ /, / ) { $minutes =~ s/(.+), /$1, and /; }
Branch: 1 branch
BranchTrueFalseTotal
if ($minutes =~ /, /) 11 42 53
380  
381 # Clean up the output a little.
382  
383 $entry->{ hours_minutes } =
384 53 ▶ ( @{ $entry->{ hour_range } } > 1 ? "at the hours" : "at" ) .
Branch: 1 branch
BranchTrueFalseTotal
@{$entry->{'hour_range'};} > 1 ? : 26 27 53
385 " $hours, at $minutes after the hour";
386  
387 # Prepare the short description. The description for the one-time cron
388 # job is much shorter.
389  
390 53 my $times = scalar @{ $entry->{ hour_range } } *
391 53 scalar @{ $entry->{ min_range } };
392  
393 53 ▶ if ( $times == 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($times == 1) { } 27 26 53
394  
395 $entry->{ hm_desc } = "Once, at " .
396 27 hm ( $entry->{ hour_range }->[ 0 ], $entry->{ min_range }->[ 0 ] );
397  
398 } else {
399  
400 $entry->{ hm_desc } = "$times times daily (" .
401 26 ( scalar @{ $entry->{ min_range } } ) . " times an hour), starting at " .
402 26 hm ( @{ $entry->{ hour_range } }[ 0 ], @{ $entry->{ min_range } }[ 0 ] ) .
403 ", and ending at " .
404 26 hm ( @{ $entry->{ hour_range } }[ -1 ], @{ $entry->{ min_range } }[ -1 ] );
405  
406 26 $entry->{ hm_desc } =~ s/\(2 times/(twice/; # Simplify
407  
408 # If the count of min_range is 1, that means it happens just once in
409 # an hour, but it's possible that the job doesn't run every hour, so
410 # once an hour is mis-leading. So delete '(1 times an hour) if it's
411 # in the description.
412  
413 26 $entry->{ hm_desc } =~ s/ \(1 times an hour\)//; # Delete this.
414 }
415 }
416  
417 # Add line number ..
418  
419 54 $entry->{ line_num } = $line_num++;
420 }
421 1 $self->{ summary } = \%data;
422 }
423  
424 # Format the time into a common format. This will replace a lot of copy pasta
425 # from earlier versions. If called with just an hour, we assume zero minutes.
426  
427 sub hm
428 81 ▶{
Subroutine hm: called CC=2 SCAR=6.9
Pod documented
429 81 my ( $h, $m ) = @_;
430  
431 81 ▶ return ( sprintf ( "${h}h%02d", $m // 0 ) );
Condition100%2/2
$m // 0
l!l
792
MC/DC100%1/1
$m // 0
$m
Truth table100%2/2
A
A= $m
Aresult
11
00
432 }
433  
434 # Figure out the ranges from a set of values.
435  
436 sub determine_ranges
437 19 ▶{
Subroutine determine_ranges: called CC=10 SCAR=23.0
Pod documented
438 19 my ( $input_range, $possible_values ) = @_;
439  
440 # Original comment when this code was just for ranges of days: For my next
441 # trick, I'm going to see if I can reduce the list to a range, in order to
442 # map 1-5 to Monday to Friday. All we know about the list of day numbers
443 # is that they're ordered.
444  
445 19 my ( $first, $last, @ranges );
446  
447 19 foreach my $off ( 0 .. ( scalar @$possible_values ) - 1 ) {
448  
449 162 my $this = $input_range->[ $off ];
450 162 ▶ if ( !defined $this ) { next; }
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $this) 52 110 162
451  
452 110 ▶ if ( defined $first ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $first) { } 91 19 110
453  
454 91 ▶ if ( defined $last ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $last) { } 66 25 91
455  
456 66 ▶ if ( $last + 1 == $this ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($last + 1 == $this) { } 64 2 66
457  
458 # We're still in order, continue.
459  
460 64 $last = $this;
461  
462 } else {
463  
464 # Not in order -- need to close off previous order and start a new one.
465  
466 2 push ( @ranges, [ $first, $last ] );
467  
468 2 $first = $this;
469 2 undef $last;
470 }
471
472 } else {
473  
474 25 ▶ if ( $first + 1 == $this ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($first + 1 == $this) { } 18 7 25
475  
476 # We're still in order, continue.
477  
478 18 $last = $input_range->[ $off ];
479  
480 } else {
481  
482 # Not in order -- need to close off previous order and start a new one.
483  
484 7 push ( @ranges, [ $first, $first ] );
485 7 $first = $input_range->[ $off ];
486 }
487 }
488  
489 } else {
490  
491 19 $first = $input_range->[ $off ];
492 }
493 }
494  
495 # We may need to capture the last range ..
496  
497 19 ▶ if ( @ranges == 0 || defined $first ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@ranges == 0 or defined $first) 19 0 19
Condition66%2/3
@ranges == 0 or defined $first
l!l&&r!l&&!r
1540
MC/DC0%0/2
@ranges == 0 or defined $first
@ranges == 0 defined $first
Truth table66%2/3
A or B
A= @ranges == 0B= defined $first
ABresult
1X1
011
000
498  
499 19 ▶ if ( defined $last ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $last) { } 16 3 19
500  
501 16 push ( @ranges, [ $first, $last ] );
502  
503 } else {
504  
505 3 push ( @ranges, [ $first, $first ] );
506 }
507 }
508  
509 19 return ( \@ranges );
510 }
511  
512  
513 =head1 AUTHOR
514  
515 T. Alex Beamish, C<< <talexb at gmail.com> >>
516  
517 =head1 BUGS
518  
519 Please report any bugs or feature requests to C<bug-parse-crontab-english at rt.cpan.org>, or through
520 the web interface at L<https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Parse-Crontab-English>. I will be notified, and then you'll
521 automatically be notified of progress on your bug as I make changes.
522  
523  
524  
525  
526 =head1 SUPPORT
527  
528 You can find documentation for this module with the perldoc command.
529  
530 perldoc Parse::Crontab::English
531  
532  
533 You can also look for information at:
534  
535 =over 4
536  
537 =item * RT: CPAN's request tracker (report bugs here)
538  
539 L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Parse-Crontab-English>
540  
541 =item * CPAN Ratings
542  
543 L<https://cpanratings.perl.org/d/Parse-Crontab-English>
544  
545 =item * Search CPAN
546  
547 L<https://metacpan.org/release/Parse-Crontab-English>
548  
549 =back
550  
551  
552 =head1 ACKNOWLEDGEMENTS
553  
554  
555 =head1 LICENSE AND COPYRIGHT
556  
557 This software is Copyright (c) 2026 by T. Alex Beamish.
558  
559 This is free software, licensed under:
560  
561 The Artistic License 2.0 (GPL Compatible)
562  
563  
564 =cut
565  
566 2 1; # End of Parse::Crontab::English
↑ Summary