模块:GameText/loaddata

文档 以下文档来自 模块:GameText/loaddata/doc. (编辑 | 历史)

[刷新缓存]
[↓ 跳转至模块代码 ↓]

This module is used by Module:GameText to fetch the game text database for a language. To improve performance, the game text databases are not fetched every time Module:GameText is invoked, but are cached instead. This module returns that cache. It is called from the language-specific loaders (模块:GameText/loaddata-de, 模块:GameText/loaddata-en, etc., which in turn are called directly by Module:GameText) with the load function.

Caching the game text databases means that changes to them are not immediately reflected. The cache must be cleared ("purged") in order for the changes to take effect. When the cache is purged, this module will recreate it. The cache can be purged from another module with the purge function.

Usage

Other modules

The module can be called from another module with the functions listed below.

load

require('Module:GameText/loaddata').load('<language>')

Returns the cache of the game text database for the given language (模块:GameText/db-de, 模块:GameText/db-en, etc.).

purge

require('Module:GameText/loaddata').purge('<language>')

Purges the cache of the game text database for the given language. The cache will be recreated with the most recent version of the game text database the next time the load function is called. This function is only intended to be called by Module:GameText – to purge it manually, invoke that module.

---

--------------------------------------------------------------------------------
--
-- =============================================================================
--
-- Module:GameText/loaddata
--
-- Cache management of the game text databases for Module:GameText
--
-- =============================================================================
--
-- Code annotations:
-- This module is documented according to LuaCATS (Lua Comment and Type System).
-- LuaCATS comments are prefixed with three dashes (---) and use Markdown syntax.
-- For a full list of annotations, see the following link:
-- https://luals.github.io/wiki/annotations/
--
--------------------------------------------------------------------------------


local cache = mw.ext.LuaCache

-- Note:
-- It seems that objects/lists stored via LuaCache have a limit on the number of
-- entities, which is about 8000. Any object/list with more than 8000 entities or
-- with such a large sub-object/sub-list will be truncated. Therefore, the data
-- must be encoded as a JSON string to get around this problem.
-- Additionally, storing a JSON string to the cache and decoding it after
-- retrieval is at least two times faster than storing Lua tables directly, for
-- whatever reason.

--------------------------------------------------------------------------------
---Main return object
local p = {}

---Get the cached game text database for the specified language `lang`. Recreate
---the cache if necessary.
---This function should only be called from the `Module:GameText/loaddata-<lang>`
---modules (e.g. `Module:GameText/loaddata-ar`), like so:
---`return require('Module:GameText/loaddata').load('<lang>')`
---@param lang string Language code
---@return table data
p.load = function(lang)
	-- attempt to load the cached data
	local success, result = pcall(function()
		return mw.text.jsonDecode(cache.get(':_gametext:data:' .. lang), mw.text.JSON_PRESERVE_KEYS)
	end)
	if success then
		-- cached data is available, just return it
		return result
	end

	-- cached data is not available, so we need to recreate it

	---Fetch the database. We use `require()` for this and not `mw.loadData()`
	---because the return table of `mw.loadData()` has a metatable and therefore
	---cannot be used with `cache.set()` and `mw.loadData()`.
	---@type table
	local jsonStr = require('Module:GameText/db-' .. lang) or '{}'

	-- cache the JSON string
	cache.set(':_gametext:data:' .. lang, jsonStr)
	return mw.text.jsonDecode(jsonStr, mw.text.JSON_PRESERVE_KEYS)
end

---Purge the game text database for the specified language `<lang>`. When the
---`load` function is called the next time, the database cache will be forcefully
---recreated.
---This function should only be called from the `purge` function of
---`Module:GameText`. That function can be invoked from wikitext via
---`{{#invoke:GameText|purge|lang=<lang>}}`, which is done on each
---`Module:GameText/db-<lang>/doc` page. So purging that documentation page (or
---the module page `Module:GameText/db-<lang>` itself) will call this function
---and purge the respective language's game text database cache.
---@param lang string Language code
p.purge = function(lang)
	cache.delete(':_gametext:data:' .. lang)
end

return p