ingraph_codegen/cron.rs
1//! THE CRON SEAM, expansion side: is this a calendar expression, and is that a zone?
2//!
3//! # The seam exists because the implementation was temporary — and it has been replaced
4//!
5//! The ruling that put cron in v1 said what rides underneath it: a third-party crate FIRST, and the
6//! user's own implementation later. The later has arrived. What changed is the crate the two
7//! functions below call; what did not change is a single word an author writes or a single meaning a
8//! schedule has — which is what the seam was built to make possible, and this swap is the
9//! measurement that it did.
10//!
11//! There are TWO halves of the seam in the workspace, one per crate, because the build order forbids
12//! one: `ingraph` cannot reach this crate (it expands through the derive, which is built on it), so
13//! the runtime's own half lives in `ingraph::drive`. A swap touches both, and they are written to be
14//! read together.
15//!
16//! # What is underneath, and what it costs
17//!
18//! **`cronp`** — `no_std`, `no_alloc`, and NO dependency at all in the configuration this asks for.
19//! It parses into a bitset per field, takes its DIALECT as a type parameter, and refuses with a
20//! [`ParseError`](cronp::ParseError) carrying a byte [`Span`](cronp::Span). The dialect is
21//! [`Vixie`](cronp::Vixie), whose own constants are exactly the pins this framework had been
22//! stating by hand: five fields, no seconds, no year, and dom/dow the classic
23//! [`Union`](cronp::DomDowRule::Union).
24//!
25//! It EVALUATES nothing, which is the property this half wants most: an expansion-time check that
26//! computed a next-due would be a check whose answer depended on the machine the build ran on. The
27//! previous crate had to be told to fall back to UTC for exactly that reason; there is now nothing
28//! to tell.
29//!
30//! # What this half checks, and what it deliberately does not
31//!
32//! The FIELDS, the EXPRESSION, and the zone's NAME. It does not compute a next-due and it must not:
33//! the zone a schedule runs in is the one where the program RUNS, and expansion happens wherever the
34//! build happens. The zone name is checked separately, and only where this machine HAS a database to
35//! check it against.
36//!
37//! # The refusal quotes the expression under a caret
38//!
39//! The span is spent rather than the sentence alone. A reader is shown the text they wrote with the
40//! offending run marked, which is what a compiler diagnostic does and what the previous crate's own
41//! rendering happened to give — so the swap is a strict keep rather than a trade.
42
43use cronp::{Schedule, Vixie};
44
45/// How many fields a cron expression has here: the classic five — minute, hour, day of month,
46/// month, day of week.
47///
48/// Checked HERE rather than left to the crate, and the reason survives the swap even though the
49/// dialect now states it too: [`Vixie::MIN_FIELDS`](cronp::Dialect::MIN_FIELDS) is five and its
50/// `MAX_FIELDS` is five as well, so the crate would refuse a sixth field on its own — but it would
51/// refuse it as a PARSE error, and the useful sentence here is that a timezone is not a sixth field
52/// because there is a word for it. One rule, said by the party that knows why.
53pub const FIELDS: usize = 5;
54
55/// Read `expression` as a calendar expression, and `zone` as an IANA name where one was written.
56///
57/// # Errors
58///
59/// The reason, ready to be quoted into a refusal by the front end that holds the span. A parse
60/// refusal carries the expression with the offending run under a caret; the two rules this module
61/// owns say themselves.
62pub fn check(expression: &str, zone: Option<&str>) -> Result<(), String> {
63 let written = expression.split_ascii_whitespace().count();
64 if written != FIELDS {
65 return Err(format!(
66 "a cron expression here is the classic {FIELDS} fields — minute, hour, day of month, month, \
67 day of week — and this one has {written}. A timezone is not a sixth field: it is the `tz = \
68 \"<IANA>\"` word beside this one, or the system's zone where nothing said otherwise"
69 ));
70 }
71
72 Schedule::<Vixie>::parse(expression).map_err(|refusal| caret(expression, &refusal))?;
73
74 match zone {
75 Some(zone) => zone_exists(zone),
76 None => Ok(()),
77 }
78}
79
80/// A parse refusal with the expression under it and a caret on the offending run.
81///
82/// Written out rather than taken from the crate, which reports the span and leaves the quoting to
83/// whoever holds the text. Both halves of the seam render it the same way and neither can share the
84/// other's copy — the build order again — so the two are kept identical by
85/// `the_two_halves_render_one_caret`, one file over in `ingraph`.
86///
87/// The caret is at least one column wide, because an empty span is a real answer: a parser that ran
88/// out of input points AT the end, and a marker with no width would point at nothing.
89fn caret(expression: &str, refusal: &cronp::ParseError) -> String {
90 let span = refusal.span();
91 // BYTE offsets from the parser, COLUMNS on the page. They differ the moment an expression carries
92 // a non-ASCII byte — which a garbage one may — so the pad is counted in characters over the text
93 // actually printed rather than assumed equal to the offset.
94 let start = expression
95 .get(..span.start())
96 .map_or(0, |before| before.chars().count());
97 let width = expression
98 .get(span.start()..span.end())
99 .map_or(1, |marked| marked.chars().count().max(1));
100 format!(
101 "{refusal}\n {expression}\n {pad}{caret}",
102 pad = " ".repeat(start),
103 caret = "^".repeat(width),
104 )
105}
106
107/// Whether `zone` is a name this machine's time zone database has.
108///
109/// A TYPO CHECK, and it is written to be one rather than a portability trap. A machine with no
110/// database refuses NOTHING here: `America/New_York` is a valid declaration whether or not the
111/// container that compiled it shipped a `zoneinfo`, and the runtime is where the zone is actually
112/// needed. So the absence of a database is detected and the check stands down.
113fn zone_exists(zone: &str) -> Result<(), String> {
114 if jiff::tz::TimeZone::get(zone).is_ok() {
115 return Ok(());
116 }
117 if jiff::tz::db().available().next().is_none() {
118 return Ok(());
119 }
120 Err(format!(
121 "`{zone}` is not a time zone this machine's database has — the word takes an IANA name, as in \
122 `tz = \"America/New_York\"`"
123 ))
124}
125
126#[cfg(test)]
127mod tests;