calendar.d.lua

---@meta _

---Weekday number (1-7) where 1 is Monday and 7 is Sunday.
---@alias mods.calendarWeekday
---| 1 Monday
---| 2 Tuesday
---| 3 Wednesday
---| 4 Thursday
---| 5 Friday
---| 6 Saturday
---| 7 Sunday

---Month number (1-12) where 1 is January and 12 is December.
---@alias mods.calendarMonth
---| 1  January
---| 2  February
---| 3  March
---| 4  April
---| 5  May
---| 6  June
---| 7  July
---| 8  August
---| 9  September
---| 10 October
---| 11 November
---| 12 December

---Day of the month (1-31).
---@alias mods.calendarMonthDay
---| 1  1st day of the month
---| 2  2nd day of the month
---| 3  3rd day of the month
---| 4  4th day of the month
---| 5  5th day of the month
---| 6  6th day of the month
---| 7  7th day of the month
---| 8  8th day of the month
---| 9  9th day of the month
---| 10 10th day of the month
---| 11 11th day of the month
---| 12 12th day of the month
---| 13 13th day of the month
---| 14 14th day of the month
---| 15 15th day of the month
---| 16 16th day of the month
---| 17 17th day of the month
---| 18 18th day of the month
---| 19 19th day of the month
---| 20 20th day of the month
---| 21 21st day of the month
---| 22 22nd day of the month
---| 23 23rd day of the month
---| 24 24th day of the month
---| 25 25th day of the month
---| 26 26th day of the month
---| 27 27th day of the month
---| 28 28th day of the month
---| 29 29th day of the month
---| 30 30th day of the month
---| 31 31st day of the month

---
---Calculate weekday alignments, leap years, and month lengths.
---
---> [!WARNING]
--->
---> This module is still under development and may not be stable.
---> The API is incomplete and may change in future versions.
---
---## Usage
---
---```lua
---local mods = require "mods"
---local cal = mods.calendar
---
---print(cal.weekday(2026, 3, 26)) --> 4
---```
---
---@class mods.calendar
---@field JANUARY    1
---@field FEBRUARY   2
---@field MARCH      3
---@field APRIL      4
---@field MAY        5
---@field JUNE       6
---@field JULY       7
---@field AUGUST     8
---@field SEPTEMBER  9
---@field OCTOBER   10
---@field NOVEMBER  11
---@field DECEMBER  12
---
---@field MONDAY    1
---@field TUESDAY   2
---@field WEDNESDAY 3
---@field THURSDAY  4
---@field FRIDAY    5
---@field SATURDAY  6
---@field SUNDAY    7
---
---Month names indexed from `1` to `12`.
---
---```lua
---print(cal.months[1])  --> January
---print(cal.months[12]) --> December
---```
---@field months mods.List<string>
---
---Weekday names indexed from `1` (Monday) to `7` (Sunday).
---
---```lua
---print(cal.days[1]) --> Monday
---print(cal.days[7]) --> Sunday
---```
---@field days mods.List<string>
---
---The default first weekday field.
---
---```lua
---print(cal.firstweekday) --> 1
---cal.firstweekday = cal.SUNDAY
---print(cal.firstweekday) --> 7
---```
---
---> [!NOTE]
--->
---> Reading or writing this property is equivalent to calling
---> `getfirstweekday()` or `setfirstweekday()`.
---
---@field firstweekday mods.calendarWeekday
local M = {}

---
---Return the default first weekday.
---
---```lua
---print(cal.getfirstweekday()) --> 1
---```
---
---> [!NOTE]
--->
---> This returns the same value as `cal.firstweekday`.
---
---@return mods.calendarWeekday firstWeekday
---@nodiscard
function M.getfirstweekday() end

---
---Set the default first weekday.
---
---```lua
---cal.setfirstweekday(cal.SUNDAY)
---```
---
---> [!NOTE]
--->
---> This updates the same value as
---> `cal.firstweekday = ...`.
---
---@param firstWeekday mods.calendarWeekday
function M.setfirstweekday(firstWeekday) end

---
---Iterate weekday numbers for one full week.
---
---```lua
---local weekdays = {}
---for day in cal.weekdays() do
---  weekdays[#weekdays + 1] = day
---end
---print(table.concat(weekdays, ", ")) --> "1, 2, 3, 4, 5, 6, 7"
---```
---
---@section Iterators
---@param firstWeekday? mods.calendarWeekday
---@return fun():mods.calendarWeekday iter
---@nodiscard
function M.weekdays(firstWeekday) end

---
---Return `true` for leap years.
---
---```lua
---print(cal.isleap(2024)) --> true
---```
---
---@section Calendar Calculations
---@param year integer
---@return boolean isLeap
---@nodiscard
function M.isleap(year) end

---
---Return the number of leap years from `y1` up to but not including `y2`.
---
---```lua
---print(cal.leapdays(2000, 2025)) --> 7
---```
---
---@section Calendar Calculations
---@param y1 integer
---@param y2 integer
---@return integer count
---@nodiscard
function M.leapdays(y1, y2) end

---
---Return weekday number where Monday is `1` and Sunday is `7`.
---
---```lua
---print(cal.weekday(2026, 3, 26)) --> 4
---```
---
---@section Calendar Calculations
---@param year integer
---@param month mods.calendarMonth
---@param day mods.calendarMonthDay
---@return mods.calendarWeekday weekday
---@nodiscard
function M.weekday(year, month, day) end

---
---Return the first weekday and number of days for a month.
---
---```lua
---local wday, ndays = cal.monthrange(2026, 2)
---print(wday, ndays) --> 7 28
---```
---
---@section Calendar Calculations
---@param year integer
---@param month integer
---@return mods.calendarWeekday weekday
---@return integer ndays
---@nodiscard
function M.monthrange(year, month) end

---Iterate `(year, month, day, weekday)` tuples for a full calendar grid.
---
---```lua
---local List = mods.list
---local cal = mods.calendar
---local str = mods.str
---
---local header = cal.weekheader(2)
---local lines = List({
---  str.center(("%s %d"):format(cal.months[cal.FEBRUARY], 2026), #header),
---  header,
---})
---
---local cells = List()
---for _, m, d, _ in cal.monthdays(2026, cal.FEBRUARY) do
---  cells:append(m == cal.FEBRUARY and ("%2d"):format(d) or "  ")
---  if #cells == 7 then
---    lines:append(cells:join(" "))
---    cells = List()
---  end
---end
---
---print(lines:join("\n"))
-----    February 2026
----- Mo Tu We Th Fr Sa Su
-----                    1
-----  2  3  4  5  6  7  8
-----  9 10 11 12 13 14 15
----- 16 17 18 19 20 21 22
----- 23 24 25 26 27 28
---```
---
---@section Iterators
---@param year integer
---@param month mods.calendarMonth
---@param firstWeekday? mods.calendarWeekday
---@return fun():year:integer,month:mods.calendarMonth,day:mods.calendarMonthDay,weekday:mods.calendarWeekday iter
---@nodiscard
function M.monthdays(year, month, firstWeekday) end

---
---Return the formatted weekday header string.
---
---```lua
---print(cal.weekheader(1, cal.SUNDAY)) --> "S M T W T F S"
---print(cal.weekheader(2, cal.SUNDAY)) --> "Su Mo Tu We Th Fr Sa"
---print(cal.weekheader(3, cal.SUNDAY)) --> "Sun Mon Tue Wed Thu Fri Sat"
---```
---
---@section Formatting
---@param width? integer
---@param firstWeekday? mods.calendarWeekday
---@return string header
---@nodiscard
function M.weekheader(width, firstWeekday) end

return M