Module:Arguments: Difference between revisions

Revision as of 08:19, 9 December 2013

This Lua module is used in system messages.
Changes to it can cause immediate changes to the Wikipedia user interface.
To avoid major disruption, any changes should be tested in the module's /sandbox or /testcases subpages, or in your own module sandbox. The tested changes can be added to this page in a single edit. Please discuss changes on the talk page before implementing them.

‹ The template below (Module rating) is being considered for merging with Template rating. See templates for discussion to help reach a consensus. ›

Protected

This module is subject to page protection. It is a highly visible module in use by a very large number of pages, or is substituted very frequently. Because vandalism or mistakes would affect many pages, and even trivial editing might cause substantial load on the servers, it is protected from editing.

File:Cascade-protection-shackle.svg

This module can only be edited by administrators because it is transcluded onto one or more cascade-protected pages.

This module provides easy processing of arguments passed from #invoke. It is a meta-module, meant for use by other modules, and should not be called from #invoke directly (for a module directly invocable by templates you might want to have a look at Template:Ml). Its features include:

Easy trimming of arguments and removal of blank arguments.
Arguments can be passed by both the current frame and by the parent frame at the same time. (More details below.)
Arguments can be passed in directly from another Lua module or from the debug console.
Most features can be customized.

-- This module provides easy processing of arguments passed to Scribunto from #invoke.
-- It is intended for use by other Lua modules, and should not be called from #invoke directly.

local arguments = {}

function arguments.getArgs(frame, options)
	options = type(options) == 'table' and options or {}

	-- Get the arguments from the frame object if available. If the frame object is not available, we are being called
	-- from another Lua module or from the debug console, so assume arguments are passed directly in.
	local fargs, pargs
	if frame == mw.getCurrentFrame() then
		fargs = frame.args
		pargs = frame:getParent().args
	else
		fargs = type(frame) == 'table' and frame or {}
		pargs = {}
	end

	local args, metaArgs, metatable = {}, {}, {}
	setmetatable(args, metatable)

	local function tidyVal(key, val)
		-- Processes a value according to the options given to getArguments. Can trim whitespace and remove blanks.
		-- Keys are not used here, but they can be used by user-generated functions, so defining it here to avoid breakage.
		if type(val) == 'string' then
			if options.trim ~= false then
				val = mw.text.trim(val)
			end
			if options.removeBlanks == false or mw.ustring.find(val, '%S') then
				return val
			end
		else
			return val
		end
	end

	-- Use a user-generated functions to tidy the values if specified.
	local valueFunc = options.valueFunc
	if valueFunc then
		local valueFuncType = type(valueFunc)
		if valueFuncType == 'function' then
			tidyVal = valueFunc
		else
			error('type error in option "valueFunc": expected function, got ' .. valueFuncType, 2)
		end
	end

	local function mergeArgs(iterator, ...)
		-- Accepts multiple tables as input and merges their keys and values into one table using the specified iterator.
		-- If a value is already present it is not overwritten; tables listed earlier have precendence.
		local tables = {...}
		for _, t in ipairs(tables) do
			for key, val in iterator(t) do
				if metaArgs[key] == nil then
					metaArgs[key] = tidyVal(key, val)
				end
			end
		end
	end

	-- Set the order of precedence of frame args and parent args.
	local firstArgs, secondArgs = fargs, pargs
	if options.parentFirst then
		firstArgs, secondArgs = pargs, fargs
	end

	-- Define metatable behaviour.
	metatable.__index = function (t, key)
		local val = metaArgs[key]
		if val ~= nil then
			return val
		else
			local firstVal = tidyVal(key, firstArgs[key])
			if firstVal ~= nil then
				return firstVal
			else
				return tidyVal(key, secondArgs[key])
			end
		end
	end

	metatable.__newindex = function (t, key, val)
		if not options.readOnly and (not options.noOverwrite or metaArgs[key] == nil) then
			metaArgs[key] = val
		end
	end

	metatable.__pairs = function ()
		if not metatable.donePairs then
			mergeArgs(pairs, firstArgs, secondArgs)
			metatable.donePairs = true
			metatable.doneIpairs = true
		end
		return pairs(metaArgs)
	end

	metatable.__ipairs = function ()
		if not metatable.doneIpairs then
			mergeArgs(ipairs, firstArgs, secondArgs)
			metatable.doneIpairs = true
		end
		return ipairs(metaArgs)
	end
	
	return args
end

return arguments