Add API docs
Wuzzy
parent
ff934eec7d
commit
e96cbf9b18
104
API.md
104
API.md
|
|
@ -1 +1,103 @@
|
|||
TO BE WRITTEN
|
||||
# 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.
|
||||
|
||||
## 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
|
||||
|
||||
### `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. Holidays and the current day are marked and
|
||||
have 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_controls`: If `true`, show buttons to change the month and year
|
||||
* `wanted_months`: Which cardinal calendar month to show (default: current one)
|
||||
* `wanted_years`: Which cardinal calendar year to show (default: current one)
|
||||
|
|
|
|||
73
init.lua
73
init.lua
|
|
@ -27,16 +27,6 @@ calendar.FIRST_WEEK_DAY = 0
|
|||
|
||||
local holidays = {}
|
||||
|
||||
-- Register a holiday.
|
||||
-- def: Table with these fields:
|
||||
-- * name: Human-readable name
|
||||
-- * type: type of holiday, determines other argumetns
|
||||
-- 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
|
||||
calendar.register_holiday = function(def)
|
||||
table.insert(holidays, def)
|
||||
end
|
||||
|
|
@ -61,6 +51,9 @@ calendar.register_holiday({
|
|||
})
|
||||
|
||||
calendar.get_holidays = function(total_days)
|
||||
if not total_days then
|
||||
total_days = minetest.get_day_count()
|
||||
end
|
||||
local days, months, years = calendar.get_date(total_days)
|
||||
local found_holidays = {}
|
||||
for h=1, #holidays do
|
||||
|
|
@ -80,26 +73,22 @@ calendar.get_holidays = function(total_days)
|
|||
return found_holidays
|
||||
end
|
||||
|
||||
-- Returns weekday number
|
||||
-- * total_days: elapsed days since start of world
|
||||
calendar.get_weekday = function(total_days)
|
||||
if not total_days then
|
||||
total_days = minetest.get_day_count()
|
||||
end
|
||||
return (total_days + calendar.FIRST_WEEK_DAY) % calendar.WEEK_DAYS
|
||||
end
|
||||
|
||||
-- Returns day, month, year, days in year
|
||||
-- * days: elapsed days since start of world
|
||||
-- * ordinal: if true, use ordinal numbers (day, month, year start counting at 1).
|
||||
-- if false, use cardinal numbers (day, month, year start counting at 0).
|
||||
-- default: false
|
||||
calendar.get_date = function(days, ordinal)
|
||||
if not days then
|
||||
days = minetest.get_day_count()
|
||||
calendar.get_date = function(total_days, ordinal)
|
||||
if not total_days then
|
||||
total_days = minetest.get_day_count()
|
||||
end
|
||||
|
||||
local y = math.floor( days / calendar.YEAR_DAYS ) -- elapsed years in epoch
|
||||
local m = math.floor( days % calendar.YEAR_DAYS / calendar.MONTH_DAYS ) -- elapsed months in year
|
||||
local d = math.floor( days % calendar.YEAR_DAYS % calendar.MONTH_DAYS ) -- elapsed days in month
|
||||
local j = math.floor( days % calendar.YEAR_DAYS ) -- elapsed days in year
|
||||
local y = math.floor(total_days / calendar.YEAR_DAYS) -- elapsed years in epoch
|
||||
local m = math.floor(total_days % calendar.YEAR_DAYS / calendar.MONTH_DAYS) -- elapsed months in year
|
||||
local d = math.floor(total_days % calendar.YEAR_DAYS % calendar.MONTH_DAYS) -- elapsed days in month
|
||||
local j = math.floor(total_days % calendar.YEAR_DAYS) -- elapsed days in year
|
||||
|
||||
if ordinal == nil then
|
||||
ordinal = false
|
||||
|
|
@ -113,35 +102,35 @@ calendar.get_date = function(days, ordinal)
|
|||
return d, m, y, j
|
||||
end
|
||||
|
||||
calendar.get_date_string = function( str, env_date )
|
||||
if not env_date then
|
||||
env_date = minetest.get_day_count( )
|
||||
calendar.get_date_string = function(format, total_days)
|
||||
if not total_days then
|
||||
total_days = minetest.get_day_count()
|
||||
end
|
||||
|
||||
if str == nil then
|
||||
str = S("%D days, %M months, %Y years")
|
||||
if format == nil then
|
||||
format = S("%D days, %M months, %Y years")
|
||||
end
|
||||
|
||||
local y, m, d, j = calendar.get_date()
|
||||
local y, m, d, j = calendar.get_date(total_days)
|
||||
|
||||
-- cardinal values
|
||||
str = string.gsub( str, "%%Y", y ) -- elapsed years in epoch
|
||||
str = string.gsub( str, "%%M", m ) -- elapsed months in year
|
||||
str = string.gsub( str, "%%D", d ) -- elapsed days in month
|
||||
str = string.gsub( str, "%%J", j ) -- elapsed days in year
|
||||
format = string.gsub( format, "%%Y", y ) -- elapsed years in epoch
|
||||
format = string.gsub( format, "%%M", m ) -- elapsed months in year
|
||||
format = string.gsub( format, "%%D", d ) -- elapsed days in month
|
||||
format = string.gsub( format, "%%J", j ) -- elapsed days in year
|
||||
|
||||
-- ordinal values
|
||||
str = string.gsub( str, "%%y", y + 1 ) -- current year of epoch
|
||||
str = string.gsub( str, "%%m", m + 1 ) -- current month of year
|
||||
str = string.gsub( str, "%%d", d + 1 ) -- current day of month
|
||||
str = string.gsub( str, "%%j", j + 1 ) -- current day of year
|
||||
format = string.gsub( format, "%%y", y + 1 ) -- current year of epoch
|
||||
format = string.gsub( format, "%%m", m + 1 ) -- current month of year
|
||||
format = string.gsub( format, "%%d", d + 1 ) -- current day of month
|
||||
format = string.gsub( format, "%%j", j + 1 ) -- current day of year
|
||||
|
||||
str = string.gsub( str, "%%b", calendar.month_names[ m + 1 ] ) -- current month long name
|
||||
str = string.gsub( str, "%%h", calendar.month_names_short[ m + 1 ] ) -- current month short name
|
||||
format = string.gsub( format, "%%b", calendar.month_names[ m + 1 ] ) -- current month long name
|
||||
format = string.gsub( format, "%%h", calendar.month_names_short[ m + 1 ] ) -- current month short name
|
||||
|
||||
str = string.gsub( str, "%%z", "%%" )
|
||||
format = string.gsub( format, "%%z", "%%" )
|
||||
|
||||
return str
|
||||
return format
|
||||
end
|
||||
|
||||
dofile(minetest.get_modpath("calendar").."/gui.lua")
|
||||
|
|
|
|||
Loading…
Reference in New Issue