Module:Region

The source of truth for world region data relevant to The Legend of Zelda series.

This module exports the following functions.

getRegion

getRegion(code, [options])

Parameters

• code

  A region code from Module:Region/Data.

• [options]

  [flagSize=20px]

  The image size to use for the region's flag(s).

Returns

• An object containing the region's name and flag(s), or nil if no region exists for the given code.
• An error category if no region exists for the given code.

Examples

#	Input	Output	Status
1	getRegion("ca")	Expected { name = "Canada", flag = '<span class="tooltip" title="Canada">[[File:Canada Flag.png|20px|Canada]]</span>', } Actual nil
		"[[Category:Articles using invalid arguments in template calls]]"
2	getRegion("cn", { flagSize = "15px" })	Expected { name = "China", flag = "<span class=\"tooltip\" title=\"The People's Republic of China\">[[File:China Flag.png|15px|The People's Republic of China]]</span>", } Actual nil
		"[[Category:Articles using invalid arguments in template calls]]"
3	getRegion("eur")	Expected { name = "Europe", flag = '<span class="tooltip" title="Europe">[[File:European Union Flag.png|20px|Europe]]</span>', } Actual nil
		"[[Category:Articles using invalid arguments in template calls]]"
4	getRegion("thm")	Expected { name = "Taiwan, Hong Kong, Macao", flag = '<span class="tooltip" title="The Republic of China">[[File:Taiwan Flag.svg|20px|The Republic of China]]</span><span class="tooltip" title="The Hong Kong Special Administrative Region of China">[[File:Hong Kong Flag.svg|20px|The Hong Kong Special Administrative Region of China]]</span><span class="tooltip" title="The Macao Special Administrative Region of China">[[File:Macao Flag.svg|20px|The Macao Special Administrative Region of China]]</span>', } Actual nil
		"[[Category:Articles using invalid arguments in template calls]]"
5	getRegion("narnia")	nil
		"[[Category:Articles using invalid arguments in template calls]]"

---

local p = {}
local h = {}
local Data = mw.loadData("Module:Region/Data")

local DEFAULT_FLAG_SIZE = "20px"
local CATEGORY_INVALID_ARGS = "[[Category:"..require("Module:Constants/category/invalidArgs").."]]"
local CLASS_TOOLTIP = require("Module:Constants/class/tooltip")

function p.getRegion(code, options)
	options = options or {}
	options.flagSize = options.flagSize or DEFAULT_FLAG_SIZE

	local region = Data.regions[code]
	if not region then
		local utilsError = require("Module:UtilsError")
		utilsError.warn(string.format("Invalid region <code>%s</code>. See [[Module:Region/Data]] for a list of supported regions.", code))
		return nil, CATEGORY_INVALID_ARGS
	else
		return {
			name = region.name,
			flag = h.flag(region, options),
		}
	end
end

function h.flag(region, options)
	if not region then
		return nil, CATEGORY_INVALID_ARGS
	elseif region.flag then
		local name = region.official or region.name
		local flagFile = region.flag
		local size = options.flagSize
		local flag = string.format('<span class="%s" title="%s">[[%s|%s|%s]]</span>', CLASS_TOOLTIP, name, flagFile, size, name)
		return flag, nil
	elseif region.countries then
		local flags = "" 
		for i, country in ipairs(region.countries) do
			flags = flags..p.getRegion(country).flag
		end
		return flags, nil
	else
		return "", nil
	end
end

