Module:Item

From Terraria Mods Wiki
Jump to navigation Jump to search
Lua.svg Documentation The documentation below is transcluded from Module:Item/doc. (edit | history)

This module is intended to provide functionality to the {{item}} template.


local md5 = function(str)
	return mw.hash.hashValue('md5', str)
end

local trim = mw.text.trim
local cargo = mw.ext.cargo
local cache = require 'mw.ext.LuaCache'

local should_cache = true

---A cached version of the current frame, the interface to the parser.
local currentFrame
---Holds the arguments from the template call.
local args_table


---Return a trimmed version of the value of the template parameter with the specified `key`.
---Return `nil` if the parameter is empty or unset.
---@param key string|number
---@return string|nil
local function getArg(key)
	local value = args_table[key]
	if not value then
		return nil
	end
	value = trim(value)
	if value == '' then
		return nil
	end
	return value
end

---Convert a string of parameters in a `₫param1:value^₫param2:value^` format to a table.
---Change the `name` and `text` parameters to `1` and `2`, respectively.
---@param paramstr string
---@return table
local function parse(paramstr)
	local args = {}
	-- cannot use string.gmatch here, must be mw.ustring.gmatch
	for s in mw.ustring.gmatch(paramstr, '%b₫^') do
		local k,v = mw.ustring.match(s, '^₫(.-):(.*)^$')
		args[k] = v
	end
	args[1] = args['name']
	args[2] = args['text']
	return args
end

local function getCacheKey(arg)
	return
	"₫name:"..(arg[1] or '')..
	"^₫text:"..(arg[2] or '')..
	"^₫mod:"..(arg['mod'] or '')..
	"^₫mode:"..(arg['mode'] or '')..
	"^₫rowspan:"..(arg['rowspan'] or '')..
	"^₫image:"..(arg['image'] or '')..
	"^₫scale:"..(arg['scale'] or '')..
	"^₫size:"..(arg['size'] or '')..
	"^₫maxsize:"..(arg['maxsize'] or '')..
	"^₫ext:"..(arg['ext'] or '')..
	"^₫nolink:"..(arg['nolink'] and 'y' or '')..
	"^₫link:"..(arg['link'] or '')..
	"^₫small:"..(arg['small'] or '')..
	"^₫anchor:"..(arg['anchor'] or '')..
	"^₫note:"..(arg['note'] or '')..
	"^₫note2:"..(arg['note2'] or '')..
	"^₫bignote:"..(arg['bignote'] or '')..
	"^₫id:"..(arg['id'] or '')..
	"^₫showid:"..(arg['showid'] or '')..
	"^₫type:"..(arg['type'] or '')..
	"^₫wrap:"..(arg['wrap'] or '')..
	"^₫class:"..(arg['class'] or '')..
	"^₫css:"..(arg['css'] or '')..
	"^"
end

