Skip to content

The reference calendar (cal)

timeglyph cal is a timezone/DST/leap-aware reference calendar for interpreting timestamps. Where the Unix cal prints day numbers, cal surfaces the temporal detail an examiner reasons about — timezone offsets and DST fold/gap days, leap-second days, ISO week and Julian Day numbering, GPS week, timestamp-format epoch boundaries, alternative calendars, and the moon's phase — for a day, a month, or a whole year.

Every number is computed, not looked up, and carries an independent oracle in the test suite (tests/cal.rs): ISO weeks and day-of-year against date, Julian Day Numbers against USNO, DST transitions against zdump, leap seconds against the IERS table (via hifitime), the moon against JPL/Meeus, and the equinox/solstice instants against published almanac values.

Usage

timeglyph cal                     # the current month, in UTC
timeglyph cal 2026-07             # a specific month
timeglyph cal 2026                # a whole year (with the season timeline)
timeglyph cal 2026-11-01          # one day, in full detail (with a moon disc)
timeglyph cal 2025-02-19T14:30    # a specific instant → the 時柱 for that hour
timeglyph cal 2026-11 --tz America/New_York   # zone-aware: DST folds/gaps flagged
timeglyph cal 2026 --tz Australia/Sydney      # southern-hemisphere seasons (Dec = summer)
timeglyph cal 2026-07 --json      # faithful, one record per day, for pipes

Flags: --tz <zone> (global; UTC by default), --week-start monday|sunday, --json.

The month grid

July 2026                UTC

      Mo  Tu  We  Th  Fr  Sa  Su
W27           1   2   3   4   5
W28   6   7   8   9  10  11  12
W29  13* 14  15  16  17  18  19
W30  20  21  22  23  24  25  26
W31  27  28  29  30  31

  * today   ^ DST gap   v DST fold   + leap second   e epoch   ~ rollover

The gutter is the ISO-8601 week number. One marker per day flags the forensically-salient conditions (highest precedence wins): today, a spring-forward gap day, a fall-back fold day, a leap-second day, a timestamp-format epoch day, or a fixed-width rollover. Markers are plain ASCII, so a piped or colourless view loses no information.

The day detail card

A single date prints every field: the week/epoch systems, timezone, leap/GPS, the moon as a shaded disc, the alternative calendars, and the season stated as early/mid/late.

2025-01-15  wednesday
  iso 2025-W03-3   doy 15/365   jdn 2460691   mjd 60690
  unix midnight 1736899200   offset 0s .. 0s   wall day 86400s
  leap 0 (UTC day 86400s)   gps week 2349

      @ @ @ @ @      Full Moon
    @ @ @ @ @ @ @    97% illuminated
   @ @ @ @ @ @ @ @   elongation 199.1deg
   @ @ @ @ @ @ @ @
   @ @ @ @ @ @ @ @
    @ @ @ @ @ @ @
      @ @ @ @ @

  農曆+干支暦 Lunisolar + Stem-Branch  十二月十六日 · 小寒
            甲丁甲庚
            辰丑申午
            年月日時
  中華民國 Republic of China  114年1月15日
  和暦 Japanese  令和7年1月15日
  बौद्ध संवत् Buddhist  15 Jan 2568 BE
  לוח עברי Hebrew  15 Tevet 5785
  هجري Islamic  15 Rajab 1446
  خورشیدی Persian  26 Dey 1403
  season    季冬 late winter (N. hemisphere; solar longitude 295.6deg)

The 農曆+干支暦 label and the bilingual alternative-calendar names match the timeglyph-lens overlay. The season is stated as the classical 孟/仲/季 × 春夏秋冬 plus early / mid / late — which third of the 90° season arc the Sun's longitude falls in — rather than an ASCII scene. The month view closes with an info panel (Chinese year + solar term, the mid-month moon, and each alternative calendar's year); the alternative-calendar labels are aligned into one column. The year view opens with the season timeline of astronomically-exact equinox/solstice dates.

Definitions and conventions

  • Dates are proleptic Gregorian everywhere, including the Julian Day Number. This matches how every timestamp format defines its epoch (FILETIME's 1601, MJD's 1858, SQL Server's 1900), so cal's JDN and a format epoch never disagree by the Julian/Gregorian cutover. cal 1582-10 therefore shows a full October; the historically-skipped Oct 5–14 exist proleptically.
  • Wall-day length is the elapsed real seconds between local midnights: 86 400 on an ordinary day, 82 800 (23 h) across a spring-forward gap, 90 000 (25 h) across a fall-back fold, and other values for sub-hour transitions (e.g. Lord Howe's 30-minute change → 88 200 s).
  • Leap-second days are derived from the change in the cumulative TAI−UTC offset across the UTC day (hifitime's IERS table), never a hardcoded date. Such a day's UTC length is 86400 + leap.
  • GPS week is the continuous week (not the 10-bit rollover value) containing the day's 00:00 UTC instant. GPST leads UTC by the current leap count, so a Sunday-00:00Z instant already falls in the new week.
  • Season boundaries are the astronomically exact instants the Sun's apparent longitude reaches 0/90/180/270° (the 春分/夏至/秋分/冬至 solar terms), from the stem-branch ephemeris — not fixed calendar dates. Which season a boundary opens depends on hemisphere: the December solstice opens winter in the north, summer in the south. The hemisphere is derived from the --tz zone — a named zone south of the equator (Australia/Sydney, Pacific/Auckland, America/Santiago) yields austral seasons automatically, from the tzdb zone1970.tab latitudes. UTC and fixed offsets carry no latitude, so they default to the northern hemisphere.
  • Moon phase uses the true geocentric elongation (Meeus ch. 48, including the Moon's ecliptic latitude and the real Sun/Moon distances), so the illuminated fraction is accurate near the quarters. It is an almanac-grade value, useful for corroborating night-time illumination in photo/CCTV/witness evidence.

Alternative calendars

With the default build, each day also carries the Chinese lunisolar date (in Chinese, e.g. 正月廿二日) and the four 干支 pillars — year, month, day, and hour (年月日時) — via the stem-branch ephemeris at the render-zone meridian. The day card stacks them as stems over branches over labels. For a bare date the hour pillar (時柱) is computed at the day's noon (午時); pass a time — cal 2025-02-19T14:30 — to get the 時柱 for that actual hour (the year/month/day pillars are unchanged). The solar term is shown as a period phrase — the bare term on its own day, else <term>後第<N>日 (e.g. 雨水後第七日) — so a day well past the term is not misread as its exact day. Behind the altcal feature, six further calendars come from ICU4X, each labelled with its native name and the English one, shown in order: 中華民國 Republic of China (ROC / Minguo, year = Gregorian − 1911), 和暦 Japanese (令和/平成/…), बौद्ध संवत् Buddhist (Gregorian + 543 BE), לוח עברי Hebrew, هجري Islamic (tabular civil), and خورشیدی Persian (Solar Hijri). Each carries a stable key (roc/japanese/…) in the --json record, and the timeglyph-lens overlay lets you toggle each one independently in its settings. All values appear in --json.