Jump to content
Menü aufrufen
Toggle preferences menu
Persönliches Menü aufrufen
Nicht angemeldet
Ihre IP-Adresse wird öffentlich sichtbar sein, wenn Sie Änderungen vornehmen.

Die Dokumentation für dieses Modul kann unter Modul:Entity/Store/Smw/doc erstellt werden

require('strict')

--- @module Entity/Store/Smw
--- The SMW read backend of Module:Entity/Store: the same lookups the Bucket
--- path runs, answered from SemanticMediaWiki via `mw.smw.getQueryResult`,
--- using Module:Entity/StructuredData/Smw's crosswalk for property names.
---
--- Error contract, mirroring the Bucket half: selfUuid, selfValue,
--- selfValues, pageValue and resolvePages are best-effort - an SMW query-layer
--- failure (getQueryResult raising, or answering an error table) degrades to
--- nil / an empty batch like Bucket's contained reads, never red-erroring a
--- page render. This module's own validation errors (ambiguous subjects,
--- duplicate rows, unsafe data shapes) stay loud everywhere, and query() and
--- resolveUuids() stay loud outright, as on Bucket; count() shares that split,
--- answering nil for a query-layer failure.
---
--- Quantity-typed German properties answer value/unit printout tables
--- (shape pinned by a live cohort probe). Verified read-backs: quantum_speed
--- in m/s and quantum_range in m, divided by the writer's scale factors back to
--- the Bucket scale, plus the identity-scale cohort fields - the m/s speeds
--- (scm/max, boost, missile, muzzle), the °/s rates (agility,
--- flight-controller standard/boost, turret traverse), the m distances
--- (weapon/tool ranges and radii, vehicle dimensions), quantum spool time in
--- s, the SCU sizes (fuel, cargo, ore, maximum container) - where the writer
--- spec, the upstream emitter and the probe all carry the same magnitude and
--- unit - and the µSCU volumes (volume, storage capacity), whose SCU-chain
--- declarations' 1000000 µSCU correspondence stores the µSCU token in SCU,
--- so the reader divides the SCU printout by 0.000001 back to µSCU. The fuel
--- probe is a live sandbox
--- declaration ([[Datentyp::Maß]], [[Entspricht::1 SCU]], [[Einheiten::SCU]]):
--- written `1,2 SCU` / `0,9 SCU` answer numeric {value=1.2,unit='SCU'} / 0.9.
--- Those declarations are local only, not deployed. The observed baseline (revs 88968/88969): production fuel properties declare L/m³, and on the one live page checked (315p) the fuel printouts answer m³ and fail loudly here; a ClassStats cohort batch answering m³ likewise rejects the whole query.
--- Production fuel read-back in SCU is unverified, not a promised outcome: it requires the declarations deployed, every page re-parsed and a live cohort probe confirming the printout shape.
--- Zahl and Text properties are unaffected.
---
--- Boolean-typed properties (manifest BOOLEAN: Available, Base variant,
--- Mineable) normalize on read from SMW's Boolean datatype printouts: 't' is
--- true, 'f' is false, an unset property an empty array (live probe on the
--- existing Abbaubar property, Modul:Sandbox rev 93932; the proposed Verfügbar
--- is undeployed, and the shape belongs to the datatype, not the property).
--- Both strings are truthy in Lua, so a passthrough would answer an
--- unavailable mission as available - real booleans only, and any other
--- printout shape fails loudly. Equality filters take the probe-verified
--- spellings only (see StructuredData/Smw.storedBoolean); anything else
--- fails the build.
---
--- Values the writer translates through a Vocab-marked spec are translated
--- back here, so internal consumers keep English machine tokens: query
--- condition values go English -> German before the [[Property::value]]
--- string is built, and read-back rows German -> English. The lookup keys on
--- the writer spec's vocabulary, never on the field name: the two differ for
--- tier ('rarity') and classification ('body_type'). Vocab passes unmapped
--- values and fields without a vocabulary through, so a nil key needs no
--- special case; property names (already German), Category selectors,
--- numbers and page titles are not value-map scope.

local metadata = require('Module:BucketQuery')
local structuredData = require('Module:Entity/StructuredData')
local crosswalk = require('Module:Entity/StructuredData/Smw')
local propertyName = crosswalk.property
local storedNumber = crosswalk.storedNumber
local storedBoolean = crosswalk.storedBoolean
-- Vocab values translate through the writer spec's key, which for tier and
-- classification differs from the field name; nil (no vocabulary) passes
-- through untouched.
local vocabKey = crosswalk.vocab
local Vocab = require('Module:Entity/Vocab')
local locationStarmap = require('Module:Entity/Location/Starmap')
local p = {}

-- The API has returned 500 rows per request; Scribunto's limit may differ.
p.batchLimit = 500

