Diff: Module:Arguments

-- This module provides easy processing of arguments passed to Scribunto from

-- 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

-- #invoke. It is intended for use by other Lua modules, and should not be

-- called from #invoke directly.

-- called from #invoke directly.

local libraryUtil = require('libraryUtil')

local libraryUtil = require('libraryUtil')

local checkType = libraryUtil.checkType

local checkType = libraryUtil.checkType

local arguments = {}

local arguments = {}

-- Generate four different tidyVal functions, so that we don't have to check the

-- Generate four different tidyVal functions, so that we don't have to check the

-- options every time we call it.

-- options every time we call it.

local function tidyValDefault(key, val)

local function tidyValDefault(key, val)

	if type(val) == 'string' then

	if type(val) == 'string' then

		val = val:match('^%s*(.-)%s*$')

		val = val:match('^%s*(.-)%s*$')

		if val == '' then

		if val == '' then

			return nil

			return nil

		else

		else

			return val

			return val

		end

		end

	else

	else

		return val

		return val

	end

	end

end

end

local function tidyValTrimOnly(key, val)

local function tidyValTrimOnly(key, val)

	if type(val) == 'string' then

	if type(val) == 'string' then

		return val:match('^%s*(.-)%s*$')

		return val:match('^%s*(.-)%s*$')

	else

	else

		return val

		return val

	end

	end

end

end

local function tidyValRemoveBlanksOnly(key, val)

local function tidyValRemoveBlanksOnly(key, val)

	if type(val) == 'string' then

	if type(val) == 'string' then

		if val:find('%S') then

		if val:find('%S') then

			return val

			return val

		else

		else

			return nil

			return nil

		end

		end

	else

	else

		return val

		return val

	end

	end

end

end

local function tidyValNoChange(key, val)

local function tidyValNoChange(key, val)

	return val

	return val

end

end

local function matchesTitle(given, title)

local function matchesTitle(given, title)

	local tp = type( given )

	local tp = type( given )

	return (tp == 'string' or tp == 'number') and mw.title.new( given ).prefixedText == title

	return (tp == 'string' or tp == 'number') and mw.title.new( given ).prefixedText == title

end

end

local translate_mt = { __index = function(t, k) return k end }

local translate_mt = { __index = function(t, k) return k end }

function arguments.getArgs(frame, options)

