Module:Television episode short description

Documentation for this module may be created at Module:Television episode short description/doc

-- 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"

-- Tracking category list.
local trackingCategoryList = {
	[1] = '[[Category:Television episode articles with short description with no series name]]',
	[2] = '[[Category:Television episode articles with short description with no season number]]',
	[3] = '[[Category:Television episode articles with short description with no episode number]]',
	[4] = '[[Category:Television episode articles with short description for single episodes]]',
	[5] = '[[Category:Television episode articles with short description for multi-part episodes]]',
	[6] = '[[Category:Television episode articles with short description and disambiguated page names]]'
}

local p = {}

-- Local function which is used to check if the article name is disambiguated.
-- This is usually in the format of "Episode name (<TV series name>)" or "Episode name (<TV series name> episode)".
local function isDisambiguated(articleTitle, tvSeriesName)
	local disambiguation = string.match(tostring(articleTitle), "%s%((.-)%)")								-- Get the text inside the disambiguation parentheses.

	if disambiguation and tvSeriesName then																	-- Check if the article has parentheses and that the TV series name is not nil.
		if (string.find(disambiguation, tvSeriesName)) then 												-- Article has parentheses; Search for the TV series name in the article name disambiguation.
			return true																						-- Article is disambiguated; Return true.
		else
			return false																					-- Article is not disambiguated; Return false.
		end
	else
		return false																						-- Article does not have parentheses; Return false.
	end
end

-- Local function which is used to return a relevant tracking category.
local function createTrackingCategory(tvSeriesName, categoryNumber)
	local articleTitle = mw.title.getCurrentTitle()															-- Get the current page's title.
	local namespace = articleTitle.nsText;																	-- Get the invoking namespace.
	if (namespace == '' or namespace == 'Draft') then														-- Check if the invoking page is from the allowed namespace.
		if (isDisambiguated(articleTitle, tvSeriesName) == true) then										-- Invoking page is from the allowed namespace; Call isDisambiguated() to check if page is disambiguated.
			return trackingCategoryList[categoryNumber] .. trackingCategoryList[6]							-- Article is disambiguated; Retrieve the correct tracking categories and return them.
		else
			return trackingCategoryList[categoryNumber]														-- Article is not disambiguated; Retrieve the correct tracking category and return it.
		end
	else
		return ''																							-- Invoking page is not from the allowed namespace; Return empty string.
	end
end

-- Local function which is used to create a short description in the style of: "A television episode".
-- Add article to the maintenance category: [[Category:Television episode articles with short description with no series name]].
local function getShortDescriptionNoValues()
	return "A television episode", createTrackingCategory(nil, 1)
end

-- Local function which is used to create a short description in the style of: "An episode of ''Lost''".
-- Add article to the maintenance category: [[Category:Television episode articles with short description with no season number]].
local function getShortDescriptionNoEpisodeNoSeasonsValues(tvSeriesName)
	return "An episode of ''" .. tvSeriesName .. "''", createTrackingCategory(tvSeriesName, 2)
end

-- Local function which is used to create a short description in the style of: "An episode of the first season of ''Lost''".
-- Add article to the maintenance category: [[Category:Television episode articles with short description with no episode number]].
local function getShortDescriptionNoEpisodeValue(seasonOrdinalNumber, tvSeriesName)
	return "An episode of the " .. seasonOrdinalNumber .. " season of ''" .. tvSeriesName .. "''", createTrackingCategory(tvSeriesName, 3)
end

-- Local function which is used to create a short description in the style of: "5th episode of the fourth season of ''Lost''".
-- Add article to the tracking category: [[Category:Television episode articles with short description for single episodes]].
local function getShortDescriptionSingleEpisode(episodeOrdinalNumber, seasonOrdinalNumber, tvSeriesName)
	return episodeOrdinalNumber .. " episode of the " .. seasonOrdinalNumber .. " season of ''" .. tvSeriesName .. "''", createTrackingCategory(tvSeriesName, 4)
end

-- Local function which is used to create a short description for double episodes in the style of: "23rd and 24th episodes of the third season of ''Lost''".
-- Add article to the tracking category: [[Category:Television episode articles with short description for multi-part episodes]].
local function getShortDescriptionDoubleEpisode(episodeOrdinalNumber, secondEpisodeOrdinalNumber, seasonOrdinalNumber, tvSeriesName)
	return episodeOrdinalNumber .. " and " .. secondEpisodeOrdinalNumber .. " episodes of the " .. seasonOrdinalNumber .. " season of ''" .. tvSeriesName .. "''", createTrackingCategory(tvSeriesName, 5)
end

