install.packages("remotes")  # if not already installed
remotes::install_github("matt-dray/dialga")
library(dialga)

A primer

But first, a quick demo on standard cron expressions. Their format is a string of five time-period ‘slots’ separated by spaces. The slots from left to right specify the minutes, hours, days of the month, months, and days of the week that you want to schedule your script to run.

The format required for the values in these slots can be expressed relatively easily as R code, which is what r2cron() uses as input. For example, this table shows cron-string formats for the minutes slot and the corresponding R integer vector for them:

Description	Cron	R
Every minute (minutes 0 to 59)	*	0:59
A single minute (5)	5	5
A consecutive sequence of minutes (1, 2 and 3)	1-3	1:3
Several irregularly-spaced minutes (1, 15 and 17)	1,15,17	c(1, 15, 17)
A sequence of minutes at regular intervals for the whole hour, starting with some value (every 15 minutes starting at minute 0)	0/15	seq(0, 59, 15)

The same principles extend to the other time-period slots, but the ranges will obviously differ. For example, the hour slot can take values 1 to 23 (i.e. a 24-hour clock), while the days of the week are zero-indexed from 0 (Sunday) to 6 (Saturday). An asterisk is a special character meaning every unit of that time period, like every minute and every hour.

So ‘every 30th minute past the hour’ would be "30 * * * *". The contrived example string from the opening of this post—"0/15 * 1,3,20 6 2,3"—translates as ‘every 15 minutes starting from minute 0 of every hour, on the 1st, 3rd and 20th of June; and Mondays and Tuesdays’.

To help simplify things, the r2cron() function lets you specify each slot in turn as arguments. Each input is an R expression like in the table above. You don’t have to worry about cron-specific symbols, you just provide the appropriate integer vector.

Simple example

How would you specify the 28th minute past 11PM every day with r2cron()? You pass the value 28 to the minutes argument and 23 to the hours argument. The resulting cron string has a 28 in the minutes slot and a 23 in the hours slot, as expected.

x <- dialga::r2cron(
  minutes = 28, 
  hours = 23  # 24-hour clock
)

x

## [1] "28 23 * * *"

Great, there’s our cron string!

You may have noticed from the documentation that there’s also a clip argument. This is for your convenience; when set to TRUE, the output will be copied to the clipboard for you to paste elsewhere, like into the YAML of a GitHub Action in my case. You will need separately to install {clipr} yourself from CRAN if you want this functionality in {dialga}.

Cool, but how do we know this worked? We could pass the cron string into cron2eng() to confirm it.

dialga::cron2eng(x)

## Cron string '28 23 * * *' means:
##   - minute(s) 28
##   - hour(s) 11PM
##   - every day(s) of the month
##   - every month(s)
##   - any day(s) of the week

This text output isn’t sophisticated, but it communicates the point. I’ve chosen to keep it simple by breaking it into bullet points, rather than wrestling the output into a potentially confusing single sentence.

Of course, this means you could pipe these functions together to go from R to cron to English in one go.

library(magrittr)  # for %>%

dialga::r2cron(minutes = 28, hours = 23) %>% 
  dialga::cron2eng()

## Cron string '28 23 * * *' means:
##   - minute(s) 28
##   - hour(s) 11PM
##   - every day(s) of the month
##   - every month(s)
##   - any day(s) of the week

It might be nice to produce eventually an eng2cron() function that goes directly from a text description to the appropriate cron string, but I think that would be a fair amount of effort.

More complex example

We can see the flexibility of r2cron() with an unlikely scheduling request like ‘every 20 minutes from the top of the hour (minute 0) of 3PM, 4PM and 5PM, on the 1st days of April, October and November, plus every weekend’. Again, we can specify these as R integer vectors.

y <- dialga::r2cron(
 minutes = seq(0, 59, 20),
 hours = 15:17,  # 24-hr clock
 days_month = 1,
 months = c(4, 10, 11),
 days_week = c(1, 7)  # Sunday is '1'
)

y

## [1] "0/20 15-17 1 4,10,11 0,6"

Note that the input to the days_week argument isn’t zero-indexed even though the cron format is zero-indexed; Sunday is 1 in r2cron(), not 0. This is to conform better to the fact that R doesn’t typically zero-index things. r2cron() converts days_week = 1 into 0 for this slot automatically.

And of course, we can express the output of this complicated cron string in English:

dialga::cron2eng(y)

## Cron string '0/20 15-17 1 4,10,11 0,6' means:
##   - every 20 minute(s) starting from minute(s) 0
##   - hour(s) 3PM to 5PM
##   - day(s) of the month 1
##   - month(s) April, October and November
##   - and day(s) of the week Sunday and Saturday

Warnings

As a courtesy, you’ll be warned when unlikely dates arise. Some are impossible, like 31 September and others are rare, like 29 February. It’s important that these are warnings and not errors though, since you might legitimately want the job to run on 31sts when available, or the 29 February only (i.e. every four years).

This example hits all the warnings:

dialga::r2cron(days_month = 28:31, months = 2)

## Warning in dialga::r2cron(days_month = 28:31, months = 2): 
##   Sure? There's no 31st in Feb, Apr, Jun, Sept nor Nov.

## Warning in dialga::r2cron(days_month = 28:31, months = 2): 
##   Sure? There's no 30th in Feb.

## Warning in dialga::r2cron(days_month = 28:31, months = 2): 
##   Sure? 29 Feb is only in leap years.

## [1] "* * 28-31 2 *"