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)