minetest_calendar/API.md

# Calendar API
This is the API documentation for the Calendar mod.

## Concepts
### Total days
Most functions use `total_days` to query the current date. This number is the
number of total elapsed days. You can get the 'elapsed days' number for today
in Minetest with `minetest.get_day_count()`.

### Ordinal and cardinal numbers
Cardinal number basically means the counting starts at 0.
Think of it as counting the number of elapsed days/months/years.

There are also ordinal numbers, which means the counting starts at 1.
This is for expressions like “1st January”.

Real calendars usually use ordinal numbers.

The calendar mod uses cardinal numbers internally to store the date internally,
this is only done to make calculations a bit simpler.
`total_days` is also a cardinal number.

## Calendar configiguration
In `gameconfig.lua`, there several variables that customize the calendar:

* `calendar.MONTH_DAYS`: Days in a month
* `calendar.month_names`: List of month names
* `calendar.month_names_short`: List of short month names
* `calendar.weekday_names`: List of weekday names
* `calendar.weekday_names_short`: List of short weekday names
* `calendar.FIRST_WEEK_DAY`: Cardinal number of the weekday that
                             marks the beginning of a week
                             and the calendar

By default, a year has 12 months with 30 days each,
the months are January to December,
the week has 7 weekdays from Monday to Sunday, starting at Monday.

For convenience, there are also these shortcuts, derived from the other values:
* `calendar.MONTHS`: Number of months in a year
* `calendar.WEEK_DAYS`: Number of days in a week
* `calendar.YEAR_DAYS`: Number of days in a year

## Functions

### `calendar.get_date(total_days, ordinal)`
Returns 4 values: days, months, years and days in year (in that order)

* `total_days`: Number of elapsed days (default: today)
* `ordinal`: if `true`, use ordinal numbers
             if `false`, use cardinal numbers
             default: false

## `calendar.get_weekday(total_days)`
Returns cardinal weekday number for given day.

* `total_days`: Number of elapsed days (default: today)

### `calendar.get_date_string(format, total_days)`
Returns the game date as a human-readable string

* `format`: Optional tokenized string to represent the game date
            Default: `"%Y years, %M months, %D days"`
* `total_days`: Number of elapsed days (default: today)

The tokenized string may include one or more date specifiers:

Cardinal values:
* `%Y`: Elapsed years in epoch
* `%M`: Elapsed months in year
* `%D`: Elapsed days in month
* `%J`: Elapsed days in year

Ordinal values:
* `%y`: Current year of epoch
* `%m`: Current month of year
* `%d`: Current day of month
* `%j`: Current day of year

Other:
* `%b`: Full name of current month
* `%h`: Short name of current month
* `%z`: Literal percent sign

### `calendar.register_holiday(def)`

Register a holiday. A holiday is just a special named day in a calender and
can be used for whatever you like: Actual holidays, special events, reminders,
whatever.
By default, holidays will be marked in the graphical calendar.
Holidays can be queried with `calendar.get_holidays`.

* `def`: Holiday definition. A table with these fields:
    * `name`: Human-readable holiday name
    * `type`: type of holiday, determines other arguments
    * Arguments when `type=="monthday"`:
        * `days`: Cardinal month day on which the holiday occurs
        * `months`: Cardinal month on which the holiday occurs
        * `years`: (optional) Cardinal year on which the holiday occurs. If not set, occurs every year
    * Arguments when `type=="custom"`:
        * `is_holiday`: Function that takes total days as parameter and must
                        return true if it's a holiday and false if not.
                        Try to keep your calculations as simple as possible

#### Examples
```
-- First day of every year
calendar.register_holiday({
	name = "New Year's Eve",
	type = "monthday",
	days = 0,
	months = 0
})

-- First Sunday in May
calendar.register_holiday({
	name = "Mother's Day",
	type = "custom",
	is_holiday = function(total_days)
		local d, m, y = calendar.get_date(total_days)
		local wday = calendar.get_weekday(total_days)
		return wday == 6 and m == 4 and d <= 6
	end,
})
```

### `calendar.get_holidays(total_days)`
Returns table of all holidays for the given day.

Each table value returns a reference to holiday definition that was
used in `calendar.register_holiday`.

* `total_days`: Number of elapsed days (default: today)



### `calendar.show_calendar(player_name, settings, wanted_months, wanted_years)`
Display a graphical calendar to player. It shows the days of a single month
with one numbered box per day. Also, holidays and the current day can be marked and
get a tooltip.

* `player_name`: Named of player
* `settings`: Table to customize calendar:
    * `ordinal`: If `true`, use ordinal numbers, otherwise, use cardinal numbers (default: `false`)
    * `show_weekdays`: If `true`, show weekdays and arrange the day boxes to weekdays (default: `true`)
    * `show_today`: If `true`, mark today (default: `true`)
    * `show_holiday`: If `true`, mark holidays (default: `true`)
    * `changable`: Which controls are available:
        * `"full"`: Can change year and month (default)
        * `"months"`: Can change month only
        * `"none"`: Can't change anything
    * `today_button`: Whether to show the 'Today' button (default: `true`)
                      Note: If `changable=="none"`, the 'Today' button is never shown
* `wanted_months`: Which cardinal calendar month to show (default: current one)
* `wanted_years`: Which cardinal calendar year to show (default: current one)
* `caption_format`: Optional format information to change the calendar caption.
                    Is a table with the following fields:
                    [1]: Format string with `minetest.translate`-style placeholders (from Minetest 5.0.0)
                    [2]: Translator domain for `minetest.translate`
                    [3]: and further: Parameters for the format string. For each parameter, use
                         a placeholder from `calender.get_date_string`.

Example for `caption_format`:

    { N("@1, year @2"), "mymod", "%b", "%Y" }

Will resolve to e.g. "January, Year 1".
`N` is a dummy function `function(s) return s end` that is used for the translation collector
script.