Module:Wd

Documentation for this module may be created at Module:Wd/doc

local p = {}

local aliasesP = {
	coord           = "P625",
	
	author          = "P50",
	publisher       = "P123",
	importedFrom    = "P143",
	statedIn        = "P248",
	publicationDate = "P577",
	startTime       = "P580",
	endTime         = "P582",
	retrieved       = "P813",
	referenceURL    = "P854",
	archiveURL      = "P1065",
	title           = "P1476",
	quote           = "P1683",
	shortName       = "P1813",
	language        = "P2439",
	archiveDate     = "P2960"
}

local aliasesQ = {
	percentage              = "Q11229",
	prolepticJulianCalendar = "Q1985786"
}

local parameters = {
	property  = "%p",
	qualifier = "%q",
	reference = "%r",
	separator = "%s"
}

local formats = {
	property              = "%p[%s][%r]",
	qualifier             = "%q[%s][%r]",
	reference             = "%r",
	propertyWithQualifier = "%p[ <span style=\"font-size:smaller\">(%q)</span>][%s][%r]"
}

local hookNames = {
	                      -- {level_1, level_2}
	[parameters.property]  = {"getProperty"},
	[parameters.qualifier] = {"getQualifiers", "getQualifier"},
	[parameters.reference] = {"getReferences", "getReference"}
}

local Config = {}
Config.__index = Config

-- allows for recursive calls
function Config.new()
	local cfg = {}
	setmetatable(cfg, Config)
	
	cfg.separators = {
		-- use tables so that we can pass by reference
		["sep"]   = {" "},
		["sep%s"] = {","},
		["sep%q"] = {", "},
		["sep%r"] = {""},
		["punc"] = {""}
	}
	
	cfg.entity = nil
	cfg.propertyID = nil
	cfg.propertyValue = nil
	cfg.qualifierID = nil
	
	cfg.bestRank = true
	cfg.foundRank = 3
	cfg.maxRank = nil
	cfg.minRank = nil
	cfg:setRankBoundaries("best")
	
	cfg.period = 0
	cfg.mdyDate = false
	
	cfg.pageTitle = false
	
	cfg.langCode = mw.language.getContentLanguage().code
	cfg.langName = mw.language.fetchLanguageName(cfg.langCode, cfg.langCode)
	cfg.langObj = mw.language.new(cfg.langCode)
	
	cfg.states = {}
	cfg.curState = nil
	
	return cfg
end

local State = {}
State.__index = State

function State.new(cfg)
	local stt = {}
	setmetatable(stt, State)
	
	stt.conf = cfg
	
	stt.outPreferred = {}
	stt.outNormal = {}
	stt.outDeprecated = {}
	
	stt.parsedFormat = {}
	stt.separator = {}
	stt.movSeparator = {}
	stt.puncMark = {}
	
	stt.linked = false
	stt.rawValue = false
	stt.shortName = false
	stt.singleValue = false
	
	return stt
end

function unknownDataTypeError(dataType)
	return "<strong class=\"error\">Unknown or unsupported datatype '" .. dataType .. "'.</strong>"
end

function missingRequiredParameterError()
	return "<strong class=\"error\">No required parameters defined, needing at least one.</strong>"
end

function extraRequiredParameterError(param)
	return "<strong class=\"error\">Parameter '" .. param .. "' must be defined as optional.</strong>"
end

function parseWikidataURL(url)
	local i, j
	
	if url:match('^http[s]?://') then
		i, j = url:find("Q")
		
		if i then
			return url:sub(i)
		end
	end
	
	return nil
end

function parseDate(dateStr, precision)
	precision = precision or "d"
	local i, j, index, ptr
	local parts = {nil, nil, nil}
	
	if dateStr == nil then
		return parts[1], parts[2], parts[3]  -- year, month, day
	end
	
	-- 'T' for snak values, '/' for outputs with '/Julian' attached
	i, j = dateStr:find("[T/]")
	
	if i then
		dateStr = dateStr:sub(1, i-1)
	end
	
	local from = 1
	
	if dateStr:sub(1,1) == "-" then
		-- this is a negative number, look further ahead
		from = 2
	end
	
	index = 1
	ptr = 1
	
	i, j = dateStr:find("-", from)
	
	if i then
		-- year
		parts[index] = tonumber(mw.ustring.gsub(dateStr:sub(ptr, i-1), "^\+(.+)$", "%1"), 10)  -- remove + sign
		
		if parts[index] == -0 then
			parts[index] = 0
		end
		
		if precision == "y" then
			-- we're done
			return parts[1], parts[2], parts[3]  -- year, month, day
		end
		
		index = index + 1
		ptr = i + 1
		
		i, j = dateStr:find("-", ptr)
		
		if i then
			-- month
			parts[index] = tonumber(dateStr:sub(ptr, i-1), 10)
			
			if precision == "m" then
				-- we're done
				return parts[1], parts[2], parts[3]  -- year, month, day
			end
			
			index = index + 1
			ptr = i + 1
		end
	end
	
	if dateStr:sub(ptr) ~= "" then
		-- day if we have month, month if we have year, or year
		parts[index] = tonumber(dateStr:sub(ptr), 10)
	end
	
	return parts[1], parts[2], parts[3]  -- year, month, day
end