-- Titles per resolvePages query. The probed #ask ceiling: the wiki's HTTP
-- ask API answers a 16-title subject disjunction and rejects 17, and Bucket's
-- UUID_BATCH 50 fails outright. A live Scribunto probe confirmed
-- getQueryResult answers the 16-title disjunction, and an over-ceiling chunk
-- costs a failed query plus one query per fallback title, so raising this
-- needs a probe first.
local SMW_BATCH = 16

-- Marker distinguishing SMW query-layer failures from this module's own
-- validation errors, so the best-effort readers can contain exactly the former.
local INFRA = {}

--- @param message string
local function infraError(message)
	error({ [INFRA] = true, message = message })
end

local function isInfraError(err)
	return type(err) == 'table' and err[INFRA] == true
end

local function property(name, kind)
	local entry = metadata.resolve(name, kind)
	if not entry then
		error('SMW: unknown property ' .. tostring(name))
	end
	-- An unresolved field's display-name fallback names a property no German
	-- page stores: the query would answer empty and look valid.
	local reason = crosswalk.unresolved(entry.field)
	if reason then
		error("SMW: '" .. tostring(name) .. "' has no German property yet (" .. reason .. ')')
	end
	-- The image field reads the PageImages-maintained Seitenbild instead of the
	-- writer's Kopfbild: the extension recomputes it on every parse, so it serves
	-- every page with a lead image and cannot drift the way the stored copy can
	-- (double-Datei: rows exist). The writer keeps writing Kopfbild; PageImages
	-- owns Seitenbild.
	if entry.field == 'image' then
		return 'Seitenbild', entry
	end
	-- The bucket decides the spec for a field name two routing buckets share
	-- (type: mission vs wearable_set), so the resolved entry's own bucket is
	-- the one correct scope.
	return propertyName(entry.field, entry.bucket), entry
end

local function readable(entry)
	if entry.bucket == 'mission' and (entry.field == 'orders' or entry.field == 'rewards') then
		error('SMW: display-only field cannot be read: ' .. entry.field)
	end
end

local function filterValue(entry, value)
	if entry.bucket == 'mission' and entry.field == 'type' then
		return Vocab.missionTypeToGerman(value)
	end
	-- The star-system fields store canonical page titles (Starmap.systemPageTitle,
	-- applied at the SMW store seam), so an equality filter derives its literal
	-- through the same accessor the writer used: a short name, an alias and any
	-- page spelling query the one stored title, on the shared Sternensystem
	-- property for Mission, Commodity and Location rows alike. destination_system
	-- (Sprungpunkt Ziel) writes through the same accessor as system and systems.
	-- The literal takes the same non-redirect PAGE shaping first
	-- (structuredData.shapedPageTitle) that the writer's value took before the
	-- seam canonicalized it, so an underscored or linked literal reaches the
	-- stored title too.
	if type(value) == 'string' and locationStarmap.systemFields[entry.field] then
		local page = locationStarmap.systemPageTitle(structuredData.shapedPageTitle(value))
		if page then
			return page
		end
	end
	return Vocab.toGerman(vocabKey(entry.field, entry.bucket), value)
end

local function literal(value)
	local s = tostring(value)
	if s:find('[%[%]|{}<>]') or s:find('\0', 1, true) then
		error('SMW: unsafe query value')
	end
	return s
end

-- A '::' in a page subject would parse it as a property condition, querying
-- the wrong thing while the answer looks valid.
local function subjectLiteral(text)
	if text:find('::', 1, true) then
		error('SMW: unsafe query value')
	end
	return literal(text)
end

-- SMW's comparator spellings for the relational operators BucketQuery supports.
-- SMW's single < and > are the non-strict comparators, so strict comparisons double up.
-- <= and >= map to the ASCII singles; SMW also accepts U+2264/U+2265 but the
-- ASCII spellings avoid any dependence on comparator Unicode parsing.
local COMPARATORS = { ['<'] = '<<', ['<='] = '<', ['>'] = '>>', ['>='] = '>' }

-- A numeric filter value serializes exactly as the writer stores it (spec
-- factor, comma decimal, unit token), so the condition compares in the
-- stored scale, not the Bucket scale callers speak; NaN and infinities have
-- no stored serialization and fail loudly. The resolved entry's bucket
-- scopes a field name two routing buckets share.
local function numberLiteral(entry, v)
	if v ~= v or math.abs(v) == math.huge then
		error('SMW: invalid numeric value')
	end
	return literal(storedNumber(entry.field, v, entry.bucket))
end

-- These TEXT fields map to numeric flight-controller properties in SMW, not seat ranges.
local function numericEqualityField(entry)
	return entry.bucket == 'item_component' and (entry.field == 'pitch' or entry.field == 'yaw')
end

-- A numeric field's filter value in Bucket scale: a Lua number, or a plain
-- dot-decimal string, which BucketQuery hands to Bucket's SQL layer where the
-- numeric column coerces it. Comma decimals, units, exponents and any other
-- text have no Bucket-scale meaning (a dot decimal is the de parser's
-- thousands separator), so they answer nil and the caller rejects them
-- loudly rather than comparing the wrong magnitude.
local function numericValue(v)
	if type(v) == 'number' then
		return v
	end
	if type(v) == 'string' and v:match('^%-?%d*%.?%d+$') then
		return tonumber(v)
	end
	return nil
