Module:Television episode short description/sandbox

This is the module sandbox page for Module:Television episode short description (diff).
See also the companion subpage for test cases (run).
Module documentation[view] [edit] [history] [purge]
This module depends on the following other modules:
Module:Television episode short description extracts data from a television episode article's Template:Infobox television episode and creates a relevant short description based on the data available.
This module implements the {{Television episode short description}} template.
Usage

{{#invoke:Television episode short description|getShortDescription}}
Parameter list

The parameter names use a corresponding parameter from Template:Infobox television episode to fill in the data. They are listed below.
Parameter	Corresponding infobox parameter	Description
`series_name`	`series`	The TV series name.
`episode_num`	`episode`	The episode's number.
`season_num`	`season`	The season's number.
`season_num_uk`	`series_no`	The season's number if using the British "series" term.
`not_dab`	same name	Set if the TV series name has parentheses as part of its name.
`special`	same name	Setting to "yes" will set the description as a "special episode". Any other value will replace the word "special" with the one entered. For example `\|special=recap` will set the text to "recap episode".
`limited`	same name	Set if the series is a single season series, such as miniseries or limited series and does not need a season number as part of the description.
Examples

Issues

If an article does not show the short description with the data from the infobox, make sure you entered the parameter names correctly in the infobox.
Tracking categories

-- This module requires the use of Module:ConvertNumeric.
local convertNumeric = require('Module:ConvertNumeric')

-- Unique suffix list.
local uniqueSuffix = {
	[1] = 'st',
	[2] = 'nd',
	[3] = 'rd',
}

-- Common suffix.
local commonSuffix = "th"

local p = {}

-- Local function used to create a short description in the style of: "A television episode".
local function getShortDescriptionNoValues()
	return "A television episode"
end
	
-- Local function used to create a short description in the style of: "An episode of ''Lost''".
local function getShortDescriptionNoEpisodeNoSeasonsValues(tvSeriesName)
	return "An episode of ''" .. tvSeriesName .. "''"
end

-- Local function used to create a short description in the style of: "An episode of the first season of ''Lost''".
local function getShortDescriptionNoEpisodeValue(seasonOrdinalNumber, tvSeriesName)
	return "An episode of the " .. seasonOrdinalNumber .. " season of ''" .. tvSeriesName .. "''"
end

-- Local function used to create a short description in the style of: "5th episode of the fourth season of ''Lost''".
local function getShortDescriptionSingleEpisode(episodeOrdinalNumber, seasonOrdinalNumber, tvSeriesName)
	return episodeOrdinalNumber .. " episode of the " .. seasonOrdinalNumber .. " season of ''" .. tvSeriesName .. "''"
end

-- Local function used to create a short description for double episodes in the style of: "23rd and 24th episodes of the third season of ''Lost''". 
local function getShortDescriptionDoubleEpisode(episodeOrdinalNumber, secondEpisodeOrdinalNumber, seasonOrdinalNumber, tvSeriesName)
	return episodeOrdinalNumber .. " and " .. secondEpisodeOrdinalNumber .. " episodes of the " .. seasonOrdinalNumber .. " season of ''" .. tvSeriesName .. "''"
end

-- Local function used to retrieve the ordinal indicator for an integer between 0 and 100.
local function getOrdinalIndicatorLessThan100(number)
	local suffix																							-- Variable to save the ordinal indicator suffix.
	
	while (suffix == nil) do																				-- Initiate a loop that goes on until a suffix has been found.
		
		if (number == 0) then																				-- Check if the number equals 0; This should never be a valid entry.
			suffix = ""																						-- Assign suffix as an empty string.
		elseif (number < 4) then																			-- Check if the number is less than 4; Numbers "1", "2" and "3" have unique suffixes.
			suffix = uniqueSuffix[number]																	-- It is; Get the unique suffix for that number and assign it.
		elseif (number < 20) then																			-- Check if the number is more than 4 AND less than 20; These numbers all have the same common suffix.
			suffix = commonSuffix																			-- It is; Assign suffix as the common suffix - "th".
		elseif (number % 10 == 0) then																		-- Check if the remainder after division of the number by 10 equals 0.
			suffix = commonSuffix																			-- It is; Assign suffix as the common suffix - "th".
		else																								-- Anything else - numbers that are above 20 and which their remainder doesn't equal 0 (such as 45).
			number = number % 10																			-- Save the new number to the remainder after division of the number by 100;
																											-- So if the current number is 45, the new number be 5.
		end
		
	end
	
	return suffix																							-- Return the suffix.
end

-- Local function used to retrieve the ordinal indicator for an integer between 0 and 1000.
local function getOrdinalIndicatorLessThan1000(number)
	
	if (number < 100) then																					-- Check if the number is less than 100.
		return getOrdinalIndicatorLessThan100(number)														-- The number is less than 100;
																											-- Call getOrdinalIndicatorLessThan100() to get the ordinal indicator and return it.
	elseif (number % 100 == 0) then																			-- Check if the remainder after division of the number by 100 equals 0.
		return commonSuffix																					-- It does; Return the common suffix - "th".
	else																									-- Anything else - numbers that are above 100 and which their remainder doesn't equal 0 (such as 345).
		return getOrdinalIndicatorLessThan100(number % 100)													-- Call getOrdinalIndicatorLessThan100() to get the ordinal indicator and return it;
																											-- Pass the remainder after division of the number by 100 (So for 345, it would pass 45) as the parameter.
	end
	
end

-- Local function used to create an ordinal number.
local function getEpisodeOrdinalNumber(number)
	local ordinalIndicator = getOrdinalIndicatorLessThan1000(number)										-- Call getOrdinalIndicatorLessThan1000() to get the number's ordinal indicator.
	return number .. ordinalIndicator																		-- Create an ordinal number and return it.
end

-- Local function used to extract the episode number from the double episode string.
local function extractEpisodeNumberInDoubleEpisode(doubleEpisodeNumberText)
	local episodeNumber = string.match (doubleEpisodeNumberText, '(%d+) *[,&/and]+ *%d+')					-- Extract the first episode number (%d+) from the string until reaching one of these characters - ",/and".
	return tonumber(episodeNumber)																			-- Convert extracted string result into a number and return it.
end

-- Local function used to validate if data was 
-- entered into a parameter of type number.
local function validateNumberParam(number)
	if (tonumber(number) == nil) then																		-- Convert the string into a number and check if the value equals nil (converstion failed).
		return false																						-- Param is either empty or not a number; Return false.
	else																									-- Param is a number;
		return true																							-- Return true.
	end
end

-- Local function that is used to create a short description
-- by validating if an episode number was entered.
-- If it was entered, it creates a double-episode short description.
local function createDescriptionValidateDoubleEpisode(episodeNumberText, seasonOrdinalNumber, tvSeriesName)
	local episodeNumber = extractEpisodeNumberInDoubleEpisode(episodeNumberText)							-- Call extractEpisodeNumberInDoubleEpisode() to get the episode number from the text.
		
	if (validateNumberParam(episodeNumber)) then															-- Call validateNumberParam() to check if an episode number was entered.
																											-- A an episode number was entered;
		local episodeOrdinalNumber = getEpisodeOrdinalNumber(episodeNumber)									-- Call getEpisodeOrdinalNumber() to get the first episode ordinal number.
		local secondEpisodeOrdinalNumber = getEpisodeOrdinalNumber(episodeNumber + 1)						-- Call getEpisodeOrdinalNumber() and increment, to get the second episode ordinal number.

		return getShortDescriptionDoubleEpisode(episodeOrdinalNumber,										-- Call getShortDescriptionDoubleEpisode() to get the double episode's short description and return it.
				secondEpisodeOrdinalNumber, seasonOrdinalNumber, tvSeriesName)
	else																									-- A an episode number was not entered;
		return getShortDescriptionNoEpisodeValue(seasonOrdinalNumber, tvSeriesName)							-- Call getShortDescriptionNoEpisodeValue() to get the short description and return it.
	end
end

-- Local function that is used to create a short description
-- by validating if an episode number was entered.
-- If it was entered, it creates a single-episode short description.
local function createDescriptionValidateSingleEpisode(episodeNumberText, seasonOrdinalNumber, tvSeriesName)
	local episodeNumber = tonumber(episodeNumberText)														-- Convert the episode number text into a number.

	if (validateNumberParam(episodeNumber)) then 															-- Call validateNumberParam() to check if an episode number was entered.
																											-- A an episode number was entered; 
		local episodeOrdinalNumber = getEpisodeOrdinalNumber(episodeNumber)									-- Call getEpisodeOrdinalNumber() to get the episode ordinal number.
		return getShortDescriptionSingleEpisode(episodeOrdinalNumber, seasonOrdinalNumber, tvSeriesName)	-- Call getShortDescriptionSingleEpisode() to get the episode's short description and return it.
	else																									-- A an episode number was not entered;
		return getShortDescriptionNoEpisodeValue(seasonOrdinalNumber, tvSeriesName)							-- Call getShortDescriptionNoEpisodeValue() to get the short description and return it.
	end
end

-- Local function that is used to create a short description
-- by validating if a "multi_episodes" value was entered.
local function createDescriptionValidateEpisodeValue(episodeNumberText, seasonOrdinalNumber, tvSeriesName, isDoubleEpisode)
	if (isDoubleEpisode ~= nil) then																		-- Check if a multi_episodes value was entered.
																											-- A multi_episodes value was entered;
		return createDescriptionValidateDoubleEpisode(episodeNumberText, seasonOrdinalNumber, tvSeriesName) -- Call createDescriptionValidateDoubleEpisode() to continue validation process.	
	else																									-- A multi_episodes value was not entered;
		return createDescriptionValidateSingleEpisode(episodeNumberText, seasonOrdinalNumber, tvSeriesName)	-- Call createDescriptionValidateSingleEpisode() to continue validation process.
	end
end

-- Local function that is used to create a short description
-- by validating if a season number was entered.
local function createDescriptionValidateSeasonValue(episodeNumberText, seasonNumber, tvSeriesName, isDoubleEpisode)
	if (validateNumberParam(seasonNumber)) then																-- Call validateNumberParam() to check if a season number was entered.
																											-- A season number was entered;
		local seasonOrdinalNumber = convertNumeric.spell_number(											-- Call spell_number() from Module:ConvertNumeric to get the season ordinal number.
			seasonNumber,																					-- Pass it the season number.
			nil,																							-- Not used here.
			nil,																							-- Not used here.
			false,																							-- Not used here.
			false,																							-- Not used here.
			false,																							-- Not used here.
			true,																							-- Get the season ordinal number from the season number.
			false,																							-- Not used here.
			nil,																							-- Not used here.
			nil,																							-- Not used here.
			nil,																							-- Not used here.
			nil,																							-- Not used here.
			false)																							-- Not used here.
																												
		return createDescriptionValidateEpisodeValue(episodeNumberText, 									-- Call createDescriptionValidateEpisodeValue() to continue validation process.	
			seasonOrdinalNumber, tvSeriesName, isDoubleEpisode)
	else																									-- A season number was not entered;
		return getShortDescriptionNoEpisodeNoSeasonsValues(tvSeriesName)									-- Call getShortDescriptionNoEpisodeNoSeasonsValues() to get the short description and return it.
	end
end

-- Local function that is used to remove the wikilink formatting of an article name.
-- Removes pipped links, brackets and disambiugation.
local function getUnformattedSeriesName(tvSeriesName, notDisambiguated)
	local unformattedName = string.match(tvSeriesName, "|(.-)]")											-- Get the series name after the piped link, without link brackets.
	
	if (unformattedName ~= nil) then																		-- Check if it was successful (will fail if no pipped link).
		tvSeriesName = unformattedName																		-- Match was successful; Save unformatted TV series name.

	else 
		unformattedName = string.match(tvSeriesName, "%[+(.-)]")											-- Get the series without the link brackets (no piped link).
		
		if (unformattedName ~= nil) then																	-- Check if it was successful (will fail if no brackets).
			tvSeriesName = unformattedName																	-- Match was successful; Save unformatted TV series name.
		end
	end
	
	if (notDisambiguated == nil) then																		-- Check if a not_dab value was entered.
		tvSeriesName = string.gsub(tvSeriesName, "%s+%b()$", "", 1, false)									-- A not_dab value was not entered; Get the article title without the disambiguation.
	end
	
	return tvSeriesName																						-- Return the unformatted TV series name.
end

-- Local function that is used to create a short description.
-- This creates a description by a process of validating which values where entered
-- into the Infobox and has the following options:
-- If no TV series name was entered, it calls getShortDescriptionNoValues().
-- If only the TV series name and season number were entered, it calls getShortDescriptionNoEpisodeValue().
-- If all information was entered and it is a single episode, it calls getShortDescriptionSingleEpisode().
-- If all information was entered and it is a double episode, it calls getShortDescriptionDoubleEpisode().
local function createDescription(episodeNumberText, seasonNumber, tvSeriesName, isDoubleEpisode, notDisambiguated) 

	if (tvSeriesName ~= nil) then																			-- Check if a TV series name was entered.
																											-- A TV series name was entered;
		tvSeriesName = getUnformattedSeriesName(tvSeriesName, notDisambiguated)								-- Call getUnformattedSeriesName() to get the unformatted TV series name.

		return createDescriptionValidateSeasonValue(episodeNumberText,										-- Call createDescriptionValidateSeasonValue() to continue validation process.				
			seasonNumber, tvSeriesName, isDoubleEpisode)			
	else																									-- A TV series name was not entered;
		return getShortDescriptionNoValues()																-- Call getShortDescriptionNoValues() to get the short description and return it.
	end
end

-- Local function used to retrieve the season number, since it can be entered in
-- either the "season" or "series_no" params.
local function getSeasonNumber(seasonNumber, seasonNumberUK)
	
	if (tonumber(seasonNumber) ~= nil) then																	-- Check if the value in the "|season_num" ("season") param is a number.
		return seasonNumber																					-- It is; Return value.
	elseif (tonumber(seasonNumberUK) ~= nil) then															-- Check if the value in the "|season_num_uk" ("series_no") param is a number.
		return seasonNumberUK																				-- It is; Return value.
	else																									-- Anything else - value not entered.
		return ""																							-- Return empty string.
	end

end

-- Local function that does the actual main process.
local function _getShortDescription(episodeNumberText, seasonNumber, seasonNumberUK, tvSeriesName, isDoubleEpisode, notDisambiguated)
	local seasonNumberFound = getSeasonNumber(seasonNumber, seasonNumberUK)									-- Call getSeasonNumber() to get the season number, as it can be in one of two fields.
	
	return createDescription(
		episodeNumberText, seasonNumberFound, tvSeriesName, isDoubleEpisode, notDisambiguated)				-- Call createDescription() and return the episode's short description.
end

-- Public function used to create a television episode's short description
-- from the data available in [[Template:Infobox television episode]].
-- A suiteable description will be generated depending on the values
-- of the various parameters. See documention for examples.
--
-- This module function takes six parameters:
-- |episode_num= — optional; The episode's number
-- |season_num= — optional; The season's number.
-- |season_num_uk= — optional; The season's number if using the British "series" term.
-- |series_name= — optional; The TV series name.
-- |multi_episodes= — optional; Set if the episode is a double episode.
-- |not_dab= — optional; Set if the TV series name has parentheses as part of its name.
function p.getShortDescription(frame)
	local getArgs = require('Module:Arguments').getArgs;													-- Use Module:Arguments to access module arguments.
	local args = getArgs(frame);																			-- Get the arguments sent via the template.
	
	local episodeNumberText = args['episode_num']															-- Get the episode number in text.
	local seasonNumber = args['season_num']																	-- Get the season number from the {{{season}}} param.
	local seasonNumberUK = args['season_num_uk']															-- Get the season number if it's written in the "series_no" param.
	local tvSeriesName = args['series_name']																-- Get the TV series name.
	local isDoubleEpisode = args['multi_episodes']															-- Get the value of "multi_episodes" (used for episode consisting of two episodes).
	local notDisambiguated = args['not_dab']																-- Get the value of "not_dab" (used if the TV series name has parentheses as part of its name).

	return _getShortDescription(
		episodeNumberText, seasonNumber, seasonNumberUK, tvSeriesName, isDoubleEpisode, notDisambiguated)	-- Call _getShortDescription() to peform the actual process.

end

return