# Cron Expression Syntax

MoonCron supports two layouts:

```text
# Standard 5-field format
minute hour day-of-month month day-of-week

# Extended 6-field format
second minute hour day-of-month month day-of-week
```

## Fields

| Field | Range | Special characters |
| --- | --- | --- |
| Second | 0-59 | `*` `,` `-` `/` |
| Minute | 0-59 | `*` `,` `-` `/` |
| Hour | 0-23 | `*` `,` `-` `/` |
| Day of month | 1-31 | `*` `,` `-` `/` |
| Month | 1-12 | `*` `,` `-` `/` |
| Day of week | 0-7 | `*` `,` `-` `/` |

For day of week, `0` and `7` both mean Sunday; `1` through `6` mean Monday through Saturday.

## Operators

### Wildcard (`*`)

Matches every valid value:

```text
* * * * *       # Every minute
* * * * * *     # Every second
```

### Value

Matches one value:

```text
30 * * * *      # At minute 30
0 30 * * * *    # At second 0, minute 30
```

### List (`,`)

Matches any listed value:

```text
0,15,30,45 * * * *
0 8,12,16 * * *
```

### Range (`-`)

Matches an inclusive range:

```text
0 9-17 * * *
0 0 1-7 * *
```

### Step (`/`)

Matches values at regular intervals:

```text
*/15 * * * *
0 */2 * * *
```

### Range with step

Combines a range and step:

```text
10-50/10 * * * *
0 9-17/2 * * *
```

## Aliases

Aliases expand to 5-field expressions:

| Alias | Equivalent | Description |
| --- | --- | --- |
| `@hourly` | `0 * * * *` | At minute 0 of every hour |
| `@daily` | `0 0 * * *` | At midnight every day |
| `@midnight` | `0 0 * * *` | Same as `@daily` |
| `@weekly` | `0 0 * * 0` | At midnight every Sunday |
| `@monthly` | `0 0 1 * *` | At midnight on the first day of each month |
| `@yearly` | `0 0 1 1 *` | At midnight on January 1 |
| `@annually` | `0 0 1 1 *` | Same as `@yearly` |

## Day-of-month and Day-of-week

When both day-of-month and day-of-week are restricted, MoonCron follows traditional cron OR semantics: a time matches when either field matches. When one field is `*`, the restricted field controls the match.

## Examples

```text
*/5 * * * *            # Every 5 minutes
0 8 * * *              # Every day at 08:00
0 9 * * 1-5            # Every weekday at 09:00
*/15 9-18 * * 1-5      # Every 15 minutes during weekday work hours
0 0 29 2 *             # Midnight on February 29
30 */5 * * * *         # At second 30 of every fifth minute
```

## Unsupported extensions

MoonCron v0.1.4 does not support:

- Quartz operators `L`, `W`, or `#`
- A year field
- Timezone identifiers

## Error Messages

Invalid input returns a `CronError` with the affected field and constraint:

```text
61 * * * *          -> invalid minute value 61: expected 0..59
* 25 * * *          -> invalid hour value 25: expected 0..23
*/0 * * * *         -> step value cannot be 0 in field 'minute'
1--5 * * * *        -> invalid range syntax in field 'minute'
1,,5 * * * *        -> invalid syntax in field 'minute'
abc * * * *         -> invalid character in field 'minute'
* * * * * * *       -> expected 5 or 6 fields but got 7
```