end

-- One alternative of a property OR list: { name, value } or { name, '=', value }.
-- Values SMW would parse as a comparator or presence condition (+, !, ~, =, <=,
-- >=) are rejected rather than reinterpreted as another query; literal()
-- covers the structural delimiters. Returns the resolved German property,
-- the translated safe value and the manifest entry; the caller enforces one
-- resolved field across the list.
local function equalityAlternative(item, kind)
	if type(item) ~= 'table' or item.any ~= nil then
		error('SMW: unsupported OR filter')
	end
	local name, op, v = item[1], item[2], item[3]
	if v == nil and op ~= '+' then
		v, op = op, '='
	end
	if op ~= '=' or v == nil then
		error('SMW: unsupported OR filter')
	end
	local prop, entry = property(name, kind)
	if entry.field == 'orders' or entry.field == 'rewards' then
		error('SMW: display-only field cannot be filtered')
	end
	if entry.type == 'BOOLEAN' then
		return prop, storedBoolean(v), entry
	end
	if type(v) == 'number' then
		return prop, numberLiteral(entry, v), entry
	end
	if entry.type == 'INTEGER' or entry.type == 'DOUBLE' or numericEqualityField(entry) then
		local n = numericValue(v)
		if n == nil then
			error('SMW: invalid numeric value')
		end
		return prop, numberLiteral(entry, n), entry
	end
	v = filterValue(entry, v)
	if crosswalk.comparatorShaped(v) then
		error('SMW: unsafe OR value')
	end
	return prop, literal(v), entry
end

local function pageSubject(row)
	if type(row) ~= 'table' or type(row.fulltext) ~= 'string' or type(row.namespace) ~= 'number' then
		error('SMW: missing subject identity')
	end
	if row.namespace ~= 0 or row.fulltext:find('#', 1, true) then
		return nil
	end
	local title = mw.title.new(row.fulltext)
	if not title or title.namespace ~= 0 or title.prefixedText ~= row.fulltext then
		error('SMW: invalid subject identity: ' .. row.fulltext)
	end
	return row.fulltext
end

