Module:Icon
Documentation for this module may be created at Module:Icon/doc
--- A library that other modules can use to create icon images with automatic prefix/suffix settings for items, characters, and weapons.
-- (Other icon types must have their types/suffixes specified manually.)
--
-- '''Note:''' this module is (currently) NOT related to [[Template:Icon]].
--
-- @script Icon
local TemplateData = require('Module:TemplateData')
local p = {}
local FOOD_PREFIXES = {
['Suspicious '] = 1,
['Delicious '] = 1,
}
-- icon arg defaults for template data
-- uses list format to ensure that the order is the same when added to another list of args using `p.addIconArgs`
local ICON_ARGS = {
{name='name',
label='Name',
description='The name of the {labelPrefix}image.',
example={'Furnishing Blueprint', 'Fruit Paste Bait', 'Anemo'}
},
{name='link', displayType='wiki-page-name', defaultFrom='name',
label='Link',
description='The page that the {labelPrefix}image links to.'
},
{name='extension', alias='ext', default='png',
label='File Extension',
description='The file extension for the {labelPrefix}image.',
example={'png', 'jpg', 'jpeg', 'gif'},
},
{name='type', displayDefault='determined based on {labelPrefix}Name; "Item" if unknown',
label='File Prefix',
description='The file prefix to prepend to {labelPrefix}Name.',
example={'Item', 'Weapon', 'Character', 'Icon'}
},
{name='suffix', displayDefault='determined based on {labelPrefix}Name/{labelPrefix}Type',
label='File Suffix',
description='The file suffix to append to {labelPrefix}Name.',
example={'Icon', 'Thumb', '2nd', 'White'}
},
{name='size', default='20',
label='Size',
description='The height and width of the {labelPrefix}image in pixels. A single number will be used for both height and width; to specify them separately, use \'wxh\' format.',
example={'20', '20x10', '20x', 'x20'}
},
{name='alt', defaultFrom='name', displayDefault='determined based on {labelPrefix}Name, and updated based on {labelPrefix}Character Outfit and {labelPrefix}Weapon Ascension Phase',
label='Alt Text',
description='The alt text of the {labelPrefix}image.',
},
{name='outfit', alias='o',
label='Character Outfit',
description='Name of the Outfit equipped on the character in the {labelPrefix}image. (Ignored if not a character.)',
example='Sea Breeze Dandelion'
},
{name='ascension', alias='a', type='number', default=0,
label='Weapon Ascension Phase',
description='Ascension Phase of the weapon in the {labelPrefix}image. (Weapon image changes for ascension 2 or higher. Ignored if not a weapon.)',
example={'1', '2'}
},
}
--- Returns a table version of the input.
-- @param v A table or an item that belongs in a table.
-- @return {table}
local function ensureTable(v)
if type(v) == 'table' then return v end
return {v}
end
--- A special constant that can be used as a value in the `overrides` parameter for `addIconArgs`
-- to disable the given base config or TemplateData key.
p.EXCLUDE = {};
--- Copy entries from b into a, excluding values that are `p.EXCLUDE`.
-- @param {table} a Table to insert into.
-- @param {table} b Table to copy from.
local function copyTable(a, b)
for k, v in pairs(b) do
if v == p.EXCLUDE then
v = nil
end
a[k] = v
end
end
--- A function that other modules can use to append Icon arguments to their template data.
-- @param {TemplateData#ArgumentConfigList} base The template data to append to.
-- If any configs have a `name` that matches an Icon argument's (with `namePrefix`)
-- and a property `placeholderFor` set to `'Module:Icon'`, then the
-- corresponding Icon argument will replace it instead of being appended.
-- (This allows argument order to be changed for [[Module:TemplateData]]'s
-- documentation generation.)
-- @param {string} namePrefix A string to prepend to all parameter names.
-- @param {string} labelPrefix A string to prepend to all parameter labels
-- (the names displayed in documentation).
-- @param {TemplateData#ArgumentConfigMap} overrides A table of overrides to configure the template data.
-- Keys should be parameter names, and values are tables of TemplateData
-- configuration objects to merge with the default configuration.
-- These configuration objects can use @{Icon.EXCLUDE} as values to disable
-- the corresponding default configuration key (e.g., to disable a default value
-- or alias without adding a new one).
function p.addIconArgs(baseConfigs, namePrefix, labelPrefix, overrides)
-- preprocessing: save position of each placeholder config
local argLocations = {}
for i, config in ipairs(baseConfigs) do
if config.placeholderFor == 'Module:Icon' then
argLocations[config.name] = i
end
end
-- main loop: prepend namePrefix and labelPrefix where needed
-- and add configs to baseConfigs
for _, config in ipairs(ICON_ARGS) do
local override = overrides[config.name]
if override ~= false and override ~= p.EXCLUDE then
local c = {}
copyTable(c, config)
c.name = namePrefix .. c.name
c.label = labelPrefix .. c.label
if c.defaultFrom then
c.defaultFrom = namePrefix .. c.defaultFrom
end
if c.alias then
local aliases = {}
for _, a in ipairs(ensureTable(c.alias)) do
table.insert(aliases, namePrefix .. a)
end
c.alias = aliases
end
if override then
copyTable(c, override)
end
if c.description then
c.description = c.description:gsub('{labelPrefix}', labelPrefix)
end
if c.displayDefault then
c.displayDefault = c.displayDefault:gsub('{labelPrefix}', labelPrefix)
end
local placeholderIndex = argLocations[c.name]
if placeholderIndex then
baseConfigs[placeholderIndex] = c
else
table.insert(baseConfigs, c)
end
end
end
end
local function extendTable(base, extra)
out = {}
setmetatable(out, {
__index = function(t, key)
-- be defensive: base or extra may be nil
local val
if base ~= nil then
val = base[key]
end
if val ~= nil then
return val
end
if extra ~= nil then
return extra[key]
end
return nil
end
})
return out
end
local neighbors = mw.loadData('Module:Card/neighbors')
local ALL_DATA = {-- list of {type, data} in the order that untyped items should get checked
{'Neighbor', neighbors},
{'Creature', mw.loadData('Module:Card/creatures')},
{'Dish', mw.loadData('Module:Card/dishes')},
{'Plant', mw.loadData('Module:Card/plants')},
{'Furniture', mw.loadData('Module:Card/furnitures')},
{'Outfit', mw.loadData('Module:Card/outfits')},
{'Item', extendTable(characters, mw.loadData('Module:Card/items'))} -- allow characters to be items
}
--- A basic image type with filename prefix/suffix support.
-- Extends @{TemplateData#TableWithDefaults} with image-related properties,
-- allowing default property values to be customized after creation.
--
-- Image objects are created by @{Icon.createIcon}.
-- Use @{Image:buildString} to convert to wikitext.
-- @type Image
local IMAGE_ARGS = {
size = {default=''},
name = {default='', alias=1},
prefix = {default=''},
prefixSeparator = {default=' '},
suffix = {default=''},
suffixSeparator = {default=' '},
extension = {default='png', alias='ext'},
link = {defaultFrom='name'},
alt = {defaultFrom='name'},
}
local function buildImageFullPrefix(img)
local prefix = img.prefix
if prefix ~= '' then
return prefix .. img.prefixSeparator
end
return ''
end
local function buildImageFullSuffix(img)
local suffix = img.suffix
if suffix ~= '' then
return img.suffixSeparator .. suffix
end
return ''
end
local function buildImageFilename(img)
if img.name == '' then return '' end
return 'File:' .. buildImageFullPrefix(img) .. img.name .. buildImageFullSuffix(img) .. '.' .. img.extension
end
local function buildImageSizeString(img)
local size = img.size
if size == nil or size == '' then
return ''
end
size = tostring(size)
if size:find('x', 1, true) then
return size .. 'px'
end
return size .. 'x' .. size .. 'px'
end
--[[
Returns wikitext that will display this image.
@return {string} Wikitext
@function Image:buildString
--]]
local function buildImageString(img)
local filename = buildImageFilename(img)
if filename == '' then return '' end
return '[[' .. filename .. '|' .. buildImageSizeString(img) .. '|link=' .. img.link .. '|alt=' .. img.alt .. ']]'
end
--[[
Creates an `Image` object with the given properties.
@param {table} args A table of `Image` properties that to assign to the new `Image`.
@see @{Image} for property documentation
@return {Image} The new `Image` object.
@constructor
--]]
local function createImage(args)
local out
if type(args) == 'table' then
out = TemplateData.processArgs(args, IMAGE_ARGS, {preserveDefaults=true})
else
out = {name = args}
end
-- add buildString function to image directly, not to image.nonDefaults
rawset(out, 'buildString', buildImageString)
return out
end
--- The name of the image. Used to determine filename.
-- @property {string} Image.name
--- Maximum image size using wiki image syntax.
-- Unlike regular wiki image syntax, a single number specifies both height and width.
-- @property {string} Image.size
--- Image file prefix.
-- @property {string} Image.prefix
--- Appended to `prefix` if `prefix` is not empty. Defaults to a single space.
-- @property[opt] {string} Image.prefixSeparator
--- Image file suffix.
-- @property {string} Image.suffix
--- Prepended to `suffix` if `suffix` is not empty. Defaults to a single space.
-- @property {string} Image.suffixSeparator
--- Image file extension. (Alias: `ext`.)
-- @property {string} Image.extension
--- Image link. Also sets title (hover tooltip). Defaults to `name`.
-- @property {string} Image.link
--- Image alt text. Defaults to `name`.
-- @property {string} Image.alt
--- A helper function for other modules to get icon args with a prefix from the given table.
-- @param {table} args A table containing icon args (and probably other args).
-- @param {string} prefix Prefix for keys to use when looking up entries from `args`.
-- If not specified, no prefix is used.
-- @return {table} A table containing only the extracted args, with the prefix removed from its keys.
function p.extractIconArgs(args, prefix)
prefix = prefix or ''
local out = TemplateData.createObjectWithDefaults()
for _, config in pairs(ICON_ARGS) do
out.defaults[config.name] = args.defaults[prefix .. config.name]
out.nonDefaults[config.name] = args.nonDefaults[prefix .. config.name]
end
return out
end
--- A helper function that removes one of the given prefixes from the given string.
-- @param {string} str The string from which to strip a prefix
-- @param {table} prefixes A table whose keys are the possible prefixes to strip from `str`
-- @return {string} The string with the prefix removed.
-- @return[opt] {string} The prefix that was removed, or `nil` if no prefix was found.
function p.stripPrefixes(str, prefixes)
for prefix, _ in pairs(prefixes) do
if string.sub(str, 1, string.len(prefix)) == prefix then
return string.sub(str, string.len(prefix) + 1), prefix
end
end
return str
end
--[[
The main entry point for other modules.
Creates and returns an Image object with the given arguments.
Infers `args.type` if `args.name` matches a known item/character/weapon.
@param {table} args Table containing the arguments:
@param[opt] {string} args.name The name of the image.
Used to determine file name and set the default link and alt text.
If not specified, the output `Image` will produce empty wikitext.
@param[opt] {string} args.link Image link. Also sets title (hover tooltip).
Defaults to `name`.
@param[opt] {string} args.extension (alias: `ext`) Image file extension.
Defaults to 'png'.
@param[opt] {string} args.type Image type. Used to determine file prefix and default file suffix.
If not specified, type will be inferred if `args.name`
is a known item; otherwise, defaults to 'Item'.
@param[opt] {string} args.suffix File suffix override.
@param[opt] {string} args.size Maximum image size using wiki image syntax.
Unlike regular wiki image syntax, specifying a single number will
set both height and width.
@param[opt] {string} args.alt Image alt text. Defaults to `args.name`, but
also changes with `args.outfit` or `args.ascension`.
@param[opt] {string} args.outfit Character outfit. Only applies to character images.
@param[opt] {number} args.ascension Weapon ascension level. Only applies to weapon images.
@param[opt] {string} prefix Prefix to use when looking up arguments in `args`.
@return {Image} The image for given arguments.
Use `Image:buildString()` to get the wikitext for the image.
@return {string} The image type.
@return {TableWithDefaults} Associated data for given item (e.g., rarity, display name).
--]]
function p.createIcon(args, prefix)
if prefix then
args = p.extractIconArgs(args, prefix)
end
args = TemplateData.processArgs(args, ICON_ARGS, {preserveDefaults=true})
local baseName, prefix = p.stripPrefixes(args.name or '', FOOD_PREFIXES)
-- determine type by checking for data
local image_type, data
for i, v in ipairs(ALL_DATA) do
image_type = v[1]
if args.type == nil or args.type == image_type then
data = v[2][baseName]
if data then break end
end
end
image_type = args.type or image_type -- in case args.type isn't in ALL_DATA (e.g., Enemy, Wildlife)
local image = createImage(args)
image.suffix = 'Icon'
image.defaults.suffix = 'Icon'
return image, image_type, data
end
return p