function arguments.getArgs(frame, options)

	checkType('getArgs', 1, frame, 'table', true)

	checkType('getArgs', 1, frame, 'table', true)

	checkType('getArgs', 2, options, 'table', true)

	checkType('getArgs', 2, options, 'table', true)

	frame = frame or {}

	frame = frame or {}

	options = options or {}

	options = options or {}

	--[[

	--[[

	-- Set up argument translation.

	-- Set up argument translation.

	--]]

	--]]

	options.translate = options.translate or {}

	options.translate = options.translate or {}

	if getmetatable(options.translate) == nil then

	if getmetatable(options.translate) == nil then

		setmetatable(options.translate, translate_mt)

		setmetatable(options.translate, translate_mt)

	end

	end

	if options.backtranslate == nil then

	if options.backtranslate == nil then

		options.backtranslate = {}

		options.backtranslate = {}

		for k,v in pairs(options.translate) do

		for k,v in pairs(options.translate) do

			options.backtranslate[v] = k

			options.backtranslate[v] = k

		end

		end

	end

	end

	if options.backtranslate and getmetatable(options.backtranslate) == nil then

	if options.backtranslate and getmetatable(options.backtranslate) == nil then

		setmetatable(options.backtranslate, {

		setmetatable(options.backtranslate, {

			__index = function(t, k)

			__index = function(t, k)

				if options.translate[k] ~= k then

				if options.translate[k] ~= k then

					return nil

					return nil

				else

				else

					return k

					return k

				end

				end

			end

			end

		})

		})

	end

	end

	--[[

	--[[

	-- Get the argument tables. If we were passed a valid frame object, get the

	-- Get the argument tables. If we were passed a valid frame object, get the

	-- frame arguments (fargs) and the parent frame arguments (pargs), depending

	-- frame arguments (fargs) and the parent frame arguments (pargs), depending

	-- on the options set and on the parent frame's availability. If we weren't

	-- on the options set and on the parent frame's availability. If we weren't

	-- passed a valid frame object, we are being called from another Lua module

	-- passed a valid frame object, we are being called from another Lua module

	-- or from the debug console, so assume that we were passed a table of args

	-- or from the debug console, so assume that we were passed a table of args

	-- directly, and assign it to a new variable (luaArgs).

	-- directly, and assign it to a new variable (luaArgs).

	--]]

	--]]

	local fargs, pargs, luaArgs

	local fargs, pargs, luaArgs

	if type(frame.args) == 'table' and type(frame.getParent) == 'function' then

	if type(frame.args) == 'table' and type(frame.getParent) == 'function' then

		if options.wrappers then

		if options.wrappers then

			--[[

			--[[

			-- The wrappers option makes Module:Arguments look up arguments in

			-- The wrappers option makes Module:Arguments look up arguments in

			-- either the frame argument table or the parent argument table, but

			-- either the frame argument table or the parent argument table, but

			-- not both. This means that users can use either the #invoke syntax

			-- not both. This means that users can use either the #invoke syntax

			-- or a wrapper template without the loss of performance associated

			-- or a wrapper template without the loss of performance associated

			-- with looking arguments up in both the frame and the parent frame.

			-- with looking arguments up in both the frame and the parent frame.

			-- Module:Arguments will look up arguments in the parent frame

			-- Module:Arguments will look up arguments in the parent frame

			-- if it finds the parent frame's title in options.wrapper;

			-- if it finds the parent frame's title in options.wrapper;

			-- otherwise it will look up arguments in the frame object passed

			-- otherwise it will look up arguments in the frame object passed

			-- to getArgs.

			-- to getArgs.

			--]]

			--]]

			local parent = frame:getParent()

			local parent = frame:getParent()

			if not parent then

			if not parent then

				fargs = frame.args

				fargs = frame.args

			else

			else

				local title = parent:getTitle():gsub('/sandbox$', '')

				local title = parent:getTitle():gsub('/sandbox$', '')

				local found = false

				local found = false

				if matchesTitle(options.wrappers, title) then

				if matchesTitle(options.wrappers, title) then

					found = true

					found = true

				elseif type(options.wrappers) == 'table' then

				elseif type(options.wrappers) == 'table' then

					for _,v in pairs(options.wrappers) do

					for _,v in pairs(options.wrappers) do

						if matchesTitle(v, title) then

						if matchesTitle(v, title) then

							found = true

							found = true

							break

							break

						end

						end

					end

					end

				end

				end

				-- We test for false specifically here so that nil (the default) acts like true.

				-- We test for false specifically here so that nil (the default) acts like true.

				if found or options.frameOnly == false then

				if found or options.frameOnly == false then

					pargs = parent.args

					pargs = parent.args

				end

				end

				if not found or options.parentOnly == false then

				if not found or options.parentOnly == false then

					fargs = frame.args

					fargs = frame.args

				end

				end

			end

			end

		else

		else

			-- options.wrapper isn't set, so check the other options.

			-- options.wrapper isn't set, so check the other options.

			if not options.parentOnly then

			if not options.parentOnly then

				fargs = frame.args

				fargs = frame.args

			end

			end

			if not options.frameOnly then

			if not options.frameOnly then

				local parent = frame:getParent()

				local parent = frame:getParent()

				pargs = parent and parent.args or nil

				pargs = parent and parent.args or nil

			end

			end

		end

		end

		if options.parentFirst then

		if options.parentFirst then

			fargs, pargs = pargs, fargs

			fargs, pargs = pargs, fargs

		end

		end

	else

	else

		luaArgs = frame

		luaArgs = frame

	end

	end

	-- Set the order of precedence of the argument tables. If the variables are

	-- Set the order of precedence of the argument tables. If the variables are

	-- nil, nothing will be added to the table, which is how we avoid clashes

	-- nil, nothing will be added to the table, which is how we avoid clashes

	-- between the frame/parent args and the Lua args.

	-- between the frame/parent args and the Lua args.

	local argTables = {fargs}

	local argTables = {fargs}

	argTables[#argTables + 1] = pargs

	argTables[#argTables + 1] = pargs

	argTables[#argTables + 1] = luaArgs

	argTables[#argTables + 1] = luaArgs

	--[[

	--[[

	-- Generate the tidyVal function. If it has been specified by the user, we

	-- Generate the tidyVal function. If it has been specified by the user, we

	-- use that; if not, we choose one of four functions depending on the

	-- use that; if not, we choose one of four functions depending on the

	-- options chosen. This is so that we don't have to call the options table

	-- options chosen. This is so that we don't have to call the options table

	-- every time the function is called.

	-- every time the function is called.

	--]]

	--]]

	local tidyVal = options.valueFunc

	local tidyVal = options.valueFunc

	if tidyVal then

	if tidyVal then

		if type(tidyVal) ~= 'function' then

		if type(tidyVal) ~= 'function' then

			error(

			error(

				"bad value assigned to option 'valueFunc'"

				"bad value assigned to option 'valueFunc'"

					.. '(function expected, got '

					.. '(function expected, got '

					.. type(tidyVal)

					.. type(tidyVal)

					.. ')',

					.. ')',

				2

				2

			)

			)

		end

		end

	elseif options.trim ~= false then

	elseif options.trim ~= false then

		if options.removeBlanks ~= false then

		if options.removeBlanks ~= false then

			tidyVal = tidyValDefault

			tidyVal = tidyValDefault

		else

		else

			tidyVal = tidyValTrimOnly

			tidyVal = tidyValTrimOnly

		end

		end

	else

	else

		if options.removeBlanks ~= false then

		if options.removeBlanks ~= false then

			tidyVal = tidyValRemoveBlanksOnly

			tidyVal = tidyValRemoveBlanksOnly

		else

		else

			tidyVal = tidyValNoChange

			tidyVal = tidyValNoChange

		end

		end

	end

	end

	--[[

	--[[

	-- Set up the args, metaArgs and nilArgs tables. args will be the one

	-- Set up the args, metaArgs and nilArgs tables. args will be the one

	-- accessed from functions, and metaArgs will hold the actual arguments. Nil

	-- accessed from functions, and metaArgs will hold the actual arguments. Nil

	-- arguments are memoized in nilArgs, and the metatable connects all of them

	-- arguments are memoized in nilArgs, and the metatable connects all of them

	-- together.

	-- together.

	--]]

	--]]

	local args, metaArgs, nilArgs, metatable = {}, {}, {}, {}

	local args, metaArgs, nilArgs, metatable = {}, {}, {}, {}

	setmetatable(args, metatable)

	setmetatable(args, metatable)

	local function mergeArgs(tables)

	local function mergeArgs(tables)

		--[[

		--[[

		-- Accepts multiple tables as input and merges their keys and values

		-- Accepts multiple tables as input and merges their keys and values

		-- into one table. If a value is already present it is not overwritten;

		-- into one table. If a value is already present it is not overwritten;

		-- tables listed earlier have precedence. We are also memoizing nil

		-- tables listed earlier have precedence. We are also memoizing nil

		-- values, which can be overwritten if they are 's' (soft).

		-- values, which can be overwritten if they are 's' (soft).

		--]]

		--]]

		for _, t in ipairs(tables) do

		for _, t in ipairs(tables) do

			for key, val in pairs(t) do

			for key, val in pairs(t) do

				if metaArgs[key] == nil and nilArgs[key] ~= 'h' then

				if metaArgs[key] == nil and nilArgs[key] ~= 'h' then

					local tidiedVal = tidyVal(key, val)

					local tidiedVal = tidyVal(key, val)

					if tidiedVal == nil then

					if tidiedVal == nil then

						nilArgs[key] = 's'

						nilArgs[key] = 's'

					else

					else

						metaArgs[key] = tidiedVal

						metaArgs[key] = tidiedVal

					end

					end

				end

				end

			end

			end

		end

		end

	end

	end

	--[[

	--[[

	-- Define metatable behaviour. Arguments are memoized in the metaArgs table,

	-- Define metatable behaviour. Arguments are memoized in the metaArgs table,

	-- and are only fetched from the argument tables once. Fetching arguments

	-- and are only fetched from the argument tables once. Fetching arguments

	-- from the argument tables is the most resource-intensive step in this

	-- from the argument tables is the most resource-intensive step in this

	-- module, so we try and avoid it where possible. For this reason, nil

	-- module, so we try and avoid it where possible. For this reason, nil

	-- arguments are also memoized, in the nilArgs table. Also, we keep a record

	-- arguments are also memoized, in the nilArgs table. Also, we keep a record

	-- in the metatable of when pairs and ipairs have been called, so we do not

	-- in the metatable of when pairs and ipairs have been called, so we do not

	-- run pairs and ipairs on the argument tables more than once. We also do

	-- run pairs and ipairs on the argument tables more than once. We also do

	-- not run ipairs on fargs and pargs if pairs has already been run, as all

	-- not run ipairs on fargs and pargs if pairs has already been run, as all

	-- the arguments will already have been copied over.

	-- the arguments will already have been copied over.

	--]]

	--]]

	metatable.__index = function (t, key)

	metatable.__index = function (t, key)

		--[[

		--[[

		-- Fetches an argument when the args table is indexed. First we check

		-- Fetches an argument when the args table is indexed. First we check

		-- to see if the value is memoized, and if not we try and fetch it from

		-- to see if the value is memoized, and if not we try and fetch it from

		-- the argument tables. When we check memoization, we need to check

		-- the argument tables. When we check memoization, we need to check

		-- metaArgs before nilArgs, as both can be non-nil at the same time.

		-- metaArgs before nilArgs, as both can be non-nil at the same time.

		-- If the argument is not present in metaArgs, we also check whether

		-- If the argument is not present in metaArgs, we also check whether

		-- pairs has been run yet. If pairs has already been run, we return nil.

		-- pairs has been run yet. If pairs has already been run, we return nil.

		-- This is because all the arguments will have already been copied into

		-- This is because all the arguments will have already been copied into

		-- metaArgs by the mergeArgs function, meaning that any other arguments

		-- metaArgs by the mergeArgs function, meaning that any other arguments

		-- must be nil.

		-- must be nil.

		--]]

		--]]

		if type(key) == 'string' then

		if type(key) == 'string' then

			key = options.translate[key]

			key = options.translate[key]

		end

		end

		local val = metaArgs[key]

		local val = metaArgs[key]

		if val ~= nil then

		if val ~= nil then

			return val

			return val

		elseif metatable.donePairs or nilArgs[key] then

		elseif metatable.donePairs or nilArgs[key] then

			return nil

			return nil

		end

		end

		for _, argTable in ipairs(argTables) do

		for _, argTable in ipairs(argTables) do

			local argTableVal = tidyVal(key, argTable[key])

			local argTableVal = tidyVal(key, argTable[key])

			if argTableVal ~= nil then

			if argTableVal ~= nil then

				metaArgs[key] = argTableVal

				metaArgs[key] = argTableVal

				return argTableVal

				return argTableVal

			end

			end

		end

		end

		nilArgs[key] = 'h'

		nilArgs[key] = 'h'

		return nil

		return nil

	end

	end

	metatable.__newindex = function (t, key, val)

	metatable.__newindex = function (t, key, val)

		-- This function is called when a module tries to add a new value to the

		-- This function is called when a module tries to add a new value to the

		-- args table, or tries to change an existing value.

		-- args table, or tries to change an existing value.

		if type(key) == 'string' then

		if type(key) == 'string' then

			key = options.translate[key]

			key = options.translate[key]

		end

		end

		if options.readOnly then

		if options.readOnly then

			error(

			error(

				'could not write to argument table key "'

				'could not write to argument table key "'

					.. tostring(key)

					.. tostring(key)

					.. '"; the table is read-only',

					.. '"; the table is read-only',

				2

				2

			)

			)

		elseif options.noOverwrite and args[key] ~= nil then

		elseif options.noOverwrite and args[key] ~= nil then

			error(

			error(

				'could not write to argument table key "'

				'could not write to argument table key "'

					.. tostring(key)

					.. tostring(key)

					.. '"; overwriting existing arguments is not permitted',

					.. '"; overwriting existing arguments is not permitted',

				2

				2

			)

			)

		elseif val == nil then

		elseif val == nil then

			--[[

			--[[

			-- If the argument is to be overwritten with nil, we need to erase

			-- If the argument is to be overwritten with nil, we need to erase

			-- the value in metaArgs, so that __index, __pairs and __ipairs do

			-- the value in metaArgs, so that __index, __pairs and __ipairs do

			-- not use a previous existing value, if present; and we also need

			-- not use a previous existing value, if present; and we also need

			-- to memoize the nil in nilArgs, so that the value isn't looked

			-- to memoize the nil in nilArgs, so that the value isn't looked

			-- up in the argument tables if it is accessed again.

			-- up in the argument tables if it is accessed again.

			--]]

			--]]

			metaArgs[key] = nil

			metaArgs[key] = nil

			nilArgs[key] = 'h'

			nilArgs[key] = 'h'

		else

		else

			metaArgs[key] = val

			metaArgs[key] = val

		end

		end

	end

	end

	local function translatenext(invariant)

	local function translatenext(invariant)

		local k, v = next(invariant.t, invariant.k)

		local k, v = next(invariant.t, invariant.k)

		invariant.k = k

		invariant.k = k

		if k == nil then

		if k == nil then

			return nil

			return nil

		elseif type(k) ~= 'string' or not options.backtranslate then

		elseif type(k) ~= 'string' or not options.backtranslate then

			return k, v

			return k, v

		else

		else

			local backtranslate = options.backtranslate[k]

			local backtranslate = options.backtranslate[k]

			if backtranslate == nil then

			if backtranslate == nil then

				-- Skip this one. This is a tail call, so this won't cause stack overflow

				-- Skip this one. This is a tail call, so this won't cause stack overflow

				return translatenext(invariant)

				return translatenext(invariant)

			else

			else

				return backtranslate, v

				return backtranslate, v

			end

			end

		end

		end

	end

	end

	metatable.__pairs = function ()

	metatable.__pairs = function ()

		-- Called when pairs is run on the args table.

		-- Called when pairs is run on the args table.

		if not metatable.donePairs then

		if not metatable.donePairs then

			mergeArgs(argTables)

			mergeArgs(argTables)

			metatable.donePairs = true

			metatable.donePairs = true

		end

		end

		return translatenext, { t = metaArgs }

		return translatenext, { t = metaArgs }

	end

	end

	local function inext(t, i)

	local function inext(t, i)

		-- This uses our __index metamethod

		-- This uses our __index metamethod

		local v = t[i + 1]

		local v = t[i + 1]

		if v ~= nil then

		if v ~= nil then

			return i + 1, v

			return i + 1, v

		end

		end

	end

	end

	metatable.__ipairs = function (t)

	metatable.__ipairs = function (t)

		-- Called when ipairs is run on the args table.

		-- Called when ipairs is run on the args table.

		return inext, t, 0

		return inext, t, 0

	end

	end

	return args

	return args

end

end

return arguments

return arguments