Permalink
Browse files

Revamed documentation

  • Loading branch information...
1 parent 867a130 commit 278fb39ca22d1f90cb067a48147f56801df752dc @ericpruitt committed Dec 15, 2010
Showing with 72 additions and 44 deletions.
  1. +4 −0 CHANGELOG
  2. +1 −1 cronex.py
  3. +66 −42 doc/SYNTAX
  4. +1 −1 test/test_cronex.py
View
4 CHANGELOG
@@ -1,5 +1,9 @@
CHANGELOG
+2010.12.14; Tuesday
+ Fixed mis-spelling of "annually" and rewrote much of the SYNTAX
+ documentation.
+
2010.12.07; Tuesday
Fixed bug in which wrap-around ranges sometimes skip values.
View
2 cronex.py
@@ -64,7 +64,7 @@ def zip(*args):
DEFAULT_EPOCH = (1970, 1, 1, 0, 0, 0)
SUBSTITUTIONS = {
"@yearly": "0 0 1 1 *",
- "@anually": "0 0 1 1 *",
+ "@annually": "0 0 1 1 *",
"@monthly": "0 0 1 * *",
"@weekly": "0 0 * * 0",
"@daily": "0 0 * * *",
View
108 doc/SYNTAX
@@ -1,52 +1,76 @@
-If you are familiar with cron, skip down to the section titled "PERIODIC," and
-consider reading the last half of "RANGES." Everything else is standard
-"man 5 crontab" information that probably isn't worded as well as in the man
-page.
-
-FIELDS
- Cron fields must be defined in the following order: minute, hour, day of
- the month, month, and day of the week. All fields permit arbitrary listing
- of values, ranges, wild-cards, steps and periodicity. In the field for
- days of the week, 0 represents Sunday and 6 Saturday. The months and days
- of the week fields permit using three letter abbreviations such as "dec"
- for December and "tue" for Tuesday in place of numbers. All abbreviations
- are case insensitive.
-
- Lone integers can be specified for each field, or multiple values can be
- used by separating them with commas. In the field representing days of the
- month, "5,10,25" would represent the 5th, 10th and 25th day of each month.
-
-RANGES
- Ranges are defined with a hyphen separating the initial and terminal
- values. In the hour field, "6-14" would mean all from 6:00am to 2:00pm.
- All ranges are inclusive of both values. If the first value is greater
- than the second value, this will be interpreted to mean the range should
- wrap-around. If "10-2" were specified in the months field, it would be
- interpreted to mean October, November, December, January and February.
-
-WILD-CARDS
+If you are familiar with cron, skip down to the section titled "REPEATERS."
+In this implementation, ranges wrap around: 22-2 in the hours field is the
+same as "22,23,0,1,2." Everything else is standard "man 5 crontab."
+
+Each cron trigger is specified with a combination of five white-space
+separated fields that dictate when the event should occur. In order the fields
+specify trigger times for minutes past the hour, hour of the day, day of the
+month, month, and day of the week.
+
+ .--------------- minute (0 - 59)
+ | .------------ hour (0 - 23)
+ | | .--------- day of month (1 - 31)
+ | | | .------ month (1 - 12) or Jan, Feb ... Dec
+ | | | | .---- day of week (0 - 6) or Sun(0 or 7), Mon(1) ... Sat(6)
+ V V V V V
+ * * * * * command to be executed / trigger comment
+
+There are four ways of specifying valid values for each field, all of which
+can be combined with each other using commas. There are ranges, wild-cards,
+steps, and repeaters. Repeaters are a non-standard addition to cron
+expressions that allow specification of events with arbitrary periods.
+
+If the the hour, minute, and month of a given time period are valid values as
+specified in the trigger and _either_ the day of the month _or_ the day of the
+week is a valid value, the trigger fires.
+
+RANGES AND WILD-CARDS
+ Ranges specify a starting and ending time period. It includes all values
+ from the starting value to and including the ending value.
+
Wild-cards, indicated with a "*", in a field represents all valid values.
- It is the same as 0-59 for minutes, 0-23 for hours, 1-31 for days, 1-12
- for months and 0-6 for weekdays.
+ It is _almost_ the same as specifying the range 0-59 in the minutes field,
+ 0-23 in the hours, 1-31 in days, 1-12 in months and 0-6 for weekdays.
+
+ The following cron expression is triggered every day at noon from June
+ through September:
+
+ 0 12 * 6-9 * * remind "Walk the ducks"
+
+ If the day of the week field is a wild card, but the day of the month is
+ an explicit range, the day of the week will be ignored and the trigger
+ will only be activated on the specified days of the month. If the day of
+ the month is a wild card, the same principal applies.
+
+ This expression is triggered every week day at 4:00 PM: "0 16 * * 1-5"
+
+ This one is triggered the first nine days of the month: "0 16 1-9 * *"
+
+ This one is triggered every day for the first week, but only on Saturdays
+ thereafter: "0 16 1-7 * 6"
STEPS
Steps are specified with a "/" and number following a range or wild-card.
When iterating through a range with a step, the specified number of values
will be skipped each time. "1-10/2" is the functional equivalent to
"1,3,5,7,9".
-PERIODIC
- In standard cron format, an approximation to trigger an event every 10
- days might look like this: "0 0 */10 * *". This works fine for January:
- The trigger is active on January 1st, 11th, and 31st; but in February, the
- trigger will be active on February 1st, far ahead of schedule. One
- "solution" would be to instead use "0 0 10,20,30 * *", but this still does
- not produce an event consistently every 10 days. This is the problem that
- periodicity addresses. Periodicity is represented as a "%" followed by the
- length of each period. The length of the period can be outside the bounds
- normal ranges of each field. "0 0 %45 * *" would be active every 45 days.
- All periodicities are calculated starting from the epoch and are
- independent of each other.
+ The following cron expression is triggered on the first day of every
+ quarter (Jan., Apr., ... Oct.) at midnight:
+
+ 0 0 1 */2 * * delete log.txt
+
+REPEATERS
+ Repeaters cause an event to trigger after arbitrary periods of time from a
+ given moment which will be hitherto referred to as the epoch. By default,
+ the epoch is January 1st, 1970 at 0:00. Triggers in different fields
+ operate independently of each other: "%10 %10 * * *" would trigger at
+ 00:00, 00:10, ... 00:50, 10:00, 10:10, etc...
+
+ The following cron expression is triggered at noon on the 10th every 5
+ months:
+
+ 0 12 10 %5 * Something amazing happens at noon...
SPECIAL SYMBOLS
There are three additional special symbols: "L", "W" and "#".
@@ -80,7 +104,7 @@ SPECIAL STRINGS
String Equivalent
------ ----------
@yearly 0 0 1 1 *
- @anually 0 0 1 1 *
+ @annually 0 0 1 1 *
@monthly 0 0 1 * *
@weekly 0 0 * * 0
@daily 0 0 * * *
View
2 test/test_cronex.py
@@ -25,7 +25,7 @@
class test_testedmodule(unittest.TestCase):
def test_substitution(self):
testcases = [("@yearly", "0 0 1 1 *"),
- ("@anually", "0 0 1 1 *"),
+ ("@annually", "0 0 1 1 *"),
("@monthly", "0 0 1 * *"),
("@weekly", "0 0 * * 0"),
("@daily", "0 0 * * *"),

0 comments on commit 278fb39

Please sign in to comment.