Merge pull request #17 from fermyon/tpmccallum-patch-1

Add cron character explanation and give examples of different schedules

Author: tpmccallum

README.md

@@ -48,19 +48,53 @@ spin build --up
 
 ## Trigger Configuration
 
-The trigger type is `cron` and there are no application-level configuration options. 
+The trigger type is `cron`, and there are no application-level configuration options. 
 
 The following options are available to set in the [[trigger.cron]] section:
 
 | Name                  | Type             | Required? | Description |
 |-----------------------|------------------|-----------|-------------|
 | `component`           | string or table  | required  | The component to run on the schedule given in `cron_expression`. (This is the standard Spin trigger component field.) |
-| `cron_expression`     | string           | required  | The `cron` expresison describing the schedule on which to execute the component. |
+| `cron_expression`     | string           | required  | The `cron` expression describes the schedule for executing the component. |
+
+### Cron Expression Fields
+
+The `cron_expression` fields are as follows:
+
+```text
+#  ┌──────────── sec (0–59)
+#  |  ┌───────────── min (0–59)
+#  |  │  ┌───────────── hour (0–23)
+#  |  │  │  ┌───────────── day of month (1–31)
+#  |  │  │  │  ┌───────────── month (1–12)
+#  |  │  │  │  │  ┌───────────── day of week (0–6)
+#  |  │  │  │  │  |  ┌─────────────- year
+#  |  │  │  │  │  |  │
+#  |  │  │  │  │  |  │
+   *  *  *  *  *  *  * 
+```
+
+### Cron Expression Characters
+
+The `*` indicates that every value applies. For example, if `sec` is set to `*`, then every second will trigger execution.
+The `/` indicates increments. For example, if `sec` is set to `0/15`, then starting at `0`, the trigger will be executed every 15 seconds.
+The `,` indicates a list of values. For example, if `sec` is set to `2,8`, then the trigger will execute only on the 2nd and 8th seconds of every minute.
+The `-` indicates range. For example, if the `sec` is set to `5-10`, then the trigger will execute only on the 5th, 6th, 7th, 8th, 9th, and 10th seconds of each minute.
+The `0` indicates no execution. If the `sec` is set to `0`, then the trigger can only execute on higher field values such as `min`, `hour`, etc. The lowest second increment is 60 (one minute).
+
+Here is one example that combines a few of the fields mentioned above:
+
+```text
+sec   min   hour   day of month   month   day of week   year
+0     1/2   11,12  5-10           *       *             *
+```
+
+The above schedule of `0 1/2 11,12 5-10 * * *` will execute on the first minute and every subsequent 2 minutes during the 11th hour and the 12 hour (noon) on days 5 through 10 of every month (regardless of the day of the week) and this will repeat through every year.
 
 ## Building Cron Components
 
 Currently only a Rust SDK is supported for guest components. The `spin-cron-sdk` along with the [`spin_sdk` crate](https://docs.rs/spin-sdk) can be used to build cron components. The guest code must have a function decorated with the `#[cron_component]` macro. See `guest/src/lib.rs` for an example in rust. 
 
 The signature of the function must be `fn handle_cron_event(metadata: Metadata) -> Result<(), Error>`.
 
-The `Metadata` object contains a single field `timestamp` which contains the duration since 00:00:00 UTC on 1 January 1970 (the Unix epoch) in seconds.
+The `Metadata` object contains a single field `timestamp` which contains the duration since 00:00:00 UTC on 1 January 1970 (the Unix epoch) in seconds.