Almanack

Move a date by years, months, days and ticks. They are applied in that fixed order, which matters: a month then a day is not always the same landing as a day then a month. Adding days is always exact. policy decides what happens when the day does not exist in the target month: 'clamp' (default) moves to that month's last day, 'reject' refuses with an error, 'spill' carries the excess into the following month. Adding months to an intercalary date is refused, because those days sit between months; add days instead. 'ticks' moves within the day for a calendar that divides its day, carrying whole days as they fall. USE 'steps' FOR MORE THAN ONE MOVE: each step gives its own years, months, days and ticks, and its own date or the shared one, so a base date and a list of offsets is a single call rather than one per offset. Only the date is shared: a step states its own move in full, so a step naming no months moves by no months whatever the call around it says. Answers up to 1000 in one call, in the order given, as {count, ok, results}. Prefer this over one call per item: the spec travels once instead of once each.

When recurring events fall, and whether they land on each other. query 'next' gives the first occurrence after the date in 'after' (or on it when inclusive is true). query 'occurrences' gives every occurrence between start and end inclusive, capped at limit and at most 1000; 'truncated' says whether the list was cut short, so never read a truncated list as complete. query 'collisions' gives the days between start and end where two or more of the given events fall together, each naming what shares it — the question a calendar of festivals is really asking, and one to ask here rather than reason out in prose. An event is either a name the calendar defines or an event given inline: {'name':..,'type':'fixed','month':..,'day':..}, {'name':..,'type':'nth_weekday','month':..,'weekday':..,'n':..} or {'name':..,'type':'interval','anchor':{..},'every':N,'unit':'days'|'years'}. Pass one as 'event', or many as 'events' — which 'collisions' requires and which answers the other two queries for every event in a single call. A year in which an event's date does not exist produces no occurrence: a leap-day feast happens in leap years and not otherwise, and is never moved to a nearby day.

Which named periods of the year a date falls in — a season, a tide, a term. Answers with a list, not one: a calendar may declare several cycles of periods and a date sits in one of each, so seasons and festival tides come back together. Each answer says which day of the period it is and how long the period runs, which is how 'early autumn' becomes a comparison rather than a guess. An empty list is a legal answer and means the calendar's periods do not cover that day; validate_calendar_spec reports the gaps and overlaps in a whole cycle. Pass 'dates' for more than one. Answers up to 1000 in one call, in the order given, as {count, ok, results}. Prefer this over one call per item: the spec travels once instead of once each.

Which weekday a date falls on, as a 0-based index into the calendar's own week plus its name. Exact; never estimates. Returns weekday null when the date is an intercalary day the week does not count: those days sit outside the cycle and the week resumes after them exactly where it left off. Fails if the calendar defines no week rather than inventing a seven-day one. Pass 'dates' instead of 'date' for more than one. Answers up to 1000 in one call, in the order given, as {count, ok, results}. Prefer this over one call per item: the spec travels once instead of once each.

Convert between a calendar date, its day number, and its Gregorian date. Give exactly one of date, day_number, gregorian or one of their plurals dates, day_numbers, gregorians; all three forms come back, with whether the year is a leap year, how long it is, and any named period of the year the date falls in. USE THE PLURALS FOR MORE THAN ONE DATE: the calendar spec travels on every call, so fifteen dates in one call cost the spec once instead of fifteen times, and there is no reason to work an answer out by hand to save a round trip. Answers up to 1000 in one call, in the order given, as {count, ok, results}. Prefer this over one call per item: the spec travels once instead of once each. Exact arithmetic; never estimates. A date that does not exist in this calendar is refused with the real range, never rounded to a nearby day.

The distance between two dates. 'days' is the exact signed count (negative when end precedes start) and is always reliable. 'calendar' breaks the same distance into whole years, then whole months, then days, using the clamp policy, so adding that breakdown back to the start date with add_to_date returns the end date exactly. Give start_time and end_time and the answer also carries 'ticks', the signed distance in the calendar's finest unit of the day, and 'time', that distance as whole days plus a count per unit. Give both or neither: one alone is refused rather than measured from the start of the other day, which would be a moment you did not give — pass 0 if that is what you mean. Exact integer arithmetic; never estimates.

Write a date out to a pattern. pattern is either a name from the calendar's own 'formats' (names win) or a pattern written out. Tokens: {day} {day-name} {month} {month-name} {year} {era} {era-abbr} {era-year} {intercalary} {period}, plus one named for each unit the spec's 'day' block declares ({bell}), with an optional zero-pad width on the numeric ones as {day:2}. Write a literal brace as {{ or }}. The output is exactly reversible by parse_calendar_date with the same pattern, so use these two as a pair. Pass 'dates' instead of 'date' to write many to the same pattern, with 'times' alongside when each carries its own time. Answers up to 1000 in one call, in the order given, as {count, ok, results}. Prefer this over one call per item: the spec travels once instead of once each.

Every moon's phase on a date. 'fraction' is the exact position in the cycle, 0.0 at new and 0.5 at full, and is the number to compute with. 'phase' is only which named bucket that fraction falls in, and 'illumination' is the lit portion of the disc from 0.0 to 1.0. Computed in closed form from the moon's period and offset, not simulated and not astronomical: it is exactly what the spec describes. Measured at the start of the day; pass day_fraction 0.5 for midday, or 'time' to say where in the day exactly for a calendar whose spec divides its day. Give one or the other.

