API.md

   1 # Calendar API
   2 This is the API documentation for the Calendar mod.
   3
   4 ## Concepts
   5 ### Total days
   6 Most functions use `total_days` to query the current date. This number is the
   7 number of total elapsed days. You can get the 'elapsed days' number for today
   8 in Minetest with `minetest.get_day_count()`.
   9
  10 ### Ordinal and cardinal numbers
  11 Cardinal number basically means the counting starts at 0.
  12 Think of it as counting the number of elapsed days/months/years.
  13
  14 There are also ordinal numbers, which means the counting starts at 1.
  15 This is for expressions like “1st January”.
  16
  17 Real calendars usually use ordinal numbers.
  18
  19 The calendar mod uses cardinal numbers internally to store the date internally,
  20 this is only done to make calculations a bit simpler.
  21 `total_days` is also a cardinal number.
  22
  23 ## Calendar configuration
  24 Before calling any other function, you probably want to configure the calendar first.
  25 Call `calendar.config` to do so. This is not required, however, the calendar
  26 has a default configuration:
  27
  28 By default, ayear has 12 months with 30 days each,
  29 the months are January to December,
  30 the week has 7 weekdays from Monday to Sunday, starting at Monday.
  31
  32 ### `calendar.config(config)`
  33 Configure calendar. Call this function before any other function.
  34
  35 `config` is a table with the following fields (all fields are optional):
  36
  37 * `MONTH_DAYS`: Days in a month
  38 * `month_names`: List of month names (also determines number of months)
  39 * `month_names_short`: List of short month names
  40 * `weekday_names`: List of weekday names (also determines number of weekdays)
  41 * `weekday_names_short`: List of short weekday names
  42 * `FIRST_WEEK_DAY`: Cardinal number of the weekday that
  43                     marks the beginning of a week
  44                     and the calendar
  45
  46 Fields that were `nil` won't change. You can access each of the calender settings
  47 later with `calender.<field name>`, e.g. `calendar.MONTH_DAYS`. Note this is
  48 read-only access, you must never write to these fields directly. Only
  49 use `calendar.config` to change these fields.
  50
  51 ### Convenience variables
  52 For convenience, there are also these shortcuts that are automatically set,
  53 derived from the other values:
  54
  55 * `calendar.MONTHS`: Number of months in a year
  56 * `calendar.WEEK_DAYS`: Number of days in a week
  57 * `calendar.YEAR_DAYS`: Number of days in a year
  58
  59 ## Functions
  60
  61 ### `calendar.get_date(total_days, ordinal)`
  62 Returns 4 values: days, months, years and days in year (in that order)
  63
  64 * `total_days`: Number of elapsed days (default: today)
  65 * `ordinal`: if `true`, use ordinal numbers
  66              if `false`, use cardinal numbers
  67              default: false
  68
  69 ### `calendar.get_total_days_from_date(days, months, years, is_ordinal)`
  70 Given a date, returns the total number of elapsed days (cardinal number).
  71
  72 * `days`/`months`/`years`: Date
  73 * `is_ordinal`: If `true`, date is interpreted as ordinal numbers, otherwise
  74                 it is interpreted as cardinal numbers (default: `false`)
  75
  76 ## `calendar.get_weekday(total_days)`
  77 Returns cardinal weekday number for given day.
  78
  79 * `total_days`: Number of elapsed days (default: today)
  80
  81 ### `calendar.get_date_string(format, total_days)`
  82 Returns the game date as a human-readable string
  83
  84 * `format`: Optional tokenized string to represent the game date
  85             Default: `"%Y years, %M months, %D days"`
  86 * `total_days`: Number of elapsed days (default: today)
  87
  88 The tokenized string may include one or more date specifiers:
  89
  90 Cardinal values:
  91 * `%Y`: Elapsed years in epoch
  92 * `%M`: Elapsed months in year
  93 * `%D`: Elapsed days in month
  94 * `%J`: Elapsed days in year
  95
  96 Ordinal values:
  97 * `%y`: Current year of epoch
  98 * `%m`: Current month of year
  99 * `%d`: Current day of month
 100 * `%j`: Current day of year
 101
 102 Other:
 103 * `%b`: Full name of current month
 104 * `%h`: Short name of current month
 105 * `%W`: Full name of current weekday
 106 * `%w`: Short name of current weekday
 107 * `%z`: Literal percent sign
 108
 109 ### `calendar.register_holiday(def)`
 110
 111 Register a holiday. A holiday is just a special named day in a calender and
 112 can be used for whatever you like: Actual holidays, special events, reminders,
 113 whatever.
 114 By default, holidays will be marked in the graphical calendar.
 115 Holidays can be queried with `calendar.get_holidays`.
 116
 117 * `def`: Holiday definition. A table with these fields:
 118     * `name`: Human-readable holiday name
 119     * `text_color` (optional): Custom text color of day/tooltip text
 120     * `daybox_color` (optional): Custom text color of day box
 121     * `type`: type of holiday, determines other arguments
 122     * Arguments when `type=="monthday"`:
 123         * `days`: Cardinal month day on which the holiday occurs
 124         * `months`: Cardinal month on which the holiday occurs
 125         * `years`: (optional) Cardinal year on which the holiday occurs. If not set, occurs every year
 126     * Arguments when `type=="custom"`:
 127         * `is_holiday`: Function that takes total days as parameter and must
 128                         return true if it's a holiday and false if not.
 129                         Try to keep your calculations as simple as possible
 130
 131 When no colors are specified, a default green color is used. When multiple holidays fall
 132 on the same day and the holidays use different colors, the day box will assume the color
 133 of the first registered holiday (the order is not predictable).
 134
 135 #### Examples
 136 ```
 137 -- First day of every year
 138 calendar.register_holiday({
 139         name = "New Year's Eve",
 140         type = "monthday",
 141         days = 0,
 142         months = 0
 143 })
 144
 145 -- First Sunday in May
 146 calendar.register_holiday({
 147         name = "Mother's Day",
 148         type = "custom",
 149         is_holiday = function(total_days)
 150                 local d, m, y = calendar.get_date(total_days)
 151                 local wday = calendar.get_weekday(total_days)
 152                 return wday == 6 and m == 4 and d <= 6
 153         end,
 154 })
 155 ```
 156
 157 ### `calendar.get_holidays(total_days)`
 158 Returns table of all holidays for the given day.
 159
 160 Each table value returns a reference to holiday definition that was
 161 used in `calendar.register_holiday`.
 162
 163 * `total_days`: Number of elapsed days (default: today)
 164
 165
 166
 167 ### `calendar.show_calendar(player_name, settings, wanted_months, wanted_years)`
 168 Display a graphical calendar to player. It shows the days of a single month
 169 with one numbered box per day. Also, holidays and the current day can be marked and
 170 get a tooltip.
 171
 172 * `player_name`: Named of player
 173 * `settings`: Table to customize calendar:
 174     * `ordinal`: If `true`, use ordinal numbers, otherwise, use cardinal numbers (default: `false`)
 175     * `show_weekdays`: If `true`, show weekdays and arrange the day boxes to weekdays (default: `true`)
 176     * `show_today`: If `true`, mark today (default: `true`)
 177     * `show_holiday`: If `true`, mark holidays (default: `true`)
 178     * `changable`: Which controls are available:
 179         * `"full"`: Can change year and month (default)
 180         * `"months"`: Can change month within selected year only
 181         * `"none"`: Can't change anything
 182     * `today_button`: Whether to show the 'Today' button (default: `true`)
 183                       Note: If `changable=="none"`, the 'Today' button is never shown
 184 * `wanted_months`: Which cardinal calendar month to show (default: current one)
 185 * `wanted_years`: Which cardinal calendar year to show (default: current one)
 186 * `caption_format`: Optional format information to change the calendar caption.
 187                     Is a table with the following fields:
 188                     [1]: Format string with `minetest.translate`-style placeholders (from Minetest 5.0.0)
 189                     [2]: Translator domain for `minetest.translate`
 190                     [3]: and further: Parameters for the format string. For each parameter, use
 191                          a placeholder from `calender.get_date_string`.
 192
 193 Example for `caption_format`:
 194
 195     { N("@1, year @2"), "mymod", "%b", "%Y" }
 196
 197 Will resolve to e.g. "January, Year 1".
 198 `N` is a dummy function `function(s) return s end` that is used for the translation collector
 199 script.