---
name: "DateTime::Event::Cron"
section: "3pm"
platform: "linux"
package: "libdatetime-event-cron-perl"
version: "0.09-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/DateTime::Event::Cron"
---

# DateTime::Event::Cron(3pm)

DateTime extension for generating recurrence sets from crontab lines and files.

## 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)](/crontab/5.md) 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)](/crontab/5.md)