-- Verified quantity read-backs, keyed by resolved field identity
-- (bucket.field, the identity the OR check also uses). The writer emits
-- quantum_speed x1000000 in m/s (Bucket holds Mm/s) and quantum_range
-- x1000000000 in m (Bucket holds Gm), so the reader divides back. The other
-- entries are identity scale: writer spec, upstream emitter and live probe
-- carry the same magnitude and unit (scm/max speed m/s, agility rates °/s,
-- spool time s; the Item cohort: boost/missile/muzzle speeds m/s, and the
-- standard/boost flight-controller rates plus turret traverse °/s; the m
-- range/radius cohort), so
-- nothing divides. The °/s declarations register exactly the factor-1 unit
-- 1 °/s and the m/s declarations the 1 m/s + 3,6 km/h comma chain, so the
-- canonical printout unit is °/s or m/s and any other unit (°, km/h) fails
-- loudly. The m range/radius cohort is identity too: every declaration
-- registers the factor-1 primary 1 m (EMP Radius alone, the rest beside a
-- 0,001 km comma factor) and the same-chain live rows answer {value, m}.
-- The vehicle dimensions (height/length/width, retracted) join that chain:
-- same declaration form (revs 89461-89465, 89469, 89472) and live rows
-- answer {value, m} across every stored page. km stays rejected with no
-- entry: the unreparsed legacy rows of the
-- point-factor-fixed properties (Maximaler Explosionsradius, Stör-/
-- Abriegelungsreichweite) still answer km, and a km divisor would launder
-- those wrong magnitudes instead of surfacing them. The fuel capacities
-- take SCU only,
-- verified against a live sandbox declaration; the declarations are not
-- deployed, so the production printouts' m³/L answers stay rejected. The SCU
-- size cohort: all five declarations (Volumen 71927, Inventar 72656,
-- Frachtkapazität 65513, Maximale Frachtcontainergröße 88818, Erzkapazität
-- 88819) register the identical chain 1 SCU + 1000 KµSCU, cSCU + 1000000
-- µSCU, and live rows on every property answer {value, SCU} (315p
-- Frachtkapazität 12, Prospector Erzkapazität 32, ROC 1,2, 'Arrow' I Missile
-- Volumen 0.015625), so SCU is the canonical printout and the registered
-- µSCU/KµSCU/cSCU labels reject like km on the m chains. cargo/ore/container
-- write the SCU token itself: identity. volume/storage_capacity write the
-- µSCU token and the declared factor converts (probed exact: 4600 µSCU
-- answers 0,0046 SCU), so the reader divides by 0.000001 - the printout is
-- already SCU, and a 1000000 divisor would shrink it another millionfold.
-- Every other field or unit stays unverified and fails loudly.
local QUANTITY_DIVISORS = {
	['entity.quantum_speed'] = { ['m/s'] = 1000000 },
	['entity.scm_speed'] = { ['m/s'] = 1 },
	['entity.max_speed'] = { ['m/s'] = 1 },
	['entity.quantum_spool_time'] = { ['s'] = 1 },
	['entity.storage_capacity'] = { ['SCU'] = 0.000001 },
	['entity.volume'] = { ['SCU'] = 0.000001 },
	['vehicle.entity_height'] = { ['m'] = 1 },
	['vehicle.entity_length'] = { ['m'] = 1 },
	['vehicle.entity_width'] = { ['m'] = 1 },
	['vehicle.retracted_height'] = { ['m'] = 1 },
	['vehicle.retracted_length'] = { ['m'] = 1 },
	['vehicle.retracted_width'] = { ['m'] = 1 },
	['vehicle.mass'] = { ['kg'] = 1 },
	['vehicle.cargo_capacity'] = { ['SCU'] = 1 },
	['vehicle.maximum_cargo_container_size'] = { ['SCU'] = 1 },
	['vehicle.ore_capacity'] = { ['SCU'] = 1 },
	['vehicle.average_purchase_price'] = { ['aUEC'] = 1 },
	['vehicle.average_rental_price'] = { ['aUEC'] = 1 },
	['vehicle.insurance_claim_time'] = { ['Minute'] = 1 },
	['vehicle.insurance_expedite_cost'] = { ['aUEC'] = 1 },
	['vehicle.insurance_expedite_time'] = { ['Minute'] = 1 },
	['vehicle.original_warbond_pledge_price'] = { ['USD'] = 1 },
	['vehicle.pledge_price'] = { ['USD'] = 1 },
	['vehicle.warbond_pledge_price'] = { ['USD'] = 1 },
	['vehicle_stats.quantum_range'] = { ['m'] = 1000000000 },
	['vehicle_stats.pitch_rate'] = { ['°/s'] = 1 },
	['vehicle_stats.yaw_rate'] = { ['°/s'] = 1 },
	['vehicle_stats.roll_rate'] = { ['°/s'] = 1 },
	['vehicle_stats.hydrogen_fuel_capacity'] = { ['SCU'] = 1 },
	['vehicle_stats.quantum_fuel_capacity'] = { ['SCU'] = 1 },
	['vehicle_stats.zero_to_maximum_speed_time'] = { ['Sekunde'] = 1 },
	['item_component.boost_speed'] = { ['m/s'] = 1 },
	['item_component.emp_charge_time'] = { ['s'] = 1 },
	['item_component.emp_cooldown'] = { ['s'] = 1 },
	['item_component.emp_duration'] = { ['s'] = 1 },
	['item_component.emp_radius'] = { ['m'] = 1 },
	['item_component.maximum_temperature'] = { ['°C'] = 1 },
	['item_component.minimum_temperature'] = { ['°C'] = 1 },
	['item_component.pitch'] = { ['°/s'] = 1 },
	['item_component.pitch_boosted'] = { ['°/s'] = 1 },
	['item_component.pitch_max'] = { ['°'] = 1 },
	['item_component.pitch_min'] = { ['°'] = 1 },
	['item_component.qig_charge_time'] = { ['s'] = 1 },
	['item_component.qig_cooldown'] = { ['s'] = 1 },
	['item_component.qig_dampener_range'] = { ['m'] = 1 },
	['item_component.qig_duration'] = { ['s'] = 1 },
	['item_component.qig_snare_range'] = { ['m'] = 1 },
	['item_component.quantum_cooldown'] = { ['s'] = 1 },
	['item_component.radar_aim_assist_range'] = { ['m'] = 1 },
	['item_component.radar_cooldown'] = { ['s'] = 1 },
	['item_component.roll'] = { ['°/s'] = 1 },
	['item_component.roll_boosted'] = { ['°/s'] = 1 },
	['item_component.shield_regen_delay'] = { ['s'] = 1 },
	['item_component.yaw'] = { ['°/s'] = 1 },
	['item_component.yaw_boosted'] = { ['°/s'] = 1 },
	['item_component.yaw_max'] = { ['°'] = 1 },
	['item_component.yaw_min'] = { ['°'] = 1 },
	['item_weapon.arm_time'] = { ['s'] = 1 },
	['item_weapon.blast_radius'] = { ['m'] = 1 },
	['item_weapon.drop_angle'] = { ['°'] = 1 },
	['item_weapon.explosion_radius'] = { ['m'] = 1 },
	['item_weapon.fire_rate'] = { ['rpm'] = 1 },
	['item_weapon.full_damage_range'] = { ['m'] = 1 },
	['item_weapon.laser_range'] = { ['m'] = 1 },
	['item_weapon.lock_angle'] = { ['°'] = 1 },
	['item_weapon.lock_range'] = { ['m'] = 1 },
	['item_weapon.lock_time'] = { ['s'] = 1 },
	['item_weapon.magnification'] = { ['x'] = 1 },
	['item_weapon.max_range'] = { ['m'] = 1 },
	['item_weapon.missile_range'] = { ['m'] = 1 },
	['item_weapon.missile_speed'] = { ['m/s'] = 1 },
	['item_weapon.muzzle_velocity'] = { ['m/s'] = 1 },
	['item_weapon.pitch_speed'] = { ['°/s'] = 1 },
	['item_weapon.range_increment'] = { ['m'] = 1 },
	['item_weapon.yaw_speed'] = { ['°/s'] = 1 },
	['item_tool.beam_force'] = { ['N'] = 1 },
	['item_tool.beam_max_angle'] = { ['°'] = 1 },
	['item_tool.beam_mode_force'] = { ['N'] = 1 },
	['item_tool.beam_range'] = { ['m'] = 1 },
	['item_tool.beam_tether_break'] = { ['s'] = 1 },
	['item_tool.duration'] = { ['s'] = 1 },
	['item_tool.maximum_range'] = { ['m'] = 1 },
	['item_tool.optimal_range'] = { ['m'] = 1 },
	['item_tool.ramp_down_time'] = { ['s'] = 1 },
	['item_tool.ramp_up_time'] = { ['s'] = 1 },
	['wearable_set.min_temperature'] = { ['°C'] = 1 },
	['wearable_set.max_temperature'] = { ['°C'] = 1 },
	['location.radius'] = { ['km'] = 1 },
	['location.system_size'] = { ['AE'] = 1 },
}

