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)