-- Local function which is 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 which is 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.
																											-- The number is less than 100;
		return getOrdinalIndicatorLessThan100(number)														-- 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 which is 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 which is 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 (conversion 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 which is used to return a clean version of the number.
-- This is done to make sure that no malformed episode or season values
-- have been entered. The function will remove all text which is not part
-- of the first number in the string.
--
-- The function converts entries such as:
-- "1.2" -> "1";
-- "12.2" -> "12";
-- "1<ref name="number" />" -> "1"
local function getCleanNumber(number)
	if (number ~= nil) then																					-- Check if the number is not null (some kind of value was entered).
		local cleanNumber = string.match(number, '%d+')														-- The value is not null; Clean the number, if needed.
		return cleanNumber																					-- Return the number.
	else
		return nil																							-- The number is nil; Return nil.
	end
end

-- Local function which is used to create a short description
-- by validating if a "multi_episodes" value was entered.
local function createDescriptionValidateEpisodeValue(episodeNumberText, seasonOrdinalNumber, tvSeriesName, isDoubleEpisode)
	local episodeNumber = getCleanNumber(episodeNumberText)													-- Call getCleanNumber() to return a cleaned version of the number.
	episodeNumber = tonumber(episodeNumber)																	-- Convert the value into a number.

	if (validateNumberParam(episodeNumber)) then															-- Call validateNumberParam() to check if an episode number was entered.
		local episodeOrdinalNumber = getEpisodeOrdinalNumber(episodeNumber)									-- A number was entered; Call getEpisodeOrdinalNumber() to get the episode ordinal number.

		if (isDoubleEpisode == nil) then																	-- Check if a multi_episodes value was entered.
																											-- A multi_episodes value was not entered;
			return getShortDescriptionSingleEpisode(
				episodeOrdinalNumber, seasonOrdinalNumber, tvSeriesName)									-- Call getShortDescriptionSingleEpisode() to get the episode's short description and return it.
		else																								-- A multi_episodes value was entered;
			local secondEpisodeOrdinalNumber = getEpisodeOrdinalNumber(episodeNumber + 1)					-- Call getEpisodeOrdinalNumber() and increment, to get the second episode ordinal number.
			return getShortDescriptionDoubleEpisode(
				episodeOrdinalNumber, secondEpisodeOrdinalNumber, seasonOrdinalNumber, tvSeriesName)		-- Call getShortDescriptionDoubleEpisode() to get the double episode's short description and return it.
		end
	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 which is used to retrieve the season number, since it can be entered in
-- either the "season" or "series_no" params.
local function getSeasonNumber(seasonNumber, seasonNumberUK)
	seasonNumber = getCleanNumber(seasonNumber)																-- Call getCleanNumber() to return a cleaned version of the number.
	seasonNumberUK = getCleanNumber(seasonNumberUK)															-- Call getCleanNumber() to return a cleaned version of the number.

	if (validateNumberParam(seasonNumber)) then																-- Call validateNumberParam() to check if the value
																											-- in the "|season_num" ("season") param is a number.
		return seasonNumber																					-- It is; Return value.
	elseif (validateNumberParam(seasonNumberUK)) then														-- Call validateNumberParam() to 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 which is used to create a short description
-- by validating if a season number was entered.
local function createDescriptionValidateSeasonValue(episodeNumberText, seasonNumber, seasonNumberUK, tvSeriesName, isDoubleEpisode)
	seasonNumber = getSeasonNumber(seasonNumber, seasonNumberUK)											-- Call getSeasonNumber() to get the season number, as it can be in one of two fields.

	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 which 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, seasonNumberUK, tvSeriesName, isDoubleEpisode, notDisambiguated)
	if (tvSeriesName ~= nil) then																			-- Check if a TV series name was entered.

		if (notDisambiguated == nil) then																	-- A TV series name was entered; 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 createDescriptionValidateSeasonValue(episodeNumberText,										-- Call createDescriptionValidateSeasonValue() to continue validation process.
			seasonNumber, seasonNumberUK, 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 which is used to clean the values from unwanted characters.
local function cleanValues(args)
	for _, v in ipairs({'episode_num', 'season_num', 'season_num_uk', 'series_name'}) do
		if args[v] then
			args[v] = args[v]:gsub('\127[^\127]*UNIQ%-%-(%a+)%-%x+%-QINU[^\127]*\127', '')					-- Remove all strip-markers.
			args[v] = args[v]:gsub('</? *br */?>', ' ')														-- Replace <br /> (and variants) with space character.
			args[v] = args[v]:gsub('%b<>[^<]+%b<>', '')														-- Remove html markup.
			args[v] = args[v]:gsub('%b<>', '')																-- Remove self-closed html tags.
			args[v] = args[v]:gsub('%[%[[^|]+|([^%]]+)%]%]', '%1')											-- Remove wiki-link retain label.
			args[v] = args[v]:gsub('%[%[([^%]]+)%]%]', '%1')												-- Remove wiki-link retain article.
			args[v] = args[v]:gsub('%[%S+ +([^%]]-)%]', '%1')												-- Remove URLs retain label.
			args[v] = args[v]:gsub('%[[^%]]-%]', '')														-- Remove all remaining URLs.

			if (args[v] == '') then																			-- Check if the value is an empty string.
				args[v] = nil																				-- The value is an empty string; Set it to nil.
			end
		end
	end
	return args																								-- Return args.
end

-- Local function which does the actual main process.
local function _getShortDescription(frame, args)
	args = cleanValues(args)																				-- Call cleanValues() to remove all unwanted characters.

	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).

	local test = args['test']																				-- This param should only be used by tests runned through /testcases.
	local doc = args['doc']																					-- This param should only be used by the documentation page.

	local shortDescription, trackingCat = createDescription(
		episodeNumberText, seasonNumber, seasonNumberUK, tvSeriesName, isDoubleEpisode, notDisambiguated)	-- Call createDescription() and return two values: the episode's short description and tracking category.

	if (test == nil and doc == nil) then																	-- Check if the invoking page is from /testcases or doc pages.
		local tableData = {shortDescription, 'noreplace'}													-- Invoking page isn't a test; Create a table for the short description parameter.
		return frame:expandTemplate({title = 'short description', args = tableData}) .. trackingCat			-- Return expanded short description with tracking category.
	else
		return shortDescription																				-- Invoking page is a test; Return only short description.
	end
end

-- Public function which is used to create a television episode's short description
-- from the data available in [[Template:Infobox television episode]].
-- A suitable description will be generated depending on the values
-- of the various parameters. See documentation 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.

	return _getShortDescription(frame, args)																-- Call _getShortDescription() to perform the actual process.
end

return p