function p.Documentation(frame)
	return {
		getRegion = {
			params = {"code", "options"},
			returns = {
				"An object containing the region's name and flag(s), or <code>nil</code> if no region exists for the given code.",
				"An error category if no region exists for the given code.",
			},
			cases = {
				outputOnly = true,
				{
					args = {"ca"},
					expect = {
						{
							name = "Canada",
							flag = '<span class="tooltip" title="Canada">[[File:Canada Flag.png|20px|Canada]]</span>',
						},
						nil,
					},
				},
				{
					args = {"cn", { flagSize = "15px" } },
					expect = {
						{
							name = "China",
							flag = "<span class=\"tooltip\" title=\"The People's Republic of China\">[[File:China Flag.png|15px|The People's Republic of China]]</span>",
						},
						nil,
					},
				},
				{
					args = {"eur"},
					expect = {
						{
							name = "Europe",
							flag = '<span class="tooltip" title="Europe">[[File:European Union Flag.png|20px|Europe]]</span>',
						},
						nil
					},
				},
				{
					args = {"thm"},
					expect = {
						{
							name = "Taiwan, Hong Kong, Macao",
							flag = '<span class="tooltip" title="The Republic of China">[[File:Taiwan Flag.svg|20px|The Republic of China]]</span><span class="tooltip" title="The Hong Kong Special Administrative Region of China">[[File:Hong Kong Flag.svg|20px|The Hong Kong Special Administrative Region of China]]</span><span class="tooltip" title="The Macao Special Administrative Region of China">[[File:Macao Flag.svg|20px|The Macao Special Administrative Region of China]]</span>',
						},
						nil,
					},
				},
				{
					args = {"narnia"},
					expect = {
						nil,
						CATEGORY_INVALID_ARGS,
					},
				},
			},
		},
	}
end

function p.Schemas(frame)
	return {
		getRegion = {
			code = {
				required = true,
				type = "string",
				desc = "A region code from [[Module:Region/Data]]."
			},
			options = {
				type = "record",
				properties = {
					{
						name = "flagSize",
						type = "string",
						default = DEFAULT_FLAG_SIZE,
						desc = "The image size to use for the region's flag(s).",
					},
				},
			},
		},
		Data = {
			type = "record",
			required = true,
			properties = {
				{
					name = "regions",
					required = true,
					type = "map",
					desc = "A list of regions that Nintendo (or other Zelda-related companies) markets to.",
					keyPlaceholder = "code",
					keys = {
						type = "string",
						desc = "An {{Wp|ISO 3166-1 alpha-2}} country code, or a 3+ character code denoting a multi-country region forming a single market segment.",
					},
					values = {
						type = "record",
						properties = {
							{
								name = "name",
								required = true,
								type = "string",
								desc = "The name of the country or region.",
							},
							{
								name = "official",
								type = "string",
								desc = "The official state name of the country. Defaults to <code>name</code>.",
							},
							{
								name = "flag",
								type = "string",
								desc = "The file name of the region's flag",
							},
							{
								name = "countries",
								type = "array",
								items = { type = "string" },
								desc = "For multi-country regions, a list of country codes that comprise the region.",
							},
						},
					},
				},
			},
		}
	}
end

function p.Data(frame)
	local utilsLayout = require("Module:UtilsLayout")
	local utilsTable = require("Module:UtilsTable")

	local countries = {}
	local multiCountryRegions = {}
	
	for code in pairs(Data.regions) do
		local region = p.getRegion(code)
		local row = {
			id = code,
			cells = {
				"<code>"..code.."</code>",
				region.flag,
				region.name,
			}
		}
		if code:len() == 2 then
			table.insert(countries, row)
		else
			table.insert(multiCountryRegions, row)
		end
	end
	countries = utilsTable.sortBy(countries, "id")
	multiCountryRegions = utilsTable.sortBy(multiCountryRegions, "id")
	
	
	local countriesTable = utilsLayout.table({
		caption = "Countries",
		sortable = {1, 3},
		headers = {"{{Wp|ISO 3166-1 alpha-2|Code}}", "Flag", "Name"},
		rows = countries,
	})
	local multiCountryRegionsTable = utilsLayout.table({
		caption = "Multi-Country Regions",
		sortable = {1, 3},
		headers = {"Code", "Flags", "Name"},
		rows = multiCountryRegions,
	})

	local html = mw.html.create("div")
		:css({
			["display"] = "flex",
			["flex-wrap"] = "wrap",
			["gap"] = "1rem",
		})
		:wikitext(countriesTable)
		:wikitext(multiCountryRegionsTable)

	return tostring(html)
end

return p