NAME

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

SYNOPSIS

  use DateTime::Event::Cron;

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

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

  # DateTime::Set parameters
  $crontab = '* * * * *';
  %set_parms = ( after => DateTime->now );
  $set = DateTime::Event::Cron->from_cron($crontab, %set_parms);
  $dt = $set->next;

  # 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),
	  );
  $set = DateTime::Event::Cron->from_cron($crontab, span => $span);
  # ...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($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($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('/etc/crontab');

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($cronline, %set_parms)

Generates a DateTime::Set recurrence for the cron line provided. All remaining arguments will be passed to the DateTime::Set constructor.

from_crontab($crontab_fh)

from_crontab($crontab_fh, %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. Optionally takes parameters for DateTime::Set which will be passed along to each set for each line.

Constructors

new_from_cron($cronstring)

Returns a DateTime::Event::Cron object based on the cron specification.

new_from_crontab($fh)

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.

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.

valid($date)

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)

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)