The nth given weekday of a month: the 3rd Tuesday, the last Friday. n is 1-based from the start of the month, or negative from the end (-1 is the last). Only days the week counts are considered. If the month has no such day the call fails naming how many there are; it never returns the nearest one instead. Exact; never estimates.

Read a written date back into a date. Strict, with no fuzzy matching of any kind: literal characters must match character for character, month, weekday, era and period names must be names this calendar actually defines, and a weekday or period written into the string must be one that date really falls on. A string that does not fit is an error naming what did not fit; it never returns a best guess. Use the same pattern that wrote the string. A pattern that wrote a time of day gives the time back too.

Draw one month of a calendar as an SVG grid, or a whole year on one sheet, and return the SVG itself. Columns come from the calendar's own week, so a ten-day week gets ten columns. Intercalary days belong to no month and never take a cell in the grid: the blocks either side of this month are drawn as a strip outside it, dashed when the week does not count them. Moons get a glyph per day, lit to that moon's phase, when the calendar defines any. Events use the same shape as render_timeline and are filtered to the days on this page, with at most 500 given and at most three shown per day before the rest become a count. Colours are assigned per color_key from the whole list before filtering, so a category keeps its colour across months. OMIT 'month' TO DRAW THE WHOLE YEAR on one sheet, every month side by side — for seeing at once whether festivals are evenly spread, which nine separate month pages do not show. A year sheet has no room for labels or moon glyphs, so each day carries its number and a dot per event, every dot holding its label in a <title>. Fully deterministic: the same arguments always produce byte-identical SVG. The output is static SVG and never contains script or style.

Draw a date range as a horizontal SVG timeline and return the SVG itself. Both ends of the range are included. Axis ticks choose their own granularity from the span — days, months or years — and year labels use the calendar's eras where it defines them, so a range crossing a descending era's boundary counts down to it and up again after it, ... 3, 2, 1 | 1, 2, 3 ... Era boundaries inside the range are drawn as labelled vertical rules. Each event is {'label':.., 'date':{..}} for a marker or {'label':.., 'start':{..}, 'end':{..}} for a bar, optionally with 'lane' (a row name) and 'color_key' (a category name picking an accent colour). AT MOST 500 EVENTS: more is refused with render.timeline.too_many_events rather than drawn partially. Labels never overlap; they stagger and then truncate with an ellipsis, and the full label is always in the marker's <title> whatever ends up drawn. theme is 'default', 'dark', or a theme object with all of font_family, background, axis, text and accents; colours must be #RGB or #RRGGBB and anything else is refused. Fully deterministic: the same arguments always produce byte-identical SVG, with no timestamps or generated ids in it. The output is static SVG and never contains script or style.

Scatter a number of dates across a span, for generating events. The seed is required and the draw is fully deterministic: the same calendar, span, count, seed and unique flag always give the same dates, on any machine. unique=true (default) draws without repeats and fails if count exceeds the number of days in the span. Results come back sorted.

How long each sun is up on a date, and between which times of day. THE CURVE IS DECLARED BY THE SPEC, NEVER INFERRED, and that is the point of this tool: a shortest day, a longest day and a solstice do not say what happens between them — a sinusoid and a straight line honour all three and disagree everywhere else, by nearly a whole bell at the quarter points — so the spec names the shape ('sinusoid', 'linear', or 'table' given point by point) and this evaluates it exactly. It is NOT astronomy: no latitude, no axial tilt, no orbit, and no attempt at plausibility. It is exactly what the calendar describes, the same promise moon_phases makes. 'rise' and 'set' sit either side of each sun's own noon, so several suns can be up at different hours; both are null when a sun is up all day or not at all, which 'always_up' and 'never_up' say. 'wraps' means a sun's span runs through the turn of the day. 'lit' is the UNION of every sun's span, not the sum: two suns sharing the sky make one lit stretch, and adding them would claim a day longer than it is. Each lit stretch is half-open, so its 'to' is the tick the light stops at and is never wrapped round: a sun up the whole day closes at one whole day, not at nought. A sun that does not keep to the year declares a 'period' in whole days and a dated 'epoch' instead of a solstice; its noon then drifts through the day once per cycle — on its own 'noon_period' where the spec gives one — and 'cycle' says where in its DAYLIGHT cycle the date falls (null for a sun that keeps to the year). Any number of suns. Fails rather than guessing if the calendar declares no suns, or no 'day' block to measure them in. Pass 'dates' for more than one. Answers up to 1000 in one call, in the order given, as {count, ok, results}. Prefer this over one call per item: the spec travels once instead of once each.

Check a calendar spec and list everything wrong with it. Returns structured errors and warnings; it never throws and never partially accepts a spec. Errors mean the spec is unusable; warnings mean it is legal but probably not what was meant (a leap rule that changes no year's length, a moon that cycles every few hours). Use this before any other tool when you have written or edited a spec yourself. It is the only tool that accepts a malformed spec. A key no block defines is one of the errors, and it names the fields that block does have, so this also answers what a block takes when you are unsure.