Documentation
¶
Overview ¶
Package cadence reads a Cadence: §10's five-field cron grammar, and both halves of the gloss every surface renders one through — the phrase, which states the times of day, the days and the months the expression selects, and the rate, which states how often that comes to in runs per month.
It is a package rather than a function inside a page because three surfaces consume it and none of them owns it: a review's header and its `FLAGS` row (§8), `THE CODE MOVED`'s `cadence` row (§8), and `project`'s rows (§9). Wherever a Cadence renders, the gloss renders with it, and there is no surface exempt (ADR-0005, ADR-0021, ADR-0063) — a rule that is total is one no consumer may hold a second copy of.
**What it reads and what it refuses.** Nothing here refuses an artefact or fails a `check`: what the package answers is whether an expression is one the grammar admits, and — where it is not — what is wrong with it. Read is the first question and Fault the second, and they are two doors onto one reader because §12's `cadence-malformed` and a surface's gloss are two consumers of the same closure. A surface handed no gloss renders none rather than inventing a fallback for it; a check handed a fault cites it (§10, §12).
**What it never reads.** No clock, no calendar of record, and nothing about the environment it runs in (ADR-0066). Both halves are a function of the five fields and of nothing else, so a laptop and a runner render the same gloss for the same artefact forever.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Facts ¶
Facts are the three, in the order every surface renders them: the default-branch fact, then — where the minute field selects more than one value — the within-the-hour one, then — where it selects `0` — the hour-boundary one. The order is fixed here because no surface sorts them and every surface renders the same set — the three that render a gloss today, and `project`'s rows, which are the fourth (cadence.go).
The order is **decreasing blast radius**, which is what makes it derivable rather than remembered, and what decided where the second one went in: the branch fact says the Cadence may not fire at all, the within-the-hour one says most of its occurrences will not, and the hour-boundary one says one of them may be late. A reader who reads one line reads the largest.
An expression outside §10's grammar carries none. The facts render beside a gloss and there is no gloss for one the grammar does not admit, so the empty answer is the same answer Read gives, reached the same way — and a readable expression always carries at least the default-branch fact, so nothing but an unreadable one is ever empty.
func Fault ¶
Fault is that same reading asked the other way: what is wrong with an expression the grammar does not admit. It answers malformed=false for every expression Read glosses, and for one it declines, the reason — one sentence naming the field and the text at fault, so a reader handed the code does not have to search five fields for the one that is wrong.
The reason is the whole of what this package contributes to the problem. `cadence-malformed`, the file, the line and the column are the check's own (§12): a reader that named the code here would be one half of a problem written twice, and this package refuses nothing.
Types ¶
type Gloss ¶
type Gloss struct {
// Expression is the Cadence exactly as the artefact wrote it. It is the
// one member this package does not derive.
Expression string
// Phrase is the time, the day and the month clauses, in that order.
Phrase string
// Rate is the number the page renders, at the two significant figures
// §10 rounds to — the value a `rate` key on the wire carries.
Rate float64
// RateText is that number rendered: the `≈` where it was rounded, the
// digits, and the unit fixed at runs per month.
RateText string
}
Gloss is one Cadence in its second reading: the expression as the artefact wrote it, the phrase, and the rate in the two forms one rounding produces.
Rate and RateText are one number and not two facts. §10 fixes that the wire carries the number the page renders, rounded once, rather than the unrounded value beside a rounded rendering — which would be one derived fact in two representations that can disagree. They are derived together here so that no consumer is in a position to round it a second time.
The composed line — the phrase, the rate and whatever a surface places beside them — is the surface's own. How the parts are arranged is the surface's, and what they are is not (§10).
func Read ¶
Read is one expression read as a Gloss. It answers ok=false where the expression is not one §10's grammar admits — the wrong number of fields, an item form that is not one of the four, a value outside its field's span, or a range that runs backwards. That is not a refusal: `cadence-malformed` is the check that declines such an artefact (internal/artefact), and what a surface does with an unreadable expression is render no gloss and go on.
Source Files