From 963257179c7e67ee0de64bfa69920311a8672788 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Barto=C5=A1?= Date: Wed, 9 Oct 2024 15:46:16 +0200 Subject: [PATCH] Docs: full syntax overview (#184) --- README.md | 76 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 59 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index eec534b..3e7e782 100644 --- a/README.md +++ b/README.md @@ -55,23 +55,65 @@ CRON Expressions A CRON expression is a string representing the schedule for a particular command to execute. The parts of a CRON schedule are as follows: - * * * * * - - - - - - - | | | | | - | | | | | - | | | | +----- day of week (0 - 7) (Sunday=0 or 7) - | | | +---------- month (1 - 12) - | | +--------------- day of month (1 - 31) - | +-------------------- hour (0 - 23) - +------------------------- min (0 - 59) - -This library also supports a few macros: - -* `@yearly`, `@annually` - Run once a year, midnight, Jan. 1 - `0 0 1 1 *` -* `@monthly` - Run once a month, midnight, first of month - `0 0 1 * *` -* `@weekly` - Run once a week, midnight on Sun - `0 0 * * 0` -* `@daily`, `@midnight` - Run once a day, midnight - `0 0 * * *` -* `@hourly` - Run once an hour, first minute - `0 * * * *` +``` +* * * * * +- - - - - +| | | | | +| | | | | +| | | | +----- day of week (0-7) (Sunday = 0 or 7) (or SUN-SAT) +| | | +--------- month (1-12) (or JAN-DEC) +| | +------------- day of month (1-31) +| +----------------- hour (0-23) ++--------------------- minute (0-59) +``` + +Each part of expression can also use wildcard, lists, ranges and steps: + +- wildcard - match always + - `* * * * *` - At every minute. + - day of week and day of month also support `?`, an alias to `*` +- lists - match list of values, ranges and steps + - e.g. `15,30 * * * *` - At minute 15 and 30. +- ranges - match values in range + - e.g. `1-9 * * * *` - At every minute from 1 through 9. +- steps - match every nth value in range + - e.g. `*/5 * * * *` - At every 5th minute. + - e.g. `0-30/5 * * * *` - At every 5th minute from 0 through 30. +- combinations + - e.g. `0-14,30-44 * * * *` - At every minute from 0 through 14 and every minute from 30 through 44. + +You can also use macro instead of an expression: + +- `@yearly`, `@annually` - At 00:00 on 1st of January. (same as `0 0 1 1 *`) +- `@monthly` - At 00:00 on day-of-month 1. (same as `0 0 1 * *`) +- `@weekly` - At 00:00 on Sunday. (same as `0 0 * * 0`) +- `@daily`, `@midnight` - At 00:00. (same as `0 0 * * *`) +- `@hourly` - At minute 0. (same as `0 * * * *`) + +Day of month extra features: + +- nearest weekday - weekday (Monday-Friday) nearest to the given day + - e.g. `* * 15W * *` - At every minute on a weekday nearest to the 15th. + - If you were to specify `15W` as the value, the meaning is: "the nearest weekday to the 15th of the month" + So if the 15th is a Saturday, the trigger will fire on Friday the 14th. + If the 15th is a Sunday, the trigger will fire on Monday the 16th. + If the 15th is a Tuesday, then it will fire on Tuesday the 15th. + - However, if you specify `1W` as the value for day-of-month, + and the 1st is a Saturday, the trigger will fire on Monday the 3rd, + as it will not 'jump' over the boundary of a month's days. +- last day of the month + - e.g. `* * L * *` - At every minute on a last day-of-month. +- last weekday of the month + - e.g. `* * LW * *` - At every minute on a last weekday. + +Day of week extra features: + +- nth day + - e.g. `* * * * 7#4` - At every minute on 4th Sunday. + - 1-5 + - Every day of week repeats 4-5 times a month. To target the last one, use "last day" feature instead. +- last day + - e.g. `* * * * 7L` - At every minute on the last Sunday. Requirements ============