--- One value/unit printout at Bucket scale for a verified field/unit pair;
--- nil for anything else (unverified field, foreign unit, malformed shape).
--- @param v table
--- @param entry table
--- @return number|nil
local function quantity(v, entry)
	local units = QUANTITY_DIVISORS[entry.bucket .. '.' .. entry.field]
	if type(units) ~= 'table' or type(v.value) ~= 'number' then
		return nil
	end
	local divisor = units[v.unit]
	if divisor == nil then
		return nil
	end
	return v.value / divisor
end

local function value(raw, entry)
	if type(raw) ~= 'table' then
		error('SMW: invalid printout')
	end
	local values = {}
	for _, v in ipairs(raw) do
		if entry.type == 'BOOLEAN' then
			-- SMW's Boolean datatype printouts answer 't'/'f' (probe: Abbaubar,
			-- Modul:Sandbox rev 93932). Explicit branches, no and/or shortcut:
			-- both strings are truthy in Lua, so a shortcut is where a false
			-- slips through as available.
			if v == 't' then
				v = true
			elseif v == 'f' then
				v = false
			else
				error('SMW: unexpected Boolean printout ' .. tostring(v) .. ' for ' .. tostring(entry.field))
			end
		end
		if type(v) == 'table' then
			-- A table printout is a page object (fulltext) or a quantity
			-- (value/unit); an unverifiable quantity fails loudly rather than
			-- guessing an adapter.
			if type(v.fulltext) == 'string' then
				v = v.fulltext
			else
				v = quantity(v, entry)
				if v == nil then
					error(
						'SMW: unsupported printout shape for ' .. tostring(entry.field) .. ' (quantity read unverified)'
					)
				end
			end
		end
		-- The SMW writer stores image as a 'Datei:' page (Kopfbild is a Seite
		-- property); Bucket and its readers hold the bare filename, so strip the
		-- file-namespace prefix the writer added.
		if entry.field == 'image' and type(v) == 'string' then
			v = v:gsub('^Datei:', ''):gsub('^File:', '')
		end
		-- Vocab fields come back as their German stored value; internal
		-- consumers (cohort filters, Navplates) speak English machine tokens.
		-- vocabKey scopes the field name through the entry's bucket: type and
		-- classification translate through different vocabularies per bucket.
		if type(v) == 'string' then
			v = Vocab.toEnglish(vocabKey(entry.field, entry.bucket), v)
		end
		values[#values + 1] = v
	end
	if entry.repeated then
		return values[1] and values or nil
	end
	if #values > 1 then
		error('SMW: multiple values for scalar property')
	end
	return values[1]
end

local function run(conditions, columns, limit)
	if type(limit) ~= 'number' or limit < 1 or limit ~= math.floor(limit) then
		error('SMW: invalid query limit')
	end
	if type(p.batchLimit) ~= 'number' or p.batchLimit < 1 or p.batchLimit ~= math.floor(p.batchLimit) then
		error('SMW: invalid batch limit')
	end
	local args = { table.concat(conditions) }
	local requests = {}
	for _, col in ipairs(columns) do
		if col.entry then
			if not requests[col.property] then
				args[#args + 1] = '?' .. col.property
				requests[col.property] = true
			end
		end
	end
	local rows, seen, count, offset = {}, {}, 0, 0
	while true do
		local size = math.min(p.batchLimit, limit - count + 1)
		args[#args + 1] = 'limit=' .. size
		args[#args + 1] = 'offset=' .. offset
		-- The pcall + tag split matters: a raising or error-tabling getQueryResult
		-- is an SMW query-layer failure the best-effort readers must contain,
		-- while every other error run() raises is this module's own validation.
		local ok, result = pcall(mw.smw.getQueryResult, args)
		if not ok then
			infraError(tostring(result))
		end
		if type(result) ~= 'table' or result.errors or type(result.results) ~= 'table' then
			infraError('SMW: query failed or returned invalid results')
		end
		args[#args], args[#args - 1] = nil, nil
		local n = 0
		for _, raw in pairs(result.results) do
			n = n + 1
			count = count + 1
			if n > size or count > limit then
				error('SMW: query limit exceeded')
			end
			local page = pageSubject(raw)
			if page then
				if seen[page] then
					error('SMW: duplicate subject across results')
				end
				seen[page] = true
				if type(raw.printouts) ~= 'table' then
					error('SMW: missing printouts')
				end
				local row = {}
				for _, col in ipairs(columns) do
					if col.entry then
						row[col.key] = value(raw.printouts[col.property] or {}, col.entry)
					else
						row[col.key] = page
					end
				end
				rows[#rows + 1] = row
			end
		end
		local continuation = result['query-continue-offset']
		if continuation ~= nil then
			continuation = tonumber(continuation)
			if not continuation or n == 0 or continuation ~= offset + n then
				error('SMW: invalid continuation offset')
			end
		elseif n < size then
			break
		end
		offset = offset + n
	end
	return rows
end

-- One Module:BucketQuery filter as its SMW query condition, shared by query()
-- and count(). `kind` scopes a property name two routing buckets share.
--- @param filter string|table
--- @param kind string|nil
--- @return string
local function condition(filter, kind)
	if type(filter) == 'string' then
		if not filter:match('^Category:.+') then
			error('SMW: unsupported selector')
		end
		-- [[:+]] keeps the condition main-namespace while still traversing
		-- subcategories: hub categories hold their pages in subcats, while a
		-- category's own subcats commonly contain only File: pages. +depth=0
		-- (direct members only) returns zero rows on subcat-only categories.
		return '[[' .. literal(filter) .. ']][[:+]]'
	end
	if type(filter) ~= 'table' then
		error('SMW: unsupported filter')
	end
	if filter.any then
		-- A table-first list is a property OR; anything else (string-first,
		-- empty) stays on the category path, which rejects non-category
		-- strings and mixed lists itself.
		if type(filter.any[1]) == 'table' then
			local parts, prop, field = {}
			for _, item in ipairs(filter.any) do
				local itemProp, text, entry = equalityAlternative(item, kind)
				-- The German label alone is not identity: distinct fields share
				-- targets (health and health_point both write Schadenspunkte),
				-- and their Bucket rows differ, so the resolved field decides.
				local itemField = entry.bucket .. '.' .. entry.field
				if prop == nil then
					prop, field = itemProp, itemField
				elseif itemProp ~= prop or itemField ~= field then
					error('SMW: unsupported OR filter')
				end
				parts[#parts + 1] = '[[' .. prop .. '::' .. text .. ']]'
			end
			return '<q>' .. table.concat(parts, ' OR ') .. '</q>'
		end
		local categories = {}
		for _, item in ipairs(filter.any) do
			if type(item) ~= 'string' or not item:match('^Category:.+') then
				error('SMW: unsupported OR filter')
			end
			categories[#categories + 1] = literal(item:sub(10))
		end
		if #categories == 0 then
			error('SMW: empty OR filter')
		end
		return '[[Category:' .. table.concat(categories, '||') .. ']][[:+]]'
	end
	local name, op, v = filter[1], filter[2], filter[3]
	if v == nil and op ~= '+' then
		v, op = op, '='
	end
	local comparator = COMPARATORS[op]
	if op ~= '=' and op ~= '+' and op ~= '!=' and not comparator then
		error('SMW: unsupported operator')
	end
	local prop, entry = property(name, kind)
	if entry.field == 'orders' or entry.field == 'rewards' then
		error('SMW: display-only field cannot be filtered')
	end
	if entry.repeated and op == '!=' then
		error('SMW: inequality on a list')
	end
	-- SMW negation ([[prop::!value]]) reuses the equality serialization below.
	local negation = op == '!=' and '!' or ''
	if comparator then
		-- Bucket parity (BucketQuery): a relational comparison runs on
		-- numeric fields only, its value a number or a canonical numeric
		-- string (numericValue).
		if entry.type ~= 'INTEGER' and entry.type ~= 'DOUBLE' then
			error("SMW: '" .. tostring(name) .. "' is not numeric")
		end
		local n = numericValue(v)
		if n == nil then
			error('SMW: invalid numeric comparison')
		end
		return '[[' .. prop .. '::' .. comparator .. numberLiteral(entry, n) .. ']]'
	end
	if op == '+' then
		return '[[' .. prop .. '::+]]'
	end
	if entry.type == 'BOOLEAN' then
		return '[[' .. prop .. '::' .. negation .. storedBoolean(v) .. ']]'
	end
	if type(v) == 'number' then
		return '[[' .. prop .. '::' .. negation .. numberLiteral(entry, v) .. ']]'
	end
	if entry.type == 'INTEGER' or entry.type == 'DOUBLE' or numericEqualityField(entry) then
		local n = numericValue(v)
		if n == nil then
			error('SMW: invalid numeric value')
		end
		return '[[' .. prop .. '::' .. negation .. numberLiteral(entry, n) .. ']]'
	end
	-- The writer stores Vocab values in German, so an English filter value
	-- must query for its German stored value or match nothing.
	v = filterValue(entry, v)
	if crosswalk.comparatorShaped(v) then
		error('SMW: unsafe query value')
	end
	return '[[' .. prop .. '::' .. negation .. literal(v) .. ']]'
end

function p.query(spec)
	if spec.primary and spec.primary ~= 'entity' then
		error('SMW: unsupported primary')
	end
	local conditions, columns = {}, {}
	for _, filter in ipairs(spec.filters or {}) do
		conditions[#conditions + 1] = condition(filter, spec.kind)
	end
	if #conditions == 0 then
		error('SMW: unbounded query')
	end
	for _, col in ipairs(spec.columns or {}) do
		if type(col) == 'string' then
			col = { property = col }
		end
		if col.builtin then
			if col.builtin ~= 'page_name' then
				error('SMW: unsupported builtin')
			end
			columns[#columns + 1] = { key = col.as or col.builtin }
		else
			local prop, entry = property(col.property, spec.kind)
			readable(entry)
			columns[#columns + 1] = { property = prop, entry = entry, key = col.as or col.property }
		end
	end
	return run(conditions, columns, spec.limit or 1000)
end

--- The number of rows the filters match, or nil when SMW did not answer a
--- count. `mw.smw.ask` with format=count answers the server-side COUNT as a
--- plain number (SemanticScribunto 3.0.0 returns getCountValue() for a
--- MODE_COUNT query, while getQueryResult would serialize count mode's empty
--- result set), so no row is transferred and no limit truncates the answer.
--- A failed query answers nil there, never 0; validation errors stay loud.
--- @param spec { filters: (string|table)[], kind: string|nil }
--- @return number|nil
function p.count(spec)
	local conditions = {}
	for _, filter in ipairs(spec.filters or {}) do
		conditions[#conditions + 1] = condition(filter, spec.kind)
	end
	if #conditions == 0 then
		error('SMW: unbounded query')
	end
	local ok, res = pcall(mw.smw.ask, { table.concat(conditions), 'format=count' })
	if not ok or type(res) ~= 'number' then
		return nil
	end
	return res
end

local function pageRead(title, name, kind)
	if not title or title.namespace ~= 0 then
		return nil
	end
	local prop, entry = property(name, kind)
	readable(entry)
	local rows = run({ '[[' .. subjectLiteral(title.prefixedText) .. ']]' }, {
		{ key = 'page' },
		{ property = prop, entry = entry, key = 'value' },
	}, 50)
	local found
	for _, row in ipairs(rows) do
		if row.page == title.prefixedText then
			if found then
				error('SMW: ambiguous page')
			end
			found = row
		end
	end
	return found and found.value
end

-- Best-effort wrapper for the page-scoped reads: an SMW query-layer failure
-- degrades to nil (Bucket's contained rowFor answers nil for the same cases);
-- this module's validation errors still raise.
--- @param fn fun(): any
--- @return any
local function soft(fn)
	local ok, res = pcall(fn)
	if ok then
		return res
	end
	if isInfraError(res) then
		return nil
	end
	error(res, 0)
end

function p.selfUuid()
	return soft(function()
		local v = pageRead(mw.title.getCurrentTitle(), 'Uuid')
		if type(v) == 'string' and v ~= '' then
			return v
		end
	end)
end
function p.selfValue(name, kind)
	return soft(function()
		local v = pageRead(mw.title.getCurrentTitle(), name, kind)
		if type(v) == 'boolean' or type(v) == 'number' or (type(v) == 'string' and v ~= '') then
			return v
		end
	end)
end
function p.selfValues(name, kind)
	return soft(function()
		local v = pageRead(mw.title.getCurrentTitle(), name, kind)
		if type(v) ~= 'table' then
			return nil
		end
		local out = {}
		for _, item in ipairs(v) do
			if type(item) == 'string' and item ~= '' then
				out[#out + 1] = item
			end
		end
		return out[1] and out or nil
	end)
end
function p.pageValue(page, name, kind)
	if type(page) ~= 'string' or page == '' then
		return nil
	end
	return soft(function()
		local title = mw.title.new(page)
		if title and title.redirectTarget then
			title = title.redirectTarget
		end
		local v = pageRead(title, name, kind)
		if type(v) == 'boolean' or type(v) == 'number' or (type(v) == 'string' and v ~= '') then
			return v
		end
	end)
end
function p.resolveUuids(uuids)
	local map = {}
	for _, uuid in ipairs(uuids) do
		local rows = p.query({
			filters = { { 'Uuid', uuid } },
			columns = {
				{ builtin = 'page_name', as = 'page' },
				{ property = 'Uuid', as = 'uuid' },
				{ property = 'Image', as = 'image' },
			},
			limit = 50,
		})
		for _, row in ipairs(rows) do
			if row.uuid == uuid then
				if map[uuid] then
					error('SMW: ambiguous UUID ' .. uuid)
				end
				-- Raw property read, so the image carries the 'Datei:' prefix
				-- (Seitenbild answers file pages); strip it for the bare filename
				-- Tiles expects.
				if type(row.image) == 'string' then
					row.image = row.image:gsub('^Datei:', ''):gsub('^File:', '')
				end
				map[uuid] = { page = row.page, image = row.image }
			end
		end
	end
	return map
end
function p.resolvePages(names)
	-- Titles must be canonical: Bucket matches page_name exactly, and the one
	-- caller resolves redirects before asking. Following them here would cost
	-- the per-title page-table loads the batching exists to remove.
	local cols = { { key = 'page' } }
	for _, pair in ipairs({
		{ 'Name', 'name' },
		{ 'Manufacturer', 'manufacturer' },
		{ 'Role', 'role' },
		{ 'Image', 'image' },
	}) do
		local prop, entry = property(pair[1], 'Vehicle')
		cols[#cols + 1] = { property = prop, entry = entry, key = pair[2] }
	end
	local wanted, seen = {}, {}
	for _, name in ipairs(names) do
		local title = mw.title.new(name)
		if title and title.namespace == 0 then
			local text = title.prefixedText
			-- Duplicate names fold to one disjunct: Bucket's map write
			-- overwrites silently, so raising here would be stricter than the
			-- shared contract.
			if not seen[text] then
				seen[text] = true
				-- Validated here, ahead of the chunk loop, so an invalid subject
				-- in a later chunk fails before the first query runs at all.
				subjectLiteral(text)
				wanted[#wanted + 1] = text
			end
		end
	end
	local map = {}
	local function absorb(rows, requested)
		for _, row in ipairs(rows) do
			local page = row.page
			if requested[page] then
				-- Dedupe keeps a title inside one chunk, and run() errors on a
				-- repeated subject, so this guard only pins that invariant.
				if map[page] then
					error('SMW: ambiguous page')
				end
				row.page = nil
				map[page] = row
			end
		end
	end
	for start = 1, #wanted, SMW_BATCH do
		local last = math.min(start + SMW_BATCH - 1, #wanted)
		local texts, parts = {}, {}
		for i = start, last do
			local text = wanted[i]
			texts[#texts + 1] = text
			parts[#parts + 1] = '[[' .. subjectLiteral(text) .. ']]'
		end
		local requested = {}
		for _, text in ipairs(texts) do
			requested[text] = true
		end
		-- limit #chunk (run() adds one) lets run() reject an over-answering
		-- disjunction loudly. A query-layer failure falls back to one query per
		-- chunk title, so one failed disjunction drops only the titles whose own
		-- query fails too; validation errors raise with no fallback, since a
		-- validation error is this module's own defect, not a transient one.
		local ok, rows = pcall(run, { '<q>' .. table.concat(parts, ' OR ') .. '</q>' }, cols, #parts)
		if not ok and isInfraError(rows) then
			for i, text in ipairs(texts) do
				-- parts[i] and the flat 50 limit are the pre-batching per-title
				-- query verbatim: reusing the already-validated condition keeps
				-- the fallback from failing validation on its own input.
				local okSingle, single = pcall(run, { parts[i] }, cols, 50)
				if not okSingle then
					if isInfraError(single) then
						single = {}
					else
						error(single, 0)
					end
				end
				absorb(single, { [text] = true })
			end
		elseif not ok then
			error(rows, 0)
		else
			absorb(rows, requested)
		end
	end
	return map
end

-- query and resolveUuids stay loud outright (the Bucket contract), but re-raise
-- the tagged query-layer failures as plain string errors so callers matching
-- error messages see the same shape as before.
for _, name in ipairs({ 'query', 'resolveUuids' }) do
	local impl = p[name]
	p[name] = function(...)
		local ok, res = pcall(impl, ...)
		if ok then
			return res
		end
		if isInfraError(res) then
			error(res.message, 0)
		end
		error(res, 0)
	end
end

return p
Zuletzt geändert
Urheberrecht
Cookies helfen uns bei der Bereitstellung dieses Wikis. Durch die Nutzung des Star Citizen Wiki erklärst du dich damit einverstanden, dass wir Cookies speichern.