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/StructuredData/doc erstellt werden

require('strict')

--- @module Entity/StructuredData
--- Stores an Entity page's structured data in the selected backend, from the
--- main namespace only: the Bucket backend splits it into one put per table by
--- Module:Entity/properties.json, the SMW backend (Module:Entity/StructuredData/Smw)
--- flattens the same routed rows to page-level properties. Routing, shaping and
--- diagnostics are shared; only the persistence step differs.
---
--- One Entity page writes at most one row per bucket, from `Module:Entity`,
--- `store`'s only caller, except in the `%rows` buckets, where `storeRows`
--- writes one row per thing the page has several of (a vehicle's cargo grids).
--- A page whose kind never resolved is stored with
--- `kind = nil`: its entity-routable keys are still written (e.g. an item with
--- no uuid), so a query over the whole category still finds it, and the
--- keys that need a kind to route are written nowhere.
---
--- `putBuckets` is the Bucket persistence step used by `store`.
--- `Module:Company` and `Module:WearableSet` build their own rows with `shape`
--- and use `writeRouted` to follow the same namespace-guarded backend dispatch
--- as `store`.

--- Bucket's callable library. Resolved when a query runs, never at module load:
--- requiring `mw.ext.bucket` returns a fresh, non-callable copy of the library on
--- the wiki, and the bare `bucket` global fails the undeclared-global scan.
--- @return table
local function bucketLib()
	return mw.ext.bucket
end

local p = {}

local locationStarmap = require('Module:Entity/Location/Starmap')

local PROPERTIES_PAGE = 'Module:Entity/properties.json'

-- Storage backend: 'bucket' (Extension:Bucket, the upstream English wiki's
-- store) or 'smw' (Semantic MediaWiki, this wiki's store). Only the selected
-- backend's extension is ever reached: the Bucket path never evaluates
-- mw.smw, the SMW path never evaluates mw.ext.bucket, and the SMW module is
-- required inside the branch below, so each wiki loads exactly one writer.
-- A wiki with Bucket selects 'bucket' here, nowhere else.
local backend = 'smw'

function p.backend()
	return backend
end

local manifest = nil

local function getManifest()
	if manifest == nil then
		manifest = mw.loadJsonData(PROPERTIES_PAGE)
	end
	return manifest
end

--- The manifest key for an emitter key: underscores to spaces, first letter
--- upper-cased. properties.json is keyed by these display names, so every
--- lookup goes through here.
--- @param key string
--- @return string
local function autoName(key)
	local spaced = key:gsub('_', ' ')
	return (spaced:gsub('^%l', string.upper))
end

--- The Bucket entry for an emitter key, looked up by its display name. nil when
--- the key is not a Bucket field.
--- @param m table
--- @param key string
--- @return table|nil entry { bucket = string, field, type, repeated }
local function bucketEntry(m, key)
	local entry = m[autoName(key)]
	if type(entry) == 'table' and entry.field then
		return entry
	end
	return nil
end

--- Extracts a bare page title from a `[[Target]]` or `[[Target|Display]]`
--- wikitext link and normalises it the way MediaWiki does ("microTech" ->
--- "MicroTech"), so a PAGE column holds one spelling per page. A `|` outside
--- brackets is plain content, not a link display split, and makes a title
--- MediaWiki rejects; such a value is kept verbatim. A redirect is followed to
--- its target, so a query for the canonical page also matches rows written
--- through one of its redirects - unless `followRedirects` is false, the
--- star-system fields under SMW whose canonicalization must see the original
--- value (which also skips the templatelinks edge reading redirectTarget
--- registers). Reading `redirectTarget` costs no expensive parser call, but
--- it does register the target as a template dependency, one templatelinks
--- edge per PAGE value: editing a manufacturer or a patch page therefore
--- queues a refresh of every page naming it.
--- @param v any
--- @param followRedirects boolean|nil
--- @return any
local function pageTitle(v, followRedirects)
	if type(v) ~= 'string' then
		return v
	end
	local inner = v:match('^%[%[:?(.-)%]%]$')
	if inner then
		v = inner:match('^([^|]*)') or inner
	end
	local t = mw.title.new(v)
	if not t then
		return v
	end
	if followRedirects ~= false then
		local target = t.redirectTarget
		if target then
			t = target
		end
	end
	return t.prefixedText
end

--- Shapes a value for Bucket: repeated fields are arrays of distinct values
--- in first-occurrence order (each element stripped to a bare title when the
--- field is PAGE); non-repeated PAGE fields are bare titles, everything else
--- passes through.
--- @param entry table manifest entry: { type, repeated, ... }
--- @param v any raw emitter value
--- @return any
local function bucketValue(entry, v)
	-- The star-system fields canonicalize at the SMW store seam from the
	-- value as the emitter produced it, so their PAGE shaping must not follow
	-- a redirect first: the canonical records fold only their own spellings,
	-- and a target outside them ("Vega System" redirecting to "Vega Prime")
	-- would store a title no filter literal can derive. Bucket keeps
	-- redirect-following for its verbatim columns.
	local followRedirects = backend ~= 'smw' or not locationStarmap.systemFields[entry.field]
	if entry.repeated then
		local list = (type(v) == 'table') and v or { v }
		local out, seen = {}, {}
		for _, item in ipairs(list) do
			if entry.type == 'PAGE' then
				item = pageTitle(item, followRedirects)
			end
			if item ~= nil and not seen[item] then
				seen[item] = true
				out[#out + 1] = item
			end
		end
		return out
	end
	if type(v) == 'table' then
		v = v[1]
	end
	if entry.type == 'PAGE' then
		v = pageTitle(v, followRedirects)
	end
	return v
end

--- The buckets a manifest meta key (`%kinds` or `%rows`) lists for a kind, as
--- a set, seeded with `seed`.
--- @param m table decoded properties.json
--- @param metaKey string
--- @param kind string|nil
--- @param seed table<string, boolean>
--- @return table<string, boolean>
local function bucketsFor(m, metaKey, kind, seed)
	local allowed = seed
	local lists = m[metaKey]
	if type(lists) == 'table' and kind and type(lists[kind]) == 'table' then
		for _, b in ipairs(lists[kind]) do
			allowed[b] = true
		end
	end
	return allowed
end

--- Splits emitter data into one table per bucket in `allowed`.
--- @param m table decoded properties.json
--- @param data table<string, any>
--- @param allowed table<string, boolean>
--- @return table<string, table> puts bucket -> field -> value
--- @return string[] unregistered keys that reach no allowed bucket
local function routeByBucket(m, data, allowed)
	local puts, unregistered = {}, {}
	local function put(bucket, entry, v)
		puts[bucket] = puts[bucket] or {}
		puts[bucket][entry.field] = bucketValue(entry, v)
	end
	for k, v in pairs(data) do
		local entry = bucketEntry(m, k)
		local bucket = entry and entry.bucket
		-- `migrateTo` names the table a property is moving to: it is written there
		-- as well while readers still read `bucket`, so the new column is full
		-- before the manifest points readers at it.
		local target = entry and entry.migrateTo
		local routed = false
		if v ~= nil and type(bucket) == 'string' and allowed[bucket] then
			put(bucket, entry, v)
			routed = true
		end
		if v ~= nil and type(target) == 'string' and allowed[target] then
			put(target, entry, v)
			routed = true
		end
		if not routed then
			unregistered[#unregistered + 1] = k
		end
	end
	return puts, unregistered
end

--- Splits a page's one-row data into one table per bucket the kind may write:
--- `entity` and the kind's `%kinds` buckets.
--- @param m table decoded properties.json
--- @param data table<string, any>
--- @param kind string|nil kind name; nil allows only the entity bucket
--- @return table<string, table> puts bucket -> field -> value
--- @return string[] unregistered keys that reach no bucket for this kind
local function splitByBucket(m, data, kind)
	return routeByBucket(m, data, bucketsFor(m, '%kinds', kind, { entity = true }))
end

--- Writes one put per bucket, only from the main namespace.
--- @param rows table<string, table<string, any>> bucket -> field -> shaped value
--- @return string|nil error
function p.putBuckets(rows)
	if mw.title.getCurrentTitle().namespace ~= 0 then
		return nil
	end
	local ok, err = pcall(function()
		for bucket, fields in pairs(rows) do
			bucketLib()(bucket).put(fields)
		end
	end)
	if not ok then
		return 'Bucket storage failed: ' .. tostring(err)
	end
	return nil
end

p.shape = bucketValue

--- The bare-title shape `pageTitle` gives a PAGE value with redirects left
--- unfollowed: exactly the pass the SMW writer pipeline runs on a star-system
--- field before the store seam canonicalizes it (bucketValue's system-field
--- branch for the PAGE-typed fields, the store seam itself for the repeated
--- TEXT systems field, which arrives as the emitter wrote it). The SMW filter
--- paths shape their equality literals through this same function first, so
--- an editor's 'Stanton_System' or '[[Stanton|Stanton system]]' derives the
--- very title the writer stored - the canonicalization alone sees none of
--- the title normalization.
--- @param v any
--- @return any
function p.shapedPageTitle(v)
	return pageTitle(v, false)
end

--- Persists the routed rows through the selected backend. An unknown value is
--- a configuration error reported as a storage failure, never a silent fall
--- back to the other store.
--- @param puts table<string, table<string, any>> bucket -> field -> shaped value
--- @param missionApi table|nil|boolean The Mission page's apiData, false when an editorial override
---   replaces the payouts; unused by the other backends
--- @param weaponAlphaDamage boolean|nil True when the routed item_weapon `damage` value, if any, is
---   the weapon chain's per-shot alpha damage rather than the grenade or magazine facets'; the SMW
---   translation then writes Alphaschaden. Bucket ignores it and keeps the union column.
--- @return string|nil error
local function write(puts, missionApi, weaponAlphaDamage)
	if backend == 'bucket' then
		return p.putBuckets(puts)
	end
	if backend == 'smw' then
		return require('Module:Entity/StructuredData/Smw').store(puts, missionApi, weaponAlphaDamage)
	end
	return 'Unknown structured-data backend: ' .. tostring(backend)
end

--- Writes rows a caller built from its own manifest through the selected
--- backend, only from the main namespace: the same dispatch `store` uses
--- after the kind/manifest split, so a domain module follows the wiki's
--- backend selection instead of reaching for a specific writer.
--- @param rows table<string, table<string, any>> bucket -> field -> shaped value
--- @return string|nil error
function p.writeRouted(rows)
	if mw.title.getCurrentTitle().namespace ~= 0 then
		return nil
	end
	return write(rows)
end

--- Stores structured data for the current page. Called only by `Module:Entity`,
--- for the page's own canonical row.
--- @param data table<string, any> Flat snake_case key -> value
--- @param kind string|nil Entity kind name (Vehicle, Item, ...), selects the buckets the page may write.
---   nil when the page's kind never resolved: the entity-routable keys are still written, and the rest
---   are NOT reported as unregistered, since without a kind whether they route is unknowable, not a
---   manifest gap.
--- @return boolean success
--- @return string|nil error
--- @return string[]|nil unregistered Emitter keys absent from properties.json for this kind
function p.store(data, kind, missionApi, weaponAlphaDamage)
	local unregistered = nil
	if mw.title.getCurrentTitle().namespace == 0 then
		local puts, missing = splitByBucket(getManifest(), data, kind)
		if kind ~= nil and #missing > 0 then
			unregistered = missing
		end
		local err = write(puts, missionApi, weaponAlphaDamage)
		if err then
			return false, err, unregistered
		end
	end
	return true, nil, unregistered
end

--- Stores the rows of the tables a kind writes several rows to per page, its
--- `%rows` buckets: one Bucket put per row under `.sub()`, or one named SMW
--- subobject per row on the SMW backend (Module:Entity/StructuredData/Smw
--- storeRow). A key reaches only a `%rows` bucket: a
--- second row in a one-row table would break every reader that takes the
--- page's row to be its only one. Called only by `Module:Entity`.
--- @param rows EntityStructuredRow[]
--- @param kind string|nil nil writes nothing and reports nothing, as `store` does for its by-kind keys
--- @param subjectType string|nil the page's subject_type; the SMW backend copies it into every row
---   (an ask cannot join a page-level property onto subobject rows), the Bucket backend joins instead and ignores it
--- @return boolean success
--- @return string|nil error
--- @return string[]|nil unregistered Row keys that reach no `%rows` bucket of the kind
function p.storeRows(rows, kind, subjectType)
	if mw.title.getCurrentTitle().namespace ~= 0 or kind == nil or type(rows) ~= 'table' then
		return true, nil, nil
	end
	local m = getManifest()
	local allowed = bucketsFor(m, '%rows', kind, {})
	local unregistered, seen = {}, {}
	local ok, err = pcall(function()
		for _, row in ipairs(rows) do
			local puts, missing = routeByBucket(m, type(row.data) == 'table' and row.data or {}, allowed)
			for _, key in ipairs(missing) do
				if not seen[key] then
					seen[key] = true
					unregistered[#unregistered + 1] = key
				end
			end
			if next(puts) == nil then
				-- Bucket names every row through .sub() even when it carries no
				-- field, so the row's id stays reserved; SMW has nothing to name.
			elseif backend == 'smw' then
				local err2 = require('Module:Entity/StructuredData/Smw').storeRow(puts, row.sub, subjectType)
				if err2 then
					error(err2, 0)
				end
			else
				for bucket, fields in pairs(puts) do
					bucketLib()(bucket).sub(tostring(row.sub)).put(fields)
				end
			end
		end
	end)
	local reported = unregistered[1] and unregistered or nil
	if not ok then
		return false, 'Row storage failed: ' .. tostring(err), reported
	end
	return true, nil, reported
end

-- Test-only exports.
p._internal = {
	autoName = autoName,
	splitByBucket = splitByBucket,
	setManifest = function(mf)
		manifest = mf
	end,
	setBackend = function(b)
		backend = b
	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.