NAME

DateTime::Event::Cron - DateTime extension for generating recurrence sets from crontab lines and files.

SYNOPSIS

  use DateTime::Event::Cron;

  # check if a date matches (defaults to current time)
  my $c = DateTime::Event::Cron->new('* 2 * * *');
  if ($c->match) {
    # do stuff
  }
  if ($c->match($date)) {
    # do something else for datetime $date
  }

  # DateTime::Set construction from crontab line
  $crontab = '*/3 15 1-10 3,4,5 */2';
  $set = DateTime::Event::Cron->from_cron($crontab);
  $iter = $set->iterator(after => DateTime->now);
  while (1) {
    my $next = $iter->next;
    my $now  = DateTime->now;
    sleep(($next->subtract_datetime_absolute($now))->seconds);
    # do stuff...
  }

  # List of DateTime::Set objects from crontab file
  @sets = DateTime::Event::Cron->from_crontab(file => '/etc/crontab');
  $now = DateTime->now;
  print "Now: ", $now->datetime, "\n";
  foreach (@sets) {
    my $next = $_->next($now);
    print $next->datetime, "\n";
  }

  # DateTime::Set parameters
  $crontab = '* * * * *';

  $now = DateTime->now;
  %set_parms = ( after => $now );
  $set = DateTime::Event::Cron->from_cron(cron => $crontab, %set_parms);
  $dt = $set->next;
  print "Now: ", $now->datetime, " and next: ", $dt->datetime, "\n";

  # Spans for DateTime::Set
  $crontab = '* * * * *';
  $now = DateTime->now;
  $now2 = $now->clone;
  $span = DateTime::Span->from_datetimes(
            start => $now->add(minutes => 1),
	    end   => $now2->add(hours => 1),
	  );
  %parms = (cron => $crontab, span => $span);
  $set = DateTime::Event::Cron->from_cron(%parms);
  # ...do things with the DateTime::Set

  # Every RTFCT relative to 12am Jan 1st this year
  $crontab = '7-10 6,12-15 10-28/2 */3 3,4,5';
  $date = DateTime->now->truncate(to => 'year');
  $set = DateTime::Event::Cron->from_cron(cron => $crontab, after => $date);

  # Rather than generating DateTime::Set objects, next/prev
  # calculations can be made directly:

  # Every day at 10am, 2pm, and 6pm. Reference date
  # defaults to DateTime->now.
  $crontab = '10,14,18 * * * *';
  $dtc = DateTime::Event::Cron->new_from_cron(cron => $crontab);
  $next_datetime = $dtc->next;
  $last_datetime = $dtc->previous;
  ...

  # List of DateTime::Event::Cron objects from
  # crontab file
  @dtc = DateTime::Event::Cron->new_from_crontab(file => '/etc/crontab');

  # Full cron lines with user, such as from /etc/crontab
  # or files in /etc/cron.d, are supported and auto-detected:
  $crontab = '* * * * * gump /bin/date';
  $dtc = DateTime::Event::Cron->new(cron => $crontab);

  # Auto-detection of users is disabled if you explicitly
  # enable/disable via the user_mode parameter:
  $dtc = DateTime::Event::Cron->new(cron => $crontab, user_mode => 1);
  my $user = $dtc->user;
  my $command = $dtc->command;

  # Unparsed original cron entry
  my $original = $dtc->original;

DESCRIPTION

DateTime::Event::Cron generated DateTime events or DateTime::Set objects based on crontab-style entries.

METHODS

The cron fields are typical crontab-style entries. For more information, see crontab(5) and extensions described in Set::Crontab. The fields can be passed as a single string or as a reference to an array containing each field. Only the first five fields are retained.

DateTime::Set Factories

See DateTime::Set for methods provided by Set objects, such as next() and previous().

from_cron($cronline)

from_cron(cron => $cronline, %parms, %set_parms)

Generates a DateTime::Set recurrence for the cron line provided. See new() for details on %parms. Optionally takes parameters for DateTime::Set.

from_crontab(file => $crontab_fh, %parms, %set_parms)

Returns a list of DateTime::Set recurrences based on lines from a crontab file. $crontab_fh can be either a filename or filehandle reference. See new() for details on %parm. Optionally takes parameters for DateTime::Set which will be passed along to each set for each line.

as_set(%set_parms)

Generates a DateTime::Set recurrence from an existing DateTime::Event::Cron object.

Constructors

new_from_cron(cron => $cronstring, %parms)

Returns a DateTime::Event::Cron object based on the cron specification. Optional parameters include the boolean 'user_mode' which indicates that the crontab entry includes a username column before the command.

new_from_crontab(file => $fh, %parms)

Returns a list of DateTime::Event::Cron objects based on the lines of a crontab file. $fh can be either a filename or a filehandle reference. Optional parameters include the boolean 'user_mode' as mentioned above.

Other methods

next()

next($date)

Returns the next valid datetime according to the cron specification. $date defaults to DateTime->now unless provided.

previous()

previous($date)

Returns the previous valid datetime according to the cron specification. $date defaults to DateTime->now unless provided.

increment($date)

decrement($date)

Same as next() and previous() except that the provided datetime is modified to the new datetime.

match($date)

Returns whether or not the given datetime (defaults to current time) matches the current cron specification. Dates are truncated to minute resolution.

valid($date)

A more strict version of match(). Returns whether the given datetime is valid under the current cron specification. Cron dates are only accurate to the minute -- datetimes with seconds greater than 0 are invalid by default. (note: never fear, all methods accepting dates will accept invalid dates -- they will simply be rounded to the next nearest valid date in all cases except this particular method)

command()

Returns the command string, if any, from the original crontab entry. Currently no expansion is performed such as resolving environment variables, etc.

user()

Returns the username under which this cron command was to be executed, assuming such a field was present in the original cron entry.

original()

Returns the original, unparsed cron string including any user or command fields.

AUTHOR

Matthew P. Sisk <sisk@mojotoad.com>

COPYRIGHT

Copyright (c) 2003 Matthew P. Sisk. All rights reserved. All wrongs revenged. This program is free software; you can distribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

DateTime(3), DateTime::Set(3), DateTime::Event::Recurrence(3), DateTime::Event::ICal(3), DateTime::Span(3), Set::Crontab(3), crontab(5)