DateTime::Event::Cron(3pm)				User Contributed Perl Documentation				DateTime::Event::Cron(3pm)

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, "
";
	 foreach (@sets) {
	   my $next = $_->next($now);
	   print $next->datetime, "
";
	 }

	 # 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, "
";

	 # 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)

perl v5.14.2							    2010-06-10						DateTime::Event::Cron(3pm)