Modul:Entity/Store/Smw
Aus Star Citizen Wiki
Weitere Optionen
< Modul:Entity | Store
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