![]() | This module is rated as beta, and is ready for widespread use. It is still new and should be used with some caution to ensure the results are as expected. |
This module is used to calculate dates in the Japanese calendar. It defines an "era" class which is designed to be called from other Lua modules, and it also contains several functions to export Japanese calendar data directly to Wikipedia pages through #invoke.
Usage
Through #invoke
{{#invoke:Japanese calendar|function_name|year=year|era=article name or kanji|previous=yes|next=yes}}
The function name specifies how the data should be outputted. The year
and era
parameters determine what era and year the module outputs. The next
and previous
parameters tell the module to return data for the next or previous era, rather than the one specified. If a combination of parameters is invalid the module will usually output nothing. However, if both the next
and previous
parameters are specified it will output an error.
Year and era
The year
parameter is the year in the Gregorian calendar. The era
parameter can either be the article name for that era, or the era's name in kanji. (Transcribed English era names can usually be used, but will not work if they are ambiguous.) Either year
or era
must be specified. If both are specified, the module defaults to using era
to get the era data. This enables output of the last year of the previous era (for example, Shōwa 64 is the same year as Heisei 1).
Code | Output |
---|---|
{{#invoke:Japanese calendar|link|year=1950}} |
Shōwa |
{{#invoke:Japanese calendar|link|era=Shōwa period}} |
Shōwa |
{{#invoke:Japanese calendar|link|era=昭和}} |
Shōwa |
{{#invoke:Japanese calendar|link|era=Shōwa}} |
|
{{#invoke:Japanese calendar|link_year|year=1989}} |
Heisei 1 |
{{#invoke:Japanese calendar|link_year|year=1989|era=Shōwa period}} |
Shōwa 64 |
{{#invoke:Japanese calendar|link_year|year=1990}} |
Heisei 2 |
{{#invoke:Japanese calendar|link_year|year=1990|era=Shōwa period}} |
Functions
Code | Description | Example |
---|---|---|
baseyear |
The first year of the specified era. | {{#invoke:Japanese calendar|baseyear|era=Heisei}} → 1989
|
endyear |
The last year of the specified era. | {{#invoke:Japanese calendar|endyear|era=Shōwa period}} → 1989
|
year |
The year for the specified era, without the era name. Defaults to the newer era, if more than one is applicable. | {{#invoke:Japanese calendar|year|year=1989}} → 1
|
kanjiyear |
The same as year , but in kanji. The first year of an era is changed to the kanji 元, and the others are changed to full-width numbers. |
{{#invoke:Japanese calendar|kanjiyear|year=1989}} → 元
|
article |
The Wikipedia article for the era, unlinked. | {{#invoke:Japanese calendar|article|year=1950}} → Shōwa (1926–1989)
|
label |
The name of the era. Same as article for undisambiguated titles. |
{{#invoke:Japanese calendar|label|year=1950}} → Shōwa
|
link |
A link to the Wikipedia article of the specified era. | {{#invoke:Japanese calendar|link|year=1950}} → Shōwa
|
kanji |
The kanji for the specified era. | {{#invoke:Japanese calendar|kanji|year=1950}} → 昭和
|
label_year |
label followed by year |
{{#invoke:Japanese calendar|label_year|year=1989}} → Heisei 1
|
link_year |
link followed by year |
{{#invoke:Japanese calendar|link_year|year=1989}} → Heisei 1
|
label_kanjiyear |
label followed by kanjiyear |
{{#invoke:Japanese calendar|label_kanjiyear|year=1989}} → Heisei 元
|
link_kanjiyear |
link followed by kanjiyear |
{{#invoke:Japanese calendar|link_kanjiyear|year=1989}} → Heisei 元
|
Next, previous and old
If the next
parameter is specified, the module outputs the data for the subsequent era; if the previous
parameter is specified it outputs the data for the previous one. If the old
parameter is specified, the module outputs the data for the "old" era. This is the same as the current era unless the year is set to the first year of the specified era. If this is the case, then old
outputs the data for the previous era. However, if the module could not find a valid previous era then the data for the current era is returned.
Code | Output |
---|---|
{{#invoke:Japanese calendar|baseyear|era=Shōwa period}} |
1926 |
{{#invoke:Japanese calendar|baseyear|era=Shōwa period|next=yes}} |
1989 |
{{#invoke:Japanese calendar|baseyear|era=Shōwa period|previous=yes}} |
1912 |
{{#invoke:Japanese calendar|baseyear|era=Shōwa period|old=yes}} |
1926 |
{{#invoke:Japanese calendar|link|year=1880}} |
Meiji |
{{#invoke:Japanese calendar|link|year=1880|next=yes}} |
Taishō |
{{#invoke:Japanese calendar|link|year=1880|previous=yes}} |
Keiō |
{{#invoke:Japanese calendar|link|year=1880|old=yes}} |
Meiji |
{{#invoke:Japanese calendar|link_year|year=1926}} |
Shōwa 1 |
{{#invoke:Japanese calendar|link_year|year=1926|old=yes}} |
Taishō 15 |
{{#invoke:Japanese calendar|link_year|year=1927}} |
Shōwa 2 |
{{#invoke:Japanese calendar|link_year|year=1927|old=yes}} |
Shōwa 2 |
From another Lua module
First of all, the era class must be loaded, like this:
local era = require( 'Module:Japanese calendar' ).era
Once the class is loaded, you can make a new era object using era:new()
:
local myEra = era:new{ year = year, era = article name or kanji }
Either year
or era
must be specified. It is also possible to use an index
field, corresponding to the index of Module:Japanese calendar/data, but this is for internal use only and will change as new eras are added.
Properties
Era objects have a number of properties. Their values might be nil
if the module did not have enough information to process them, or the values could be false
if they correspond to an invalid era. You can specify properties with the dot syntax:
local article = myEra.article
The properties are as follows:
gregorianYear
: the year in the Gregorian calendar. Same as the input year.startYear
: the first year of the specified era.endYear
: the last year of the specified era.eraYear
: the year of the specified era, without the era name.eraYearKanji
: a string representing the era year in kanji. The first year of an era is changed to the kanji 元, and the others are changed to full-width numbers. Note: even though the output may often look like a number, it will always be a string value.article
: the Wikipedia article for the era, unlinked.label
: the name of the era. Same asarticle
unless the article title is disambiguated.kanji
: the name of the era in kanji.
Methods
Era objects have three methods. Methods can be specified with the colon syntax:
local nextEra = myEra:getNextEra()
The methods are as follows:
era:getNextEra()
- gets the era object for the next era. Returnsnil
if it doesn't exist.era:getPreviousEra()
- gets the era object for the previous era. Returnsnil
if it doesn't exist.era:getOldEra()
- gets the era object for the "old" era. This is the same as the current era object unless eraYear equals 1. If eraYear equals 1 then this returns the era object for the previous era. If the module could not find a valid previous era object then the current era object is returned.
-- This module defines an "era" class for processing eras in the Japanese calendar.
-- It also contains functions to export the class properties to #invoke.
local eras = mw.loadData( 'Module:Japanese calendar/data' )
local halfToFull = require( 'Module:Convert character width' ).full -- Converts half-width characters to full-width characters.
--------------------------------------------------------------------
-- Helper functions
--------------------------------------------------------------------
local function yearToEraIndex( year )
year = tonumber( year )
if type( year ) ~= 'number' then return end
for i, t in ipairs( eras ) do
if year > t.startYear then
return i
elseif year == t.startYear then
if eras[ i + 1 ] and eras[ i + 1 ].startYear == t.startYear then -- This checks for occasions when there were more than two eras in the same year. At the moment, that only applies to the year 686.
return i + 1
else
return i
end
end
end
end
local function textToEraIndex( s )
if not s or s == '' then return end
sTitle = mw.title.new( s )
for i, t in ipairs( eras ) do
if t.article and t.article ~= '' then
tTitle = mw.title.new( t.article )
if mw.title.equals( sTitle.redirectTarget or sTitle, tTitle.redirectTarget or tTitle ) then
return i
end
end
if s == t.kanji then
return i
end
end
end
--------------------------------------------------------------------
-- Era class definition
--------------------------------------------------------------------
local era = {}
era.__index = era
function era:new( init )
init = type( init ) == 'table' and init or {}
local obj = {}
-- Grab the data from the init table.
obj.gregorianYear = tonumber( init.year )
local initText = type( init.era ) == 'string' and init.era or nil
local initIndex = tonumber( init.index )
if not ( initIndex and initIndex >= 1 and math.floor( initIndex ) == initIndex and initIndex ~= math.huge ) then -- Check that initIndex is a positive integer.
initIndex = nil
end
-- Calculate the era data from the input. First we find the era from the era index, although this is only supposed
-- to be for internal use. Next we find the era from the era name or the kanji if possible, as this allows us to
-- specify the last year of one era rather than the first year of the next one, if that is the desired behaviour.
local eraIndex
if initIndex then
eraIndex = initIndex
elseif initText then
eraIndex = textToEraIndex( initText )
elseif obj.gregorianYear then
eraIndex = yearToEraIndex( obj.gregorianYear )
end
-- If the data entry was found for the era, process it and add it to the object.
if not eraIndex then return end
local eraData = eras[ eraIndex ]
if not eraData or not eraData.article or eraData.article == '' then return end -- Exit if we are not dealing with a valid era.
obj.startYear = eraData.startYear
obj.endYear = eraData.endYear
obj.article = eraData.article
obj.kanji = eraData.kanji
obj.label = eraData.label
-- Create a link to the era article if possible.
if obj.label and obj.article then
obj.link = mw.ustring.format( '[[%s|%s]]', obj.article, obj.label )
elseif obj.article then
obj.link = mw.ustring.format( '[[%s]]', obj.article )
end
-- Allow matching years to different eras, but only for the first year of the next era. For example, Taisho 15 is also Showa 1, but there is no such thing as Taisho 16.
-- So, the code era:new{ year = 1926, era = "Taishō" } will return an object with an eraYear of 15, and era:new{ year = 1926 } will return an object with an eraYear of 1.
local nextEraData = eras[ eraIndex - 1 ]
local nextStartYear = nextEraData and nextEraData.startYear
if obj.gregorianYear
and ( -- If there is a later era, only allow the first year of that era or an earlier year.
not nextStartYear
or ( nextStartYear and obj.gregorianYear <= nextStartYear )
)
and obj.gregorianYear >= obj.startYear -- Don't allow negative years.
and obj.article ~= '' -- Don't allow periods between named eras.
and ( obj.endYear and obj.gregorianYear <= obj.endYear or true ) -- If this era has an end year, don't allow years that are greater than the end year.
then
obj.eraYear = obj.gregorianYear - obj.startYear + 1
if obj.eraYear == 1 then
obj.eraYearKanji = '元'
else
obj.eraYearKanji = halfToFull( obj.eraYear )
end
end
-- Make sure obj.label is available even if it is the same as the article name.
obj.label = obj.label or obj.article
-- Add methods to get the next and previous eras.
function obj:getNextEra()
if not eraIndex then return end
return era:new{ index = eraIndex - 1, year = obj.gregorianYear }
end
function obj:getPreviousEra()
if not eraIndex then return end
return era:new{ index = eraIndex + 1, year = obj.gregorianYear }
end
-- Gets the era object for the "old" era. In most cases this is the same as the current era object, but
-- if the era year for the current object is 1, this method will return the era object for the previous
-- era. If the method can't find a valid previous era it will return the object for the current era.
function obj:getOldEra()
if obj.eraYear == 1 then
local prevEra = obj:getPreviousEra()
if prevEra then
return prevEra
else
return obj
end
else
return obj
end
end
return setmetatable( obj, {
__index = self
})
end
--------------------------------------------------------------------
-- Interface for old Japanese calendar templates
--------------------------------------------------------------------
local function getStartYear( obj )
return obj.startYear
end
local function getEndYear( obj )
return obj.endYear
end
local function getEraYear( obj )
return obj.eraYear
end
local function getEraYearKanji( obj )
return obj.eraYearKanji
end
local function getArticle( obj )
return obj.article
end
local function getLabel( obj )
return obj.label
end
local function getLink( obj )
return obj.link
end
local function getKanji( obj )
return obj.kanji
end
local function getLabelAndEraYear( obj, kanji )
local eraYear = kanji and obj.eraYearKanji or obj.eraYear
if obj.label and eraYear then
return mw.ustring.format( '%s %s', obj.label, tostring( eraYear ) )
end
end
local function getLinkAndEraYear( obj, kanji )
local eraYear = kanji and obj.eraYearKanji or obj.eraYear
if obj.link and eraYear then
return mw.ustring.format( '%s %s', obj.link, tostring( eraYear ) )
end
end
local function getLabelAndEraYearKanji( obj )
return getLabelAndEraYear( obj, true )
end
local function getLinkAndEraYearKanji( obj )
return getLinkAndEraYear( obj, true )
end
-- Process the arguments from #invoke.
local function makeWrapper( func )
return function( frame )
-- If called via #invoke, use the args passed into the invoking
-- template, or the args passed to #invoke if any exist. Otherwise
-- assume args are being passed directly in from the debug console
-- or from another Lua module.
local origArgs
if frame == mw.getCurrentFrame() then
origArgs = frame:getParent().args
for k, v in pairs( frame.args ) do
origArgs = frame.args
break
end
else
origArgs = frame
end
-- Trim whitespace and remove blank arguments.
local args = {}
for k, v in pairs( origArgs ) do
if type( v ) == 'string' then
v = mw.text.trim( v )
end
if v ~= '' then
args[k] = v
end
end
local myEra
local otherEraArgs = {}
table.insert( otherEraArgs, args.next )
table.insert( otherEraArgs, args.previous )
table.insert( otherEraArgs, args.old )
if #otherEraArgs > 1 then
return '<strong class="error">[[Module:Japanese calendar]] error: you can only specify one parameter out of "next", "previous" and "old".</strong>'
elseif args.next then
myEra = era:new( args ):getNextEra()
elseif args.previous then
myEra = era:new( args ):getPreviousEra()
elseif args.old then
myEra = era:new( args ):getOldEra()
else
myEra = era:new( args )
end
return myEra and func( myEra ) or ''
end
end
--------------------------------------------------------------------
-- Return the era class and the template interface
--------------------------------------------------------------------
return {
era = function () return era end, -- Accessor function for getting the era class from other modules.
baseyear = makeWrapper( getStartYear ),
endyear = makeWrapper( getEndYear ),
year = makeWrapper( getEraYear ),
kanjiyear = makeWrapper( getEraYearKanji ),
article = makeWrapper( getArticle ),
label = makeWrapper( getLabel ),
link = makeWrapper( getLink ),
kanji = makeWrapper( getKanji ),
label_year = makeWrapper( getLabelAndEraYear ),
link_year = makeWrapper( getLinkAndEraYear ),
label_kanjiyear = makeWrapper( getLabelAndEraYearKanji ),
link_kanjiyear = makeWrapper( getLinkAndEraYearKanji )
}