NAME

Cron::Sequencer

SYNOPSIS

    my $crontab = Cron::Sequencer->new("/path/to/crontab");
    print encode_json([$crontab->sequence($start, $end)]);

DESCRIPTION

This class can take one or more crontabs and show the sequence of commands that they would run for the time interval requested.

METHODS

new

new takes a list of arguments each representing a crontab file, passes each in turn to Cron::Sequence::Parser->new, and then combines the parsed files into a single set of crontab events.

See "new" in Cron::Sequencer::Parser for the various formats to specify a crontab file or its contents.

sequence from to

Generates the sequence of commands that the crontab(s) would run for the specific time interval. from and to are in epoch seconds, from is inclusive, end exclusive.

Hence for this input:

    30 12 * * * lunch!
    30 12 * * 5 POETS!

Calling $crontab->sequence(45000, 131400) generates this output:

    [
      [
        {
          command => "lunch!",
          env     => undef,
          file    => "reminder",
          lineno  => 1,
          time    => 45000,
          unset   => undef,
          when    => "30 12 * * *",
        },
      ],
    ]

where the event(s) at 131400 are not reported, because the end is exclusive. Whereas $crontab->sequence(45000, 131401) shows:

    [
      [
        {
          command => "lunch!",
          env     => undef,
          file    => "reminder",
          lineno  => 1,
          time    => 45000,
          unset   => undef,
          when    => "30 12 * * *",
        },
      ],
      [
        {
          command => "lunch!",
          env     => undef,
          file    => "reminder",
          lineno  => 1,
          time    => 131400,
          unset   => undef,
          when    => "30 12 * * *",
        },
        {
          command => "POETS!",
          env     => undef,
          file    => "reminder",
          lineno  => 2,
          time    => 131400,
          unset   => undef,
          when    => "30 12 * * 5",
        },
      ],
    ]

The output is structured as a list of lists, with events that fire at the same time grouped as lists. This makes it easier to find cases where different crontab lines trigger at the same time.

SEE ALSO

This module uses Algorithm::Cron to implement the cron scheduling, but has its own crontab file parser. There are many other modules on CPAN:

Config::Crontab

Parses, edits and outputs crontab files

Config::Generator::Crontab

Outputs crontab files

DateTime::Cron::Simple

Parse a cron entry and check against current time

DateTime::Event::Cron

Generate recurrence sets from crontab lines and files

Mojar::Cron

Cron-style datetime patterns and algorithm (for Mojolicious)

Parse::Crontab

Parses crontab files

Pegex::Crontab

A Pegex crontab Parser

QBit::Cron

"Class for working with Cron" (for qbit)

Set::Crontab

Expands crontab integer lists

Schedule::Cron

cron-like scheduler for Perl subroutines

Schedule::Cron::Events

take a line from a crontab and find out when events will occur

Time::Crontab

Parser for crontab time specifications

These modules fall into roughly three groups

• Abstract crontab file parsing and manipulation

• Parsing individule command time specification strings

• Scheduling events in real time

None of the "schedulers" are easy to adapt to show events (rather than running them) and to do so for arbitrary time intervals. The parsers effectively provide an "abstract syntax tree" for the crontab, but by design don't handle "compiling" this into a sequence of "this command, with these environment variable definitions in scope". The parser/compiler in this module is 70 lines of code, including comments, and handles various corner cases and quirks of the vixie crontab C parser code. Interfacing to one of AST parser modules and implementing a "compiler" on it would likely be more code than this.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. If you would like to contribute documentation, features, bug fixes, or anything else then please raise an issue / pull request:

    https://github.com/Humanstate/cron-sequencer

AUTHOR

Nicholas Clark - nick@ccl4.org