Commitf85888dcRecorded18 Mar 2026Repositorysigil-later

Add README with usage docs and API reference

Changed
 README.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
Diff
README.mdadded
@@ -0,0 +1,81 @@
+1
# sigil-later
+2
+3
Time-based task scheduling for [Sigil](https://codeberg.org/sigil/sigil). Provides cron expression parsing and an async task runner with cancellation.
+4
+5
## Usage
+6
+7
### Parsing & Matching
+8
+9
`(sigil later)` provides pure functions for working with cron expressions:
+10
+11
```scheme
+12
(import (sigil later))
+13
+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
```
+18
+19
Cron format: `minute hour day-of-month month day-of-week`
+20
+21
Supports `*`, numbers, ranges (`1-5`), lists (`1,3,5`), steps (`*/5`, `1-10/2`), named days (`MON-FRI`), and named months (`JAN-DEC`).
+22
+23
### Async Task Runner
+24
+25
`(sigil later runner)` spawns goroutines that sleep until the exact fire time. Each task returns a cancellable handle.
+26
+27
```scheme
+28
(import (sigil later runner) (sigil async))
+29
+30
(with-async
+31
;; Recurring: fires every 5 minutes
+32
(later-every! "*/5 * * * *" "check-inbox"
+33
(lambda () (check-inbox)))
+34
+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))
+40
+41
;; One-time: fires at a specific timestamp
+42
(later-at! 1742290200 "deadline"
+43
(lambda () (notify-deadline))))
+44
```
+45
+46
## API
+47
+48
### `(sigil later)` — Parsing
+49
+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 |
+56
+57
### `(sigil later runner)` — Execution
+58
+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 |
+66
+67
## Building
+68
+69
```bash
+70
sigil build --redirects dev-redirects.sgl
+71
```
+72
+73
## Testing
+74
+75
```bash
+76
sigil test --redirects dev-redirects.sgl
+77
```
+78
+79
## License
+80
+81
BSD-3-Clause