/ 
Parse-Crontab-English-0.01
/ Parse::Crontab::English

NAME

Parse::Crontab::English - Generate useful English documentation on how often a crontab command runs.

VERSION

Version 0.01

SYNOPSIS

Parses the supplied crontab (using Parse::Crontab) and then examines the data in order to create a comprehensive English explanation of how often a command runs.

Perhaps a little code snippet.

use Parse::Crontab::English;

my $foo = Parse::Crontab::English->new( file => 'crontab.lst');

We now have the full details of each relevant crontab line in $foo->{ base }, and a summary in $foo->{ summary } as a HoA (hash of arrays). The hash key is the command line (the last entry in the line from crontab), and the detail consists of the months, days of the month, days of the week, a complete list of the times (hours and minutes) of each run, and a summary of the same times.

Because a command may have multiple entries (perhaps a weekday run and a different weekend run), the result is held in an array.

So, for the crontab line

15  9-17 *   *   0-2,4,6 cd /home/xyz/extra && ./several_days.sh >sev.out 2>sev.err

the detail for 'cd /home/xyz/extra && ./several_days.sh >sev.out 2>sev.err' will contain a single element, with the following hash values:

'month_desc' => 'every month'
'day_desc' => 'every day of the month'
'dow_desc' => 'Sunday to Tuesday, Thursday, and Saturday'
'hours_minutes' => 'at the hours 9h00, 10h00, 11h00, 12h00, 13h00, 14h00, 15h00, 16h00, and 17h00, at :15 after the hour'
'hm_desc' => '9 times daily, starting at 9h15, and ending at 17h15'

The example script 'explain_crontab' shows the following result for this line:

Command line: cd /home/xyz/extra && ./several_days.sh >sev.out 2>sev.err
--> Detail (line 1):
  --> Description of Days of the week: the following 5 days of the week: Sunday to Tuesday, Thursday, and Saturday
  --> Description of Hours and Minutes: 9 times daily, starting at 9h15, and ending at 17h15
  --> Detail of Hours and Minutes: at the hours 9h00, 10h00, 11h00, 12h00, 13h00, 14h00, 15h00, 16h00, and 17h00, at :15 after the hour

Since both 'every day of the month' and 'every month' are the defaults, the script omits those comments from the summary.

SUBROUTINES/METHODS

new

my $foo = Parse::Crontab::English->new( file => $filename);

Loads the crontab definition contained in the named file, and generates a summary of each line.

The result is a hash whose key is the command line executed by cron; since command lines can be duplciated, the value is an AoH, with the hash containing the base values from Parse::Crontab and the summary containing English descriptions of when the job will run.

load

Internal routine, called from new.

hm

Internal routine, called from load to format hour (and possibly) minutes into a nice output string.

determine_ranges

Internal routine, called from load to build an AoA containing the value ranges.

Values straight from Parse::Crontab:

mon_range

The sorted list of months that the job will run. Values range from 1 to 12.

day_range

The sorted list of days of the month that the job will run. Values range from 1 to 31.

dow_range

The sorted list of days of the week that the job will run. Values run from 0 to 7, and there may be both 0 and 7 (Sunday).

hour_range

Ths sorted list of hours that the job will run. Values run from 0 to 23.

min_range

The sorted list of minutes that the job will run. Values run from 0 to 59.

Values from Parse::Crontab::English

mon_desc

The sorted list of months that the job will run. This will be 'every month', 'just the month of xx', or a list of months.

day_desc

The sorted list of days of the month that the job will run. This will be 'every day of the month', 'just on day xx', or a list of days.

dow_desc

This is the sorted list of days of the week that the job will run. This will be 'every day of the week', 'just on xx', or a list of week days.

hours_minutes

If a job runs every minute, this contains 'every minute, for xx hours, from yy to zz', where xx is the number of hours, yy is the first time, and zz is the last time the job runs.

Otherwise, this contains 'at the hours list of hours, at list of minutes after the hour'.

hm_desc

If a job is running every minute, this short version of 'hours_minutes' contains 'every minute, for x times, from y to z' where x is how often the job runs in an hour, y is the first time it runs, and z is the last time it runs.

Otherwise, this contains 'x times daily (y times an hour), starting at z and ending at w', where x is how many times it runs in total, y is how many times it runs per hour, z is the first time it runs and w is the last time it runs.

line_num

This is the line number from the original file -- this is useful if you want to go and adjust the crontab after reading the explanation.

AUTHOR

T. Alex Beamish, <talexb at gmail.com>

BUGS

Please report any bugs or feature requests to bug-parse-crontab-english at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Parse-Crontab-English. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Parse::Crontab::English

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by T. Alex Beamish.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)