The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
time.piece.cron_0.1
River stage zero No dependents
++
/ Time::Piece::Cron

NAME

Time::Piece::Cron - Parse and evaluate times from crontab strings.

VERSION

Version 0.1

SYNOPSIS

    use Time::Piece;
    
    use Time::Piece::Cron;

    my $cron = Time::Piece::Cron->new();
    
    my $timepiece = $cron->next_time("30 08 * * Mon-Fri");
    
    my $time = $cron->next_timestamp("30 08 * * Mon-Fri");
    
    my $bool = $cron->is_now("*/15 * * * *");
    
    my $bool = $cron->parse_cron("30 08 * * Foo-Bar");

DESCRIPTION

Evaluate times from crontab type entries in a manner similar to the Vixie cron standards, and the guidelines found in the "man 5 crontab" documentation.

The cron time and date fields are:

field allowed values ----- -------------- minute 0-59 hour 0-23 day of month 1-31 month 1-12 (or names, see below) day of week 0-7 (0 or 7 is Sun, or use names)

A field may be an asterisk (*), which always stands for "first-last".

Ranges of numbers are allowed. Ranges are two numbers separated with a hyphen. The specified range is inclusive. For example, 8-11 for an "hours" entry specifies execution at hours 8, 9, 10 and 11.

Lists are allowed. A list is a set of numbers (or ranges) separated by commas. Examples: "1,2,5,9", "0-4,8-12".

Step values can be used in conjunction with ranges. Following a range with "<number>" specifies skips of the number's value through the range. For example, "0-23/2" can be used in the hours field to specify command execution every other hour. Steps are also permitted after an asterisk, so if you want to say "every two hours", just use "*/2".

Names can also be used for the "month" and "day of week" fields. Use the first three letters of the particular day or month (case doesn't matter).

Ranges and lists of names are allowed(**). However, avoid Weekday and Month ranges that wrap from one week (or year) into the next, as this will result in unexpected behavior once the lists are expanded and sorted. Such as:

  "30 08 * * Fri-Tue" or "30 08 * Dec-Mar *"

If you must span into another week or year, use absolute lists instead. Such as:

  "30 08 * * Fri,Sat,Sun,Mon,Tue" or "30 08 * Dec,Jan,Feb,Mar *"

Note: The day of a command's execution can be specified by two fields -- day of month, and day of week. If both fields are restricted (ie, aren't *), the command will be run when either field matches the current time. For example, "30 4 1,15 * 5" would cause a command to be run at 4:30 am on the 1st and 15th of each month, PLUS every Friday.

(**) = Deviates from Vixie cron standard.

METHODS

new

Create a new Time::Piece::Cron instance;

PARAMS

none

RETURNS

an object

    $cron = Time::Piece::Cron->new();

is_now

Evaluate if a crontab string is true for the current time.

PARAMS

1. A string, like "05 * * * *"

2. Optionally, a Time::Piece object for a reference start time.

RETURNS

1 if TRUE

0 if FALSE

    $bool = $cron->is_now("30 08 * * Mon-Fri");

next_time

Returns a Time::Piece object representing the next time a cron entry will run.

If you just want to know if a cron entry will run right now, use instead the faster is_now() method.

PARAMS

1. A valid crontab string. like ("05 * * * *")

2. Optionally, a Time::Piece object for a reference start time.

RETURNS

A Time::Piece object

UNDEF on error.

    $timepiece = $cron->next_time("30 08 * * *");

next_timestamp

Same as next_time(), but returns a regular perl timestamp (seconds since epoch) instead of a Time::Piece object.

PARAMS

1. A valid crontab string. like ("05 * * * *")

2. Optionally, a perl timestamp for a reference start time.

RETURNS

A perl timestamp

UNDEF on error.

    $time = $cron->next_timestamp("30 08 * * *");

parse_cron

Parse a crontab time string, and test for validity. This method is mainly used internally, but may prove useful for other things.

PARAMS

A string, like "00,30 08 * * Mon-Fri"

RETURNS

In SCALAR context, returns whether or not it is a valid cron string.

1 if TRUE 0 if FALSE

In ARRAY context, returns an array of the possible values for each segment.

ARRAY on success ([min 0-59],[hour 0-23],[mday 1-31],[mon 0-11],[wday 0-6]) UNDEF on Error

    $bool = $cron->parse_cron("30 08 * * Mon-Fri");

    @atoms = $cron->parse_cron("30 08 * * Mon-Fri");

AUTHOR

Jeffrey Leary, <jeff at sillymonkeysoftware.com>

BUGS

Please report any bugs or feature requests to bug-time-piece-cron at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Time-Piece-Cron. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

TO DO

Add a last_time() method.

Test harness is very rudimentary. Could use better tests.

Possibly add ability to handle special characters (L, W, ?, \#) found in some non-standard implementations of cron.

SUPPORT

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

    perldoc Time::Piece::Cron

You can also look for information at:

ACKNOWLEDGEMENTS

SEE ALSO

Time::Piece http://perldoc.perl.org/Time/Piece.html

Cron http://wikipedia.org/wiki/Cron

LICENSE AND COPYRIGHT

Copyright 2013 Jeffrey Leary.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.