cron-lite

Lightweight cron expressions parser and time series generator.

This is a tiny crate, intended to:

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

It has the 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 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.

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

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(())
}

TODO

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

License

This project is licensed under the MIT license.