function convertUnit(unit, link)
	link = link or false
	local itemID, label, title
	
	if unit == "" or unit == "1" then
		return nil
	end
	
	itemID = parseWikidataURL(unit)
	
	if itemID then
		if itemID == aliasesQ.percentage then
			return "%"
		else
			label = mw.wikibase.label(itemID)
			title = nil
			
			if link or label == nil then
				title = mw.wikibase.sitelink(itemID)
			end
			
			if link then
				if title then
					return " " .. "[[" .. title .. "|" .. (label or title) .. "]]"
				end
				
				if not label then
					return " " .. "[[d:" .. itemID .. "|" .. itemID .. "]]"
				end
			end
			
			return " " .. (label or title or itemID)
		end
	end
	
	return " " .. unit
end

function getOrdinalSuffix(num)
	if tostring(num):sub(-2,-2) == '1' then
		return "th"  -- 10th, 11th, 12th, 13th, ... 19th
	end
	
	num = tostring(num):sub(-1)
	
	if num == '1' then
		return "st"
	elseif num == '2' then
		return "nd"
	elseif num == '3' then
		return "rd"
	else
		return "th"
	end
end

function addDecimalMarks(n)
	local left,num,right = string.match(n,'^([^%d]*%d)(%d*)(.-)$')
	return left..(num:reverse():gsub('(%d%d%d)','%1,'):reverse())..right
end

function convertRank(rank)
	if (rank == "preferred") then
		return 1
	elseif (rank == "normal") then
		return 2
	elseif (rank == "deprecated") then
		return 3
	else
		return 4  -- default (in its literal sense)
	end
end

function datePrecedesDate(aY, aM, aD, bY, bM, bD)
	if aY == nil or bY == nil then
		return nil
	end
	aM = aM or 1
	aD = aD or 1
	bM = bM or 1
	bD = bD or 1
	
	if aY < bY then
		return true
	end
	
	if aY > bY then
		return false
	end
	
	if aM < bM then
		return true
	end
	
	if aM > bM then
		return false
	end
	
	if aD < bD then
		return true
	end
	
	return false
end

function alwaysTrue()
	return true
end

