cron-lite

Lightweight cron expressions parser and time series generator.

This tiny crate is intended to:

• parse almost all kinds of popular cron schedule formats;
• generate series of timestamps according to the schedule.

It has a single external dependency - chrono.

This is not a cron jobs scheduler or runner. If you need a scheduler/runner, look for sacs of any other similar crate.

Cron schedule format

Traditionally, cron schedule expression has a 5-fields format: minutes, hours, days, months and days of week. This crate uses such a format by default, but two optional fields may be added, seconds and years:

• if seconds is empty, 0 is used by default;
• if years is empty, * is used by default;
• if 6-fields schedule is specified, then seconds filed is assumed as first and years as empty (default).

The table below describes valid values and patterns of each field:

Patterns meanings:

• * - each possible value, i.e. 0,1,2,...,59 for minutes;
• , - list of values or patterns, i.e. 1,7,12, SUN,FRI;
• - - range of values, i.e. 0-15, JAN-MAR;
• / - repeating values, i.e. */12, 10/5, 30-59/2;
• L - last day of the month (for month field), or last particular day of the week (for weekday field), i.e. L or 5L;
• W - the weekday (not Sunday or Saturday), nearest to the specified days of month in the same month, i.e. 22W;
• # - specific day of the week, i.e. fri#1, 1#4;
• ? - for days of month or week means that value doesn't matter: if day of month is specified (not *), then day of week should be ? and vise versa.

Also, short aliases for well-known schedule expressions are allowed:

Some additional information and fields description and relationships may be found here (this is not complete or exceptional documentation).

Schedule with timezone

If tz feature is enabled, it's possible to prefix cron schedule with timezone, for example:

• TZ=Europe/Paris @monthly
• TZ=EET 0 12 * * *

How to use

The single entity of the crate is a Schedule structure, which has three basic methods:

• new(): constructor to parse and validate provided schedule;
• upcoming(): returns time of the next schedule's event, starting from the provided timestamp;
• iter(): returns an Iterator which produces series of timestamps according to the schedule.

Example with upcoming

use chrono::Utc;
use cron_lite::{Result, Schedule};

fn main() -> Result<()> {
    let schedule = Schedule::new("0 0 0 * * *")?;
    let now = Utc::now();

    // Get the next event's timestamp starting from now
    let next = schedule.upcoming(&now).unwrap();
    println!("next: {next}");

    Ok(())
}

Example with iter

use chrono::Utc;
use cron_lite::{Result, Schedule};

fn main() -> Result<()> {
    let schedule = Schedule::new("0 0 0 * * *")?;
    let now = Utc::now();

    // Get the next 10 timestamps starting from now
    schedule.iter(&now).take(10).for_each(|t| println!("next: {t}"));

    Ok(())
}

Feature flags

• serde: adds Serialize and Deserialize trait implementation for [Schedule].
• tz: enables support of cron schedules with timezone.

TODO

• Descriptive example.
• Performance tests.
• More unit tests for edge cases.
• Aliases: @yearly, @annually, @monthly, @daily, @midnight, @hourly.
• Feature tz: timezone-aware schedule pattern.
• Feature serde: implement Serialize/Deserialize traits for Schedule.

License

This project is licensed under the MIT license.