README.md — sigil-later

1# sigil-later

Time-based task scheduling for [Sigil](https://codeberg.org/sigil/sigil). Provides cron expression parsing and an async task runner with cancellation.

5## Usage

7### Parsing & Matching

9`(sigil later)` provides pure functions for working with cron expressions:

11```scheme

12(import (sigil later))

14(let ((sched (parse-cron-string "*/5 * * * *")))

15 (later-matches? sched (current-second)) ; true if minute is 0, 5, 10...

16 (later-next sched (current-second))) ; next matching timestamp

17```

19Cron format: `minute hour day-of-month month day-of-week`

Supports `*`, numbers, ranges (`1-5`), lists (`1,3,5`), steps (`*/5`, `1-10/2`), named days (`MON-FRI`), and named months (`JAN-DEC`).

23### Async Task Runner

25`(sigil later runner)` spawns goroutines that sleep until the exact fire time. Each task returns a cancellable handle.

27```scheme

28(import (sigil later runner) (sigil async))

30(with-async

31 ;; Recurring: fires every 5 minutes

32 (later-every! "*/5 * * * *" "check-inbox"

33 (lambda () (check-inbox)))

35 ;; One-time: fires in 1 hour

36 (let ((handle (later-after! 3600 "reminder"

37 (lambda () (send-reminder)))))

38 ;; Cancel before it fires:

39 (later-cancel! handle))

41 ;; One-time: fires at a specific timestamp

42 (later-at! 1742290200 "deadline"

43 (lambda () (notify-deadline))))

44```

46## API

48### `(sigil later)` — Parsing

50| Procedure | Description |

51|-----------|-------------|

52| `parse-cron-string` | Parse a 5-field cron string into a schedule |

53| `later-matches?` | Test if a timestamp matches a schedule |

54| `later-next` | Find the next matching timestamp after a given time |

55| `later-schedule?` | Type predicate |

57### `(sigil later runner)` — Execution

59| Procedure | Description |

60|-----------|-------------|

61| `later-every!` | Schedule a recurring task (cron string) |

62| `later-after!` | Schedule a one-time task after N seconds |

63| `later-at!` | Schedule a one-time task at a Unix timestamp |

64| `later-cancel!` | Cancel a scheduled task |

65| `later-handle?` | Type predicate for task handles |

67## Building

69```bash

70sigil deps install

71sigil build

72```

74## Testing

76```bash

77sigil test

78```

80## License

82BSD-3-Clause