function parseFormat(str)
	local chr, esc, param, root, cur
	local params = {}
	
	local function newObject(array)
		local obj = {}  -- new object
		obj.str = ""
		
		array[#array + 1] = obj  -- array{object}
		obj.parent = array
		
		return obj
	end
	
	root = {}  -- array
	root.req = {}
	cur = newObject(root)
	
	esc = false
	param = false
	
	for i = 1, #str do
		chr = str:sub(i,i)
		
		if not esc then
			if chr == '\\' then
				esc = true
			elseif chr == '%' then
				cur = newObject(cur.parent)
				param = true
			else
				if chr == '[' then
					cur.child = {}  -- new array
					cur.child.req = {}
					cur.child.parent = cur
					cur = newObject(cur.child)
				elseif chr == ']' then
					if cur.parent.parent then
						cur = newObject(cur.parent.parent.parent)
					end
				else
					cur.str = cur.str .. chr
					
					if param then
						cur.str = "%"..cur.str
						cur.param = true
						params[cur.str] = true
						cur.parent.req[cur.str] = true
						cur = newObject(cur.parent)
					end
				end
				
				param = false
			end
		else
			cur.str = cur.str .. chr
			esc = false
			
			if param then
				cur.str = "%"..cur.str
				cur.param = true
				params[cur.str] = true
				cur.parent.req[cur.str] = true
				cur = newObject(cur.parent)
				param = false
			end
		end
	end
	
	return root, params
end

function getShortName(itemID)
	return p._property({itemID, aliasesP.shortName})  -- "property" is single
end

function getLabel(ID)
	return p._label({ID})
end

function Config:getValue(snak, raw, link, short, anyLang)
	raw = raw or false
	link = link or false
	short = short or false
	anyLang = anyLang or false
	
	if snak.snaktype == 'value' then
		if snak.datavalue.type == 'string' then
			return snak.datavalue.value
		elseif snak.datavalue.type == 'monolingualtext' then
			if anyLang then
				return snak.datavalue.value['text'], snak.datavalue.value['language']
			elseif snak.datavalue.value['language'] == self.langCode then
				return snak.datavalue.value['text']
			else
				return nil
			end
		elseif snak.datavalue.type == 'quantity' then
			-- strip + signs from front
			local value = mw.ustring.gsub(snak.datavalue.value['amount'], "^\+(.+)$", "%1")
			
			if not raw then
				value = addDecimalMarks(value)
				local unit = convertUnit(snak.datavalue.value['unit'], link)
				if unit then
					value = value .. unit
				end
			end
			
			return value
		elseif snak.datavalue.type == 'time' then
			local y, m, d, p, yDiv, yRound, yFull, value, calendarID, dateStr
			local yFactor = 1
			local sign = 1
			local suffix = ""
			local mayAddCalendar = false
			local calendar = ""
			local precision = snak.datavalue.value['precision']
			
			if precision == 11 then
				p = "d"
			elseif precision == 10 then
				p = "m"
			else
				p = "y"
				yFactor = 10^(9-precision)
			end
			
			y, m, d = parseDate(snak.datavalue.value['time'], p)
			
			if y < 0 then
				sign = -1
				y = y * sign
			end
			
			-- if precision is tens/hundreds/thousands/millions/billions of years
			if precision <= 8 then
				yDiv = y / yFactor
				
				-- if precision is tens/hundreds/thousands of years
				if precision >= 6 then
					mayAddCalendar = true
					
					if precision <= 7 then
						-- round centuries/millenniums up (e.g. 20th century or 3rd millennium)
						yRound = math.ceil(yDiv)
						
						if not raw then
							if precision == 6 then
								suffix = " millennium"
							else
								suffix = " century"
							end
							
							suffix = getOrdinalSuffix(yRound) .. suffix
						else
							-- if not verbose, take the first year of the century/millennium
							-- (e.g. 1901 for 20th century or 2001 for 3rd millennium)
							yRound = (yRound - 1) * yFactor + 1
						end
					else
						-- precision == 8
						-- round decades down (e.g. 2010s)
						yRound = math.floor(yDiv) * yFactor
						
						if not raw then
							suffix = "s"
						end
					end
					
					if raw and sign < 0 then
						-- if BCE then compensate for "counting backwards"
						-- (e.g. -2019 for 2010s BCE, -2000 for 20th century BCE or -3000 for 3rd millennium BCE)
						yRound = yRound + yFactor - 1
					end
				else
					local yReFactor, yReDiv, yReRound
					
					-- round to nearest for tens of thousands of years or more
					yRound = math.floor(yDiv + 0.5)
					
					if yRound == 0 then
						if precision <= 2 and y ~= 0 then
							yReFactor = 1e6
							yReDiv = y / yReFactor
							yReRound = math.floor(yReDiv + 0.5)
							
							if yReDiv == yReRound then
								-- change precision to millions of years only if we have a whole number of them
								precision = 3
								yFactor = yReFactor
								yRound = yReRound
							end
						end
						
						if yRound == 0 then
							-- otherwise, take the unrounded (original) number of years
							precision = 5
							yFactor = 1
							yRound = y
							mayAddCalendar = true
						end
					end
					
					if precision >= 1 and y ~= 0 then
						yFull = yRound * yFactor
						
						yReFactor = 1e9
						yReDiv = yFull / yReFactor
						yReRound = math.floor(yReDiv + 0.5)
						
						if yReDiv == yReRound then
							-- change precision to billions of years if we're in that range
							precision = 0
							yFactor = yReFactor
							yRound = yReRound
						else
							yReFactor = 1e6
							yReDiv = yFull / yReFactor
							yReRound = math.floor(yReDiv + 0.5)
							
							if yReDiv == yReRound then
								-- change precision to millions of years if we're in that range
								precision = 3
								yFactor = yReFactor
								yRound = yReRound
							end
						end
					end
					
					if not raw then
						if precision == 3 then
							suffix = " million years"
						elseif precision == 0 then
							suffix = " billion years"
						else
							yRound = yRound * yFactor
							if yRound == 1 then
								suffix = " year"
							else
								suffix = " years"
							end
						end
					else
						yRound = yRound * yFactor
					end
				end
			else
				yRound = y
				mayAddCalendar = true
			end
			
			if mayAddCalendar then
				calendarID = parseWikidataURL(snak.datavalue.value['calendarmodel'])
				
				if calendarID and calendarID == aliasesQ.prolepticJulianCalendar then
					if not raw then
						if link then
							calendar = " ([[Julian calendar|Julian]])"
						else
							calendar = " (Julian)"
						end
					else
						calendar = "/Julian"
					end
				end
			end
			
			if not raw then
				local ce = nil
				
				if sign < 0 then
					ce = "BCE"
				elseif precision <= 5 then
					ce = "CE"
				end
				
				if ce then
					if link then
						ce = "[[Common Era|" .. ce .. "]]"
					end
					suffix = suffix .. " " .. ce
				end
				
				value = tostring(yRound)
				
				if m then
					dateStr = self.langObj:formatDate("F", "1-"..m.."-1")
					
					if d then
						if self.mdyDate then
							dateStr = dateStr .. " " .. d .. ","
						else
							dateStr = d .. " " .. dateStr
						end
					end
					
					value = dateStr .. " " .. value
				end
				
				value = value .. suffix .. calendar
			else
				value = tostring(yRound * sign)
				
				if m then
					value = value .. "-" .. m
					
					if d then
						value = value .. "-" .. d
					end
				end
				
				value = value .. calendar
			end
			
			return value
		elseif snak.datavalue.type == 'globecoordinate' then
			local precision, numDigits, strFormat, value, globe
			local latValue, latitude, latDegrees, latMinutes, latSeconds
			local latDirection = "N"
			local lonValue, longitude, lonDegrees, lonMinutes, lonSeconds
			local lonDirection = "E"
			
			local degSymbol = "°"
			local minSymbol = "'"
			local secSymbol = '"'
			local partsGlue = ", "
			
			if raw then
				degSymbol = "/"
				minSymbol = "/"
				secSymbol = "/"
				partsGlue = "/"
			end
			
			latitude = snak.datavalue.value['latitude']
			longitude = snak.datavalue.value['longitude']
			
			if latitude < 0 then
				latDirection = "S"
				latitude = math.abs(latitude)
			end
			if longitude < 0 then
				lonDirection = "W"
				longitude = math.abs(longitude)
			end
			
			precision = snak.datavalue.value['precision']
			
			latitude = math.floor(latitude / precision + 0.5) * precision
			longitude = math.floor(longitude / precision + 0.5) * precision
			
			latDegrees = math.floor(latitude)
			lonDegrees = math.floor(longitude)
			
			latMinutes = math.floor((latitude - latDegrees) * 60)
			lonMinutes = math.floor((longitude - lonDegrees) * 60)
			
			latSeconds = (latitude - (latDegrees + latMinutes / 60)) * 3600
			lonSeconds = (longitude - (lonDegrees + lonMinutes / 60)) * 3600
			
			latValue = latDegrees .. degSymbol
			lonValue = lonDegrees .. degSymbol
			
			if precision < 1 then
				latValue = latValue .. latMinutes .. minSymbol
				lonValue = lonValue .. lonMinutes .. minSymbol
			end
			
			if precision < (1 / 60) then
				numDigits = math.ceil(-math.log10(3600 * precision))
				
				if numDigits < 0 or numDigits == -0 then
					numDigits = 0
				end
				
				strFormat = "%." .. numDigits .. "f"
				
				latSeconds = string.format(strFormat, latSeconds)
				lonSeconds = string.format(strFormat, lonSeconds)
				
				latValue = latValue .. latSeconds .. secSymbol
				lonValue = lonValue .. lonSeconds .. secSymbol
			end
			
			latValue = latValue .. latDirection
			lonValue = lonValue .. lonDirection
			
			value = latValue .. partsGlue .. lonValue
			
			if link then
				globe = parseWikidataURL(snak.datavalue.value['globe'])
				
				if globe then
					globe = mw.wikibase.label(globe):lower()
				else
					globe = "earth"
				end
				
				value = "[https://tools.wmflabs.org/geohack/geohack.php?language="..self.langCode.."&params="..latitude.."_"..latDirection.."_"..longitude.."_"..lonDirection.."_globe:"..globe.." "..value.."]"
			end
			
			return value
		elseif snak.datavalue.type == 'wikibase-entityid' then
			local value = ""
			local title = nil
			local itemID = "Q" .. snak.datavalue.value['numeric-id']
			
			if raw then
				if link then
					return "[[d:" .. itemID .. "|" .. itemID .. "]]"
				else
					return itemID
				end
			end
			
			if short then
				value = getShortName(itemID)
			end
			
			if value == "" then
				value = mw.wikibase.label(itemID)
			end
			
			if link or value == nil then
				title = mw.wikibase.sitelink(itemID)
			end
			
			if link then
				if title then
					value = "[[" .. title .. "|" .. (value or title) .. "]]"
				elseif not value then
					value = "[[d:" .. itemID .. "|" .. itemID .. "]]"
				end
			elseif not value then
				value = (title or itemID)
			end
			
			return value
		else
			return unknownDataTypeError(snak.datavalue.type)
		end
	elseif snak.snaktype == 'somevalue' then
		if raw then
			return " "  -- single space represents 'somevalue'
		else
			return "unknown"
		end
	elseif snak.snaktype == 'novalue' then
		if raw then
			return ""  -- empty string represents 'novalue'
		else
			return "none"
		end
	else
		return nil
	end
end

function Config:getSingleRawQualifier(claim, qualifierID)
	local qualifiers
	
	if claim.qualifiers then qualifiers = claim.qualifiers[qualifierID] end
	
	if qualifiers and qualifiers[1] then
		return self:getValue(qualifiers[1], true)  -- raw = true
	else
		return nil
	end
end

function Config:snakEqualsValue(snak, value)
	local snakValue = self:getValue(snak, true)  -- raw = true
	
	if snakValue and snak.snaktype == 'value' and snak.datavalue.type == 'wikibase-entityid' then value = value:upper() end
	
	return snakValue == value
end

function Config:setRankBoundaries(rank)
	local rankPos
	
	self.foundRank = 3  -- must equal the lowest possible rank
	
	if (rank == "best") then
		self.bestRank = true
		return
	else
		self.bestRank = false
	end
	
	if (rank:sub(1,9) == "preferred") then
		rankPos = 1
	elseif (rank:sub(1,6) == "normal") then
		rankPos = 2
	elseif (rank:sub(1,10) == "deprecated") then
		rankPos = 3
	end
	
	if (rank:sub(-1) == "+") then
		self.maxRank = 1
		self.minRank = rankPos
	elseif (rank:sub(-1) == "-") then
		self.maxRank = rankPos
		self.minRank = 3
	else
		self.maxRank = rankPos
		self.minRank = rankPos
	end
end

function Config:processFlag(flag)
	if flag == "linked" then
		self.curState.linked = true
		return true
	elseif flag == "raw" then
		self.curState.rawValue = true
		
		if self.curState == self.states[parameters.reference] then
			-- raw reference values end with periods and require a separator different from ""
			self.separators["sep%r"][1] = " "
		end
		
		return true
	elseif flag == "short" then
		self.curState.shortName = true
		return true
	elseif flag == "mdy" then
		self.mdyDate = true
		return true
	elseif flag == "best" or flag:match('^preferred[+-]?$') or flag:match('^normal[+-]?$') or flag:match('^deprecated[+-]?$') then
		self:setRankBoundaries(flag)
		return true
	elseif flag == "future" then
		self.period = 1
		return true
	elseif flag == "current" then
		self.period = 2
		return true
	elseif flag == "former" then
		self.period = 3
		return true
	elseif flag == "" then
		-- ignore empty flags and carry on
		return true
	else
		return false
	end
end

function Config:processFlagOrCommand(flag)
	local param = ""
	
	if flag == "property" or flag == "properties" then
		param = parameters.property
	elseif flag:match('^qualifier[s]?$') then
		param = parameters.qualifier
	elseif flag:match('^reference[s]?$') then
		param = parameters.reference
	else
		return self:processFlag(flag)
	end
	
	if self.states[param] then
		return false
	end
	
	-- create a new State for each command
	self.states[param] = State.new(self)
	
	-- use "%x" as the general parameter name
	self.states[param].parsedFormat = parseFormat("%x")  -- will be overwritten for param=="%p"
	
	-- set the separator
	self.states[param].separator = self.separators["sep"..param]  -- will be nil for param=="%p", which will be set separately
	
	if string.sub(flag, -1) ~= 's' then
		self.states[param].singleValue = true
	end
	
	self.curState = self.states[param]
	
	return true
end

function Config:rankMatches(rankPos)
	if self.bestRank then
		return self.foundRank >= rankPos
	else
		return (self.maxRank <= rankPos and rankPos <= self.minRank)
	end
end

function Config:timeMatches(claim)
	local startTime = nil
	local startTimeY = nil
	local startTimeM = nil
	local startTimeD = nil
	local endTime = nil
	local endTimeY = nil
	local endTimeM = nil
	local endTimeD = nil
	
	if self.period == 0 then
		-- any time
		return true
	end
	
	local now = os.date('!*t')
	
	startTime = self:getSingleRawQualifier(claim, aliasesP.startTime)
	if startTime and startTime ~= "" and startTime ~= " " then
		startTimeY, startTimeM, startTimeD = parseDate(startTime)
	end
	
	endTime = self:getSingleRawQualifier(claim, aliasesP.endTime)
	if endTime and endTime ~= "" and endTime ~= " " then
		endTimeY, endTimeM, endTimeD = parseDate(endTime)
	elseif endTime == " " then
		-- end time is 'unknown', assume it is somewhere in the past;
		-- we can do this by taking the current date as a placeholder for the end time
		endTimeY = now['year']
		endTimeM = now['month']
		endTimeD = now['day']
	end
	
	if startTimeY ~= nil and endTimeY ~= nil and datePrecedesDate(endTimeY, endTimeM, endTimeD, startTimeY, startTimeM, startTimeD) then
		-- invalidate end time if it precedes start time
		endTimeY = nil
		endTimeM = nil
		endTimeD = nil
	end
	
	if self.period == 1 then
		-- future
		if startTimeY == nil or not datePrecedesDate(now['year'], now['month'], now['day'], startTimeY, startTimeM, startTimeD) then
			return false
		else
			return true
		end
	elseif self.period == 2 then
		-- current
		if (startTimeY ~= nil and datePrecedesDate(now['year'], now['month'], now['day'], startTimeY, startTimeM, startTimeD)) or
		   (endTimeY ~= nil and not datePrecedesDate(now['year'], now['month'], now['day'], endTimeY, endTimeM, endTimeD)) then
		    return false
		else
		   	return true
		end
	elseif self.period == 3 then
		-- former
		if endTimeY == nil or datePrecedesDate(now['year'], now['month'], now['day'], endTimeY, endTimeM, endTimeD) then
			return false
		else
			return true
		end
	end
end

function State:claimMatches(claim)
	local matches, rankPos
	
	-- if a property value was given, check if it matches the claim's property value
	if self.conf.propertyValue then
		matches = self.conf:snakEqualsValue(claim.mainsnak, self.conf.propertyValue)
	else
		matches = true
	end
	
	-- check if the claim's rank and time period match
	rankPos = convertRank(claim.rank)
	matches = (matches and self.conf:rankMatches(rankPos) and self.conf:timeMatches(claim))
	
	return matches, rankPos
end

function State:appendOutput(result, rankPos)
	local done = false
	
	-- a rankPos should only apply to complete claims, not to its individual qualifiers or references;
	-- for the latter two, no rankPos should be given and their default rankPos must be the highest possible (i.e. 1)
	if rankPos then
		if (self.conf.bestRank or self.singleValue) and self.conf.foundRank > rankPos then
			self.conf.foundRank = rankPos
			
			-- found a better rank, reset worse rank outputs
			if self.conf.foundRank == 1 then
				self.outNormal = {}
				self.outDeprecated = {}
			elseif self.conf.foundRank == 2 then
				self.outDeprecated = {}
			end
		end
	else
		rankPos = 1
	end
	
	if rankPos == 1 then
		self.outPreferred[#self.outPreferred + 1] = result
		
		if self.singleValue then
			done = true
		end
	elseif rankPos == 2 then
		self.outNormal[#self.outNormal + 1] = result
		
		if self.singleValue and not self.conf.bestRank and self.conf.maxRank == 2 then
			done = true
		end
	elseif rankPos == 3 then
		self.outDeprecated[#self.outDeprecated + 1] = result
		
		if self.singleValue and not self.conf.bestRank and self.conf.maxRank == 3 then
			done = true
		end
	end
	
	return done
end

function State:out()
	local out = ""
	
	local function walk(formatTable, result)
		local str = ""
		
		for i, v in pairs(formatTable.req) do
			if not result[i] then
				-- we've got no result for a parameter that is required on this level,
				-- so skip this level (and its children) by returning an empty string
				return ""
			end
		end
		
		for i, v in ipairs(formatTable) do
			if v.param then
				str = str .. result[v.str]
			else
				str = str .. v.str
			end
			
			if v.child then
				str = str .. walk(v.child, result)
			end
		end
		
		return str
	end
	
	local function prepend(results)
		local sep = ""
		local result, value
		
		-- iterate from back to front, so that we know when to add separators
		for i = #results, 1, -1 do
			result = results[i]
			
			-- if there is already some output, then add the separators
			if out ~= "" then
				sep = self.separator[1]  -- fixed separator
				result[parameters.separator] = self.movSeparator[1]  -- movable separator
			else
				sep = ""
				result[parameters.separator] = self.puncMark[1]  -- optional punctuation mark
			end
			
			value = walk(self.parsedFormat, result)
			
			if value ~= "" then
				out = value .. sep .. out
			end
		end
	end
	
	prepend(self.outDeprecated)
	prepend(self.outNormal)
	prepend(self.outPreferred)
	
	-- reset state before next iteration
	self.outDeprecated = {}
	self.outNormal = {}
	self.outPreferred = {}
	
	return out
end

-- level 1 hook
function State:getProperty(claim)
	return self.conf:getValue(claim.mainsnak, self.rawValue, self.linked, self.shortName)
end

-- level 1 hook
function State:getQualifiers(claim)
	local qualifiers
	
	if claim.qualifiers then qualifiers = claim.qualifiers[self.conf.qualifierID] end
	if qualifiers then
		-- iterate through claim's qualifier statements to collect their values
		return self.conf.states[parameters.qualifier]:iterate(qualifiers, {["%x"] = hookNames[parameters.qualifier][2], count = 1})  -- pass qualifier State with level 2 hook
	else
		return nil
	end
end

-- level 2 hook
function State:getQualifier(snak)
	return self.conf:getValue(snak, self.rawValue, self.linked, self.shortName)
end

-- level 1 hook
function State:getReferences(claim)
	if claim.references then
		-- iterate through claim's reference statements to collect their values
		return self.conf.states[parameters.reference]:iterate(claim.references, {["%x"] = hookNames[parameters.reference][2], count = 1})  -- pass reference State with level 2 hook
	else
		return nil
	end
end

-- level 2 hook
-- logic determined based on https://www.wikidata.org/wiki/Help:Sources
function State:getReference(statement)
	local snakValue, lang, property
	local value = ""
	local snaks = {}
	local params = {}
	local leadParams = {}
	
	if statement.snaks then
		for i, v in pairs(statement.snaks) do
			if v[1] then
				snaks[i] = v[1]
			end
		end
		
		if snaks[aliasesP.importedFrom] then
			snaks[aliasesP.importedFrom] = nil
		end
		
		if snaks[aliasesP.referenceURL] and snaks[aliasesP.title] then
			params["url"] = self.conf:getValue(snaks[aliasesP.referenceURL])
			params["title"] = self.conf:getValue(snaks[aliasesP.title], false, false, false, true)  -- anyLang = true
			
			if snaks[aliasesP.publicationDate] then params["date"]         = self.conf:getValue(snaks[aliasesP.publicationDate])                  end
			if snaks[aliasesP.retrieved]       then params["access-date"]  = self.conf:getValue(snaks[aliasesP.retrieved])                        end
			if snaks[aliasesP.archiveURL]      then params["archive-url"]  = self.conf:getValue(snaks[aliasesP.archiveURL])                       end
			if snaks[aliasesP.archiveDate]     then params["archive-date"] = self.conf:getValue(snaks[aliasesP.archiveDate])                      end
			if snaks[aliasesP.author]          then params["author"]       = self.conf:getValue(snaks[aliasesP.author])                           end
			if snaks[aliasesP.publisher]       then params["publisher"]    = self.conf:getValue(snaks[aliasesP.publisher])                        end
			if snaks[aliasesP.quote]           then params["quote"]        = self.conf:getValue(snaks[aliasesP.quote], false, false, false, true) end  -- anyLang = true
			
			if snaks[aliasesP.language] then
				snakValue = self.conf:getValue(snaks[aliasesP.language])
				
				if self.conf.langName ~= snakValue then
					params["language"] = snakValue
				end
			end
			
			value = mw.getCurrentFrame():expandTemplate{title="cite_web", args=params}
		else
			for i, v in pairs(snaks) do
				property = getLabel(i)
				
				if property ~= "" then
					snakValue, lang = self.conf:getValue(v, false, (i == aliasesP.statedIn), false, true)  -- link = true/false, anyLang = true
					
					if lang and lang ~= self.conf.langCode then
						snakValue = "''" .. snakValue .. "'' (" .. mw.language.fetchLanguageName(lang, self.conf.langCode) .. ")"
					end
					
					if i == aliasesP.referenceURL or i == aliasesP.statedIn then
						leadParams[#leadParams + 1] = snakValue
					elseif i ~= aliasesP.language or self.conf.langName ~= snakValue then
						params[#params + 1] = property .. ": " .. snakValue
					end
				end
			end
			
			value = table.concat(leadParams, "; ")
			params = table.concat(params, "; ")
			
			if params ~= "" then
				if value ~= "" then
					value = value .. "; "
				end
				value = value .. params
			end
			
			if value ~= "" then
				value = value .. "."
			end
		end
		
		if value ~= "" then
			if not self.rawValue then
				-- add <ref> tags with the reference's hash as its name (to deduplicate references)
				value = mw.getCurrentFrame():extensionTag("ref", value, {name = statement.hash})
			end
		else
			value = nil
		end
	end
	
	return value
end

-- iterate through claims, claim's qualifiers or claim's references to collect values
function State:iterate(statements, hooks, matchHook)
	matchHook = matchHook or alwaysTrue
	
	local done = false
	local matches = false
	local rankPos = nil
	local result, numValues, doAppend, gotRequired
	
	for i, v in ipairs(statements) do
		-- rankPos will be nil for non-claim statements (e.g. qualifiers, references, etc.),
		-- but let appendOutput handle that
		matches, rankPos = matchHook(self, v)
		
		if matches then
			result = {count = 0}
			doAppend = true
			
			-- if we need to return a single value, check if we don't have one already
			if self.singleValue then
				if not rankPos or rankPos == 1 then
					numValues = #self.outPreferred
				elseif rankPos == 2 then
					numValues = #self.outNormal
				elseif rankPos == 3 then
					numValues = #self.outDeprecated
				end
				
				if numValues > 0 then
					doAppend = false
				end
			end
			
			if doAppend then
				local function walk(formatTable)
					local value
					
					for i2, v2 in pairs(formatTable.req) do
						if not result[i2] and hooks[i2] then
							-- call a hook and add its return value to the result
							value = self[hooks[i2]](self, v)
							
							if value then
								result[i2] = value
								result.count = result.count + 1
							else
								return false  -- we miss a required value for this level
							end
						end
						
						if result.count == hooks.count then
							-- we're done if all hooks have been called;
							-- returning at this point breaks the loop
							return true
						end
					end
					
					for i2, v2 in ipairs(formatTable) do
						if result.count == hooks.count then
							-- we're done if all hooks have been called;
							-- returning at this point prevents further childs from being processed
							return true
						end
						
						if v2.child then
							walk(v2.child)
						end
					end
					
					return true
				end
				gotRequired = walk(self.parsedFormat)
				
				-- only append the result if we got values for all required parameters on the root level
				if gotRequired then
					done = self:appendOutput(result, rankPos)
					if done then
						break
					end
				end
			end
		end
	end
	
	return self:out()
end

function p.property(frame)
	return p._property(frame.args)
end

function p._property(args)
	return execCommand(args, "property")
end

function p.properties(frame)
	return p._properties(frame.args)
end

function p._properties(args)
	return execCommand(args, "properties")
end

function p.qualifier(frame)
	return p._qualifier(frame.args)
end

function p._qualifier(args)
	return execCommand(args, "qualifier")
end

function p.qualifiers(frame)
	return p._qualifiers(frame.args)
end

function p._qualifiers(args)
	return execCommand(args, "qualifiers")
end

function p.reference(frame)
	return p._reference(frame.args)
end

function p._reference(args)
	return execCommand(args, "reference")
end

function p.references(frame)
	return p._references(frame.args)
end

function p._references(args)
	return execCommand(args, "references")
end

function execCommand(args, funcName)
	_ = Config.new()
	_:processFlagOrCommand(funcName)  -- process first command (== function name)
	
	local parsedFormat, formatParams, claims
	local hooks = {count = 0}
	
	local nextArg = mw.text.trim(args[1] or "")
	local nextIndex = 2
	
	-- process flags and commands
	while _:processFlagOrCommand(nextArg) do
		nextArg = mw.text.trim(args[nextIndex] or "")
		nextIndex = nextIndex + 1
	end
	
	-- check for optional item ID
	if nextArg:sub(1,1):upper() == "Q" then
		_.entity = mw.wikibase.getEntity(nextArg)  -- item ID given
		_.propertyID = mw.text.trim(args[nextIndex] or "")  -- property ID
		nextIndex = nextIndex + 1
	else
		_.entity = mw.wikibase.getEntity()  -- no item ID given, use item connected to current page
		_.propertyID = nextArg  -- property ID
	end
	
	-- check if given property ID is an alias
	if aliasesP[_.propertyID] then
		_.propertyID = aliasesP[_.propertyID]
	end
	
	_.propertyID = _.propertyID:upper()
	
	if _.states[parameters.qualifier] then
		-- do further processing if "qualifier(s)" command was given
		
		nextArg = args[nextIndex]
		nextIndex = nextIndex + 1
		
		_.qualifierID = nextArg
		
		nextArg = mw.text.trim(args[nextIndex] or "")
		nextIndex = nextIndex + 1
		
		if nextArg == "" then
			-- claim ID or literal value has NOT been given
			_.propertyValue = nil
			_.qualifierID = mw.text.trim(_.qualifierID or "")
		else
			-- claim ID or literal value has been given
			_.propertyValue = _.qualifierID  -- cannot be nil when reached
			_.qualifierID = nextArg
		end
		
		-- check if given qualifier ID is an alias
		if aliasesP[_.qualifierID] then
			_.qualifierID = aliasesP[_.qualifierID]
		end
		
		_.qualifierID = _.qualifierID:upper()
	elseif _.states[parameters.reference] then
		-- do further processing if "reference(s)" command was given
		
		nextArg = args[nextIndex]
		nextIndex = nextIndex + 1
		
		_.propertyValue = nextArg  -- claim ID or literal value (possibly nil)
	end
	
	-- check for special property value 'somevalue' or 'novalue'
	if _.propertyValue then
		if _.propertyValue ~= "" and mw.text.trim(_.propertyValue) == "" then
			_.propertyValue = " "  -- single space represents 'somevalue', whereas empty string represents 'novalue'
		else
			_.propertyValue = mw.text.trim(_.propertyValue)
		end
	end
	
	-- parse the desired format, or choose an appropriate format
	if args["format"] then
		parsedFormat, formatParams = parseFormat(mw.text.trim(args["format"]))
	elseif _.states[parameters.qualifier] then
		if _.states[parameters.property] then
			parsedFormat, formatParams = parseFormat(formats.propertyWithQualifier)
		else
			parsedFormat, formatParams = parseFormat(formats.qualifier)
		end
	elseif _.states[parameters.property] then
		parsedFormat, formatParams = parseFormat(formats.property)
	else
		parsedFormat, formatParams = parseFormat(formats.reference)
		
		-- if only "reference(s)" has been given, make the emtpy string the default separator (except when raw)
		if not _.states[parameters.reference].rawValue then
			_.separators["sep"][1] = ""
		end
	end
	
	-- process overridden separator values;
	-- must come AFTER parsing the formats
	for i, v in pairs(_.separators) do
		if args[i] then
			_.separators[i][1] = args[i]
		end
	end
	
	-- make sure that at least one required parameter has been defined
	if not next(parsedFormat.req) then
		return missingRequiredParameterError()
	end
	
	-- make sure that the separator parameter "%s" is not amongst the required parameters
	if parsedFormat.req[parameters.separator] then
		return extraRequiredParameterError(parameters.separator)
	end
	
	-- define the hooks that should be called (getProperty, getQualifiers, getReferences);
	-- only define a hook if both its command ("propert(y|ies)", "qualifier(s)", "reference(s)") and its parameter ("%p", "%q", "%r") have been given
	for i, v in pairs(_.states) do
		if formatParams[i] then
			hooks[i] = hookNames[i][1]
			hooks.count = hooks.count + 1
		end
	end
	
	-- create a state for "properties" if it doesn't exist yet, which will be used as a base configuration for each claim iteration;
	-- must come AFTER defining the hooks
	if not _.states[parameters.property] then
		_.states[parameters.property] = State.new(_)
	end
	
	-- set the parsed format and the separators (and optional punctuation mark)
	_.states[parameters.property].parsedFormat = parsedFormat
	_.states[parameters.property].separator = _.separators["sep"]
	_.states[parameters.property].movSeparator = _.separators["sep"..parameters.separator]
	_.states[parameters.property].puncMark = _.separators["punc"]
	
	if _.entity and _.entity.claims then claims = _.entity.claims[_.propertyID] end
	if claims then
		-- iterate through the claims to collect values
		return _.states[parameters.property]:iterate(claims, hooks, State.claimMatches)  -- pass property State with level 1 hooks and matchHook
	else
		return ""
	end
end

function p.label(frame)
	return p._label(frame.args)
end

function p._label(args, _)
	_ = _ or Config.new()
	_.curState = State.new(_)
	
	local ID
	local label = ""
	local title = nil
	
	local nextArg = mw.text.trim(args[1] or "")
	local nextIndex = 2
	
	while _:processFlag(nextArg) do
		nextArg = mw.text.trim(args[nextIndex] or "")
		nextIndex = nextIndex + 1
	end
	
	ID = nextArg
	
	if ID ~= "" then
		if aliasesP[ID] then
			ID = aliasesP[ID]
		end
		
		ID = ID:upper()
		
		-- check if this is a valid ID, and if the number is not larger than max int (to prevent error)
		if not string.match(ID, '^[QP]%d+$') or tonumber(string.match(ID, '%d+')) > 2147483647 then
			return ""
		end
		
		if _.curState.rawValue then
			if mw.wikibase.getEntity(ID) or mw.wikibase.resolvePropertyId(ID) then
				if _.curState.linked then
					if ID:sub(1,1) == "P" then
						label = "[[d:Property:" .. ID .. "|" .. ID .. "]]"
					else
						label = "[[d:" .. ID .. "|" .. ID .. "]]"
					end
				else
					label = ID
				end
			end
		else
			if ID:sub(1,1) == "P" then
				if not _.pageTitle then
					label = mw.wikibase.label(ID) or ""
					
					if _.curState.linked and label ~= "" then
						label = "[[d:Property:" .. ID .. "|" .. label .. "]]"
					end
				end
			else
				if not _.pageTitle then
					if _.curState.shortName then
						label = getShortName(ID)
					end
					
					-- at this point, 'label' will be a string and not nil
					
					if label == "" then
						label = mw.wikibase.label(ID)
					end
				else
					-- set 'label' to nil so 'title' will always prevail
					label = nil
				end
				
				-- at this point, 'label' will be nil or a non-empty string
				
				if _.curState.linked or label == nil then
					title = mw.wikibase.sitelink(ID)
				end
				
				if _.curState.linked and title then
					label = "[[" .. title .. "|" .. (label or title) .. "]]"
				else
					label = label or title or ""
				end
			end
		end
	else
		if _.curState.rawValue then
			label = mw.wikibase.getEntityIdForCurrentPage() or ""
			
			if _.curState.linked and label ~= "" then
				label = "[[d:" .. label .. "|" .. label .. "]]"
			end
		else
			if not _.pageTitle then
				label = mw.wikibase.label()
			else
				-- set 'label' to nil so 'title' will always prevail
				label = nil
			end
			
			if _.curState.linked or label == nil then
				title = mw.title.getCurrentTitle().prefixedText
			end
			
			if _.curState.linked then
				label = "[[" .. title .. "|" .. (label or title) .. "]]"  -- not much use since it links to the current page, but does add wiki mark-up
			else
				label = label or title
			end
		end
	end
	
	return label
end

function p.title(frame)
	return p._title(frame.args)
end

function p._title(args, _)
	_ = _ or Config.new()
	_.pageTitle = true
	return p._label(args, _)
end

-- main function that may be used by wrapper templates
function p.main(frame)
	local f, args, i, v
	
	frame = frame:getParent() or frame
	f = mw.text.trim(frame.args[1] or "")
	assert(p[f], 'The function "' .. f .. '" does not exist')
	
	args = {}
	
	-- positional parameters;
	-- shift them one index forward
	for i, v in ipairs(frame.args) do
		if i > 1 then
			args[i-1] = v
		end
	end
	
	-- named parameters;
	-- simply copy these
	for i, v in pairs(frame.args) do
		-- pairs() also iterates over the positional parameters,
		-- so ignore those since they have been added by the last loop already
		if not args[i] then
			args[i] = v
		end
	end
	
	-- last loop added the last positional parameter under its previous key again,
	-- so just remove it (it has been copied to #frame.args-1 already)
	args[#frame.args] = nil
	return #frame.args
	--return p["_"..f](args)
end

return p