---Split the `str` on each `div` in it and return the result as a table.
---Original version credit: http://richard.warburton.it. This version trims each substring.
---@param div string
---@param str string
---@return table|boolean
local function explode(div,str)
	if (div=='') then return false end
	local pos,arr = 0,{}
	-- for each divider found
	for st,sp in function() return string.find(str,div,pos,true) end do
		arr[#arr + 1] = trim(string.sub(str,pos,st-1)) -- Attach chars left of current divider
		pos = sp + 1 -- Jump past current divider
	end
	arr[#arr + 1] = trim(string.sub(str,pos)) -- Attach chars right of last divider
	return arr
end

---Extract scale, width, and height from an input string. Up to two of the three can be empty in the input.
---Example: `5x7px*0.75` → `0.75`, `5`, `7`
---@param size string
---@return string basescale
---@return number width
---@return number height
local function parseSize(size)
	if not size then return end
	local basescale, width, height
	size, basescale = unpack(explode('*', size))
	if size ~= '' then
		width, height = unpack(explode('x', string.gsub(size, 'px', '')))
		width, height = tonumber(width), tonumber(height)
		if width == 0 then width = nil end
		if height == 0 then height = nil end
	end
	return basescale, width, height
end

---Return width, height, and caching date for the specified `imagename` from the Imageinfo cargo table.
---@param imagename string
---@return number width
---@return number height
---@return string cached
local function getInfoFromCargo(imagename)
	-- try to get from cargo cache
	local result = mw.ext.cargo.query('Imageinfo', 'width, height, cached', {
		-- md5name for case-sensitive query.
		where = 'md5name='.. "'"..md5(imagename).."'",
		orderBy = "cached DESC",
		limit = 1,
	})
	for _, row in ipairs(result) do
		return tonumber(row['width']), tonumber(row['height']), row['cached']
	end
end

---Store width and height of the specified `imagename` to the Imageinfo cargo table and return them.
---Width and height are computed via the `#imgw:` and `#imgh:` parser functions, respectively.
---@param imagename string
---@return number width
---@return number height
local function storeInfoToCargo(imagename)
	-- don't cache {{item}}'s result when parsing imagesize fails.
	should_cache = false
	local imageTitle = mw.title.new("File:" .. imagename)
	local width, height = imageTitle.file.width, imageTitle.file.height
	if width and width ~= 0 and height and height ~= 0 then
		should_cache = true -- ok, cache it.
		currentFrame:callParserFunction('#cargo_store:_table=Imageinfo',{
			image = imagename,
			md5name = md5(imagename),
			width = width,
			height = height,
			cached = os.time(),
		})
	end
	return width, height
end

---Retrieve the dimensions of the specified `image` from the Imageinfo cargo table.
---If it doesn't have any data for the image yet, store it.
---@param imagename string
---@return number width
---@return number height
local function getSizeInfo(imagename)
	local width, height, cached = getInfoFromCargo(imagename)
	-- cache missed, init cache
	if not cached then
		width, height = storeInfoToCargo(imagename)
	end
	if width == 0 then width = nil end
	if height == 0 then height = nil end
	return width, height
end

---Compute the final width and height of the image.
---If necessary, retrieve data from or store data to the Imageinfo cargo table.
---@param imagename string
---@param width number
---@param height number
---@param scale number
---@param maxwidth number
---@param maxheight number
---@return number width
---@return number height
local function getImageSize(imagename, width, height, scale, maxwidth, maxheight)
	-- get size info from image file itself (may be expensive)
	local w, h = getSizeInfo(imagename) -- store data to cache

	-- if width and height are not given as input, but scale/maxwidth/maxheight are, then
	-- set width and height to the original dimensions of the image
	if not width and not height and (scale or maxwidth or maxheight) then
		width, height = w, h
	end

	-- apply scale to width/height if needed
	if scale then
		if width then width = width * scale end
		if height then height = height * scale end
	end

	-- apply maxwidth/maxheight
	if maxwidth then
		if width then
			if width > maxwidth then width = maxwidth end
		else
			if height then width = maxwidth end
		end
	end
	if maxheight then
		if height then
			if height > maxheight then height = maxheight end
		else
			if width then height = maxheight end
		end
	end

	-- round to natural numbers
	if width then width = math.ceil(width) end
	if height then height = math.ceil(height) end

	return width, height
end

---Extract width and height from an input string.
---Example: `6x9px` → `6`, `9`
---@param maxsize string
---@return number maxwidth
---@return number maxheight
local function parseMaxSize(maxsize)
	if not maxsize then return end
	local maxwidth, maxheight = unpack(explode('x', string.gsub(maxsize, 'px', '')))
	maxwidth, maxheight = tonumber(maxwidth), tonumber(maxheight)
	if maxwidth == 0 then maxwidth = nil end
	if maxheight == 0 then maxheight = nil end
	return maxwidth, maxheight
end

---Assemble the final wikicode for an image.
---@param imagename string
---@param link string
---@param text string
---@param size string As accepted by the `[[File:` syntax, e.g. `5x7px*0.75`.
---@param scale number This will be multiplied by the scale in `size`, if necessary.
---@param maxsize string
---@return string
local function imagecode(imagename, link, text, size, scale, maxsize)
	local image_output = '[[File:' .. imagename .. '|link='.. link .. '|' .. text
	if size or scale or maxsize then
		local basescale, width, height = parseSize(size) -- width, height: number or nil (basescale is string!)
		scale = (tonumber(scale) or 1) * (tonumber(basescale) or 1) -- combine the scale parameter and scale from the size parameter
		if scale == 0 or scale == 1 then
			scale = nil
		end
		local maxwidth, maxheight = parseMaxSize(maxsize)
		width, height = getImageSize(imagename, width, height, scale, maxwidth, maxheight) -- can be 0
		if width or height then
			image_output = image_output .. '|' .. (width or '') .. 'x' .. (height or '') .. 'px'
		end
	end
	return image_output .. ']]'
end

---Return the full `[[File:` wikicode for each image in the input (multiple are separated with `/`).
---@param image string
---@param link string
---@param text string
---@param size string
---@param scale string
---@param maxsize string
---@return string
local function images(image, link, text, size, scale, maxsize)

	if not image:find('/') then
		-- there is only one image in the input
		return imagecode(image, link, text, size, scale, maxsize)
	end

	-- there are multiple images in the input, separated with a slash
	image = explode('/', image)
	local result = ''
	if size and size:find('/') then
		-- there are multiple sizes in the size parameter
		size = explode('/', size) -- so turn it into a table
		for i, v in ipairs(image) do -- iterate over the images
			result = result .. imagecode(v, link, text, size[i], scale, maxsize) -- create the wikicode (using the respective size)
		end
	else
		for i, v in ipairs(image) do -- iterate over the images
			result = result .. imagecode(v, link, text, size, scale, maxsize) -- create the wikicode
		end
	end
	return result
end

---Return a string like `Internal Item ID: `, depending on the `_type`.
---@param _type '"item"'|'"tile"'|'"wall"'|'"npc"'|'"mount"'|'"buff"'|'"projectile"'|'"armor"'
---@return string
local function getIdText(_type)
	local id_text
	if _type == 'item' then -- a shortcut for faster
		id_text = 'Internal [[Item IDs|Item ID]]: '
	elseif _type == 'tile' then
		id_text = 'Internal [[Tile IDs|Tile ID]]: '
	elseif _type == 'wall' then
		id_text = 'Internal [[Wall IDs|Wall ID]]: '
	elseif _type == 'npc' then
		id_text = 'Internal [[NPC IDs|NPC ID]]: '
	elseif _type == 'mount' then
		id_text = 'Internal [[Mount IDs|Mount ID]]: '
	elseif _type == 'buff' or _type == 'debuff' then
		id_text = 'Internal [[Buff IDs|Buff ID]]: '
	elseif _type == 'projectile' then
		id_text = 'Internal [[Projectile IDs|Projectile ID]]: '
	elseif _type == 'armor' then
		id_text = 'Internal [[Armor IDs|Armor ID]]: '
	else
		id_text = 'Internal [[Item IDs|Item ID]]: '
	end
	return id_text
end

local handleModItem = function(modname)
	args_table[1] = args_table[1]:gsub('‡‡', '#') -- decode the hash character, was encoded in {{item}} to prevent expansion to <ol></ol>
	args_table[2] = args_table[2]:gsub('‡‡', '#')
	if args_table[1]:sub(1, 1) == '#' then
		local pos = args_table[1]:find('@')
		if pos then
			modname = args_table[1]:sub(pos+1)
			args_table[1] = args_table[1]:sub(1, pos-1)
		end
		if args_table[1]:sub(2, 2) == '#' then
			local itemname = args_table[1]:sub(3)
			if not getArg(2) or args_table[2]:sub(1, 2) == '%%' then
				args_table[2] = itemname
			end
			args_table[1] = itemname
			if modname then
				args_table[1] = modname .. '/' .. itemname
				args_table['note'] = (getArg('note') and args_table['note'] .. ' ' or '') .. '(' .. modname .. ')'
				if not getArg('image') then
					local normalized_modname = modname:gsub('/', '-'):gsub(':', '-')
					args_table['image'] = itemname .. ' (' .. normalized_modname .. ').' .. (getArg('ext') or 'png')
				end
				if not getArg('wrap') then
					args_table['wrap'] = 'y'
				end
			end
		else
			local itemname = args_table[1]:sub(2)
			if not getArg(2) or args_table[2]:sub(1, 2) == '%%' then
				args_table[2] = itemname
			end
			args_table[1] = itemname
			if modname then
				args_table[1] = modname .. '/' .. itemname
				if not getArg('image') then
					local normalized_modname = modname:gsub('/', '-'):gsub(':', '-')
					args_table['image'] = itemname .. ' (' .. normalized_modname .. ').' .. (getArg('ext') or 'png')
				end
			end
		end
	end
	if getArg(2) and args_table[2]:sub(1, 2) == '%%' then
		args_table[2] = args_table[2]:sub(3)
	end
end


-----------------------------------------------------------------
-- main return object
return {

parse = parse,
go = function(frame, args)
	-- init var cache
	currentFrame = frame
	args_table = args or parse(frame.args[1])

	local modname = getArg('mod') or currentFrame:expandTemplate{ title = 'modname', args = { 'get' } }
	args_table['mod'] = modname
	
	-- cache?
	local cache_key = args and getCacheKey(args) or (':_item:' .. frame.args[1])
	local cached = cache.get(cache_key)
	if cached then
		return cached
	end
	handleModItem(modname)

	local _arg1 = getArg(1) or ''
	local _nolink = getArg('nolink')
	local _link = _nolink and '' or getArg('link') or _arg1 -- now: _link == '' means nolink

	local text = getArg(2) or ''

	-- set output flags
	local output_image, output_text, output_table = true, true, false
	local _mode = getArg('mode')
	if _mode then
		if _mode == 'image' or _mode == 'imageonly' or _mode =='onlyimage' then
			output_text = false
		elseif _mode == 'text' or _mode == 'noimage' then
			output_image = false
		elseif _mode == 'table' or _mode == '2-cell' then
			output_table = true
		end
	end

	local hovertext
	if output_image and not output_text then
		-- with image only, the hovertext will only be displayed on the image, so it should be text or _arg1 or _link (in that order)
		if text ~= '' then
			hovertext = text
		elseif _arg1 ~= '' then
			hovertext = _arg1
		else
			hovertext = _link
		end
	else
		-- with image and text, the hovertext will be displayed on the image and on the text, so it should be _arg1 or text or _link (in that order)
		if _arg1 ~= '' then
			hovertext = _arg1
		elseif text ~= '' then
			hovertext = text
		else
			hovertext = _link
		end
	end

	local class = 'i'

	local image_output, text_output
	-- get wikicode for the image(s)
	if output_image then
		local image_arg = getArg('image')
		if not image_arg then
			image_arg = string.gsub(string.gsub(_arg1, ":%s*", " "), "/" , " ")
			image_arg = image_arg .. '.' .. (getArg('ext') or 'png')
		end
		if string.find(image_arg, '%[%[[fF]ile:') then
			image_output = '<span class="img">' .. image_arg .. '</span>'
		else
			image_output = images(image_arg, _link, hovertext, getArg('size'), getArg('scale'), getArg('maxsize'))
		end
	else
		image_output = ''
	end

	-- get wikicode for the text
	if output_text then
		local _note, _note2, _bignote, _showid, _id = getArg('note'), getArg('note2'), getArg('bignote'), getArg('showid'), getArg('id') -- get info from arguments

		-- prepare: display ID?
		if _id and not _showid then
			_showid = true
		end
		if _showid and (_showid == 'n' or _showid == 'no') then
			_showid = false
		end

		-- prepare: wrap?
		local _wrap
		if _showid or _note2 then
			_wrap = false
		else
			_wrap = getArg('wrap')
		end

		-- prepare: link and display text
		if _link == '' or text == '' then
			text = '<span title="'..hovertext..'">'..text..'</span>'
		else
			if text == _link then
				text = '<span>[['..text..']]</span>'
			else
				text = '<span>[['.._link..'|'..text..']]</span>'
			end
		end

		-- assemble HTML code
		local content = text -- item name link text first.
		-- '-w' class means 'wrapmode', optimized for multiple lines of text. But it should be disabled for single line text.
		if _wrap then
			-- note in a new line
			if _note then
				class = class .. ' -w'
				content = content .. '<span class="note">' .. _note .. '</span>'
			end
		else
			-- note in the same line
			if _note then
				content = content .. '<span class="note">' .. _note .. '</span>'
			end
			if _note2 then
				class = class .. ' -w'
				content = content .. '<span class="note2">' .. _note2 .. '</span>'
			end
			-- id in a new line
			if _showid then
				class = class .. ' -w'
				local idtype = (getArg('type') or 'item'):lower()
				local id_text = getIdText(idtype)
				content = content .. '<span class="id">' .. id_text .. _id .. '</span>'
			end
		end
		if _bignote then
			text_output = '<span>' .. content .. '</span><span>' .. _bignote .. '</span>'
		else
			text_output = '<span>' .. content .. '</span>'
		end
	else
		text_output = ''
	end

	-- handle custom CSS
	local _class, _css = getArg('class'), getArg('css')
	if _class then
		class = class .. ' ' .. _class -- add to existing classes
	end
	local attr = {class = class}
	if _css then
		attr.style = _css -- set the style attribute to parameter value
	end

	-- anchor:
	local _anchor = false
	if getArg('anchor') then
		_anchor = '<s class="anchor" id="' .. frame:callParserFunction('anchorencode', _arg1) .. '"></s>'
		--text_output = text_output .. '<s class="anchor" id="' .. frame:callParserFunction('anchorencode', _arg1) .. '"></s>'
	end

	local return_string
	if output_table then
		-- table output
		attr.class = class
		local _rowspan = getArg('rowspan')
		local rowspan_text = (_rowspan and (' rowspan=' .. _rowspan) or '')
		-- prepare the two cells
		local first_cell_pre = rowspan_text .. ' class="il1c"'
		local first_cell_content = mw.text.tag('span', attr, image_output)
		if _anchor then
			first_cell_content = _anchor .. first_cell_content
		end
		local second_cell_pre = rowspan_text .. ' class="il2c"'
		local second_cell_content = mw.text.tag('span', attr, text_output)
		-- combine
		return_string = first_cell_pre .. " | " .. first_cell_content .. " || " .. second_cell_pre .. " | " .. second_cell_content
	else
		-- non-table output (text/image)
		return_string = mw.text.tag('span', attr, _anchor and (image_output .. text_output .. _anchor) or (image_output .. text_output) )
	end

	-- cache output for reuse
	if should_cache then
		cache.set(cache_key, return_string, 3600*24) -- cache for 24 hours
	end

	-- output
	return return_string

end,

purge = function(frame)
	cache.delete(':_item:' .. frame.args[1]) -- delete that cache key.
end,

storeImageInfo = function(frame)
	currentFrame = frame
	local width, height = storeInfoToCargo(frame.args[1])
	if not width or width == 0 or not height or height == 0 then
		return
	else
		return frame:callParserFunction{name = "#dplvar:set", args = {
			"_image_exist", "1",
			"_image_width", width,
			"_image_height", height,
		}}
	end
end,

}