Module:Arguments/doc

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

Basic use

First, you need to load the module. It contains one function, named getArgs.

local getArgs = require('Module:Arguments').getArgs

In the most basic scenario, you can use getArgs inside your main function. The variable args is a table containing the arguments from #invoke. (See below for details.)

local getArgs = require('Module:Arguments').getArgs
local p = {}

function p.main(frame)
	local args = getArgs(frame)
	-- Main module code goes here.
end

return p

However, the recommended practice is to use a function just for processing arguments from #invoke. This means that if someone calls your module from another Lua module you don't have to have a frame object available, which improves performance.

local getArgs = require('Module:Arguments').getArgs
local p = {}

function p.main(frame)
	local args = getArgs(frame)
	return p._main(args)
end

function p._main(args)
	-- Main module code goes here.
end

return p

If you want multiple functions to use the arguments, and you also want them to be accessible from #invoke, you can use a wrapper function.

local getArgs = require('Module:Arguments').getArgs

local function makeInvokeFunc(funcName)
	return function (frame)
		local args = getArgs(frame)
		return p[funcName](args)
	end
end

local p = {}

p.func1 = makeInvokeFunc('_func1')

function p._func1(args)
	-- Code for the first function goes here.
end

p.func2 = makeInvokeFunc('_func2')

function p._func2(args)
	-- Code for the second function goes here.
end

return p

Options

The following options are available. They are explained in the sections below.

local args = getArgs(frame, {
	trim = false,
	removeBlanks = false,
	valueFunc = function(key, val)
		-- Code for processing one argument
	end,
	parentFirst = true,
	readOnly = true,
	noOverwrite = true
})

Trimming and removing blanks

Blank arguments often trip up coders new to converting MediaWiki templates to Lua. In template syntax, blank strings and strings consisting only of whitespace are considered false. However, in Lua, blank strings and strings consisting of whitespace are considered true. This means that if you don't pay attention to such arguments when you write your Lua modules, you might treat something as true that should actually be treated as false. To avoid this, by default this module removes all blank arguments.

Similarly, whitespace can cause problems when dealing with positional arguments. Although whitespace is trimmed for named arguments coming from #invoke, it is preserved for positional arguments. Most of the time this additional whitespace is not desired, so this module trims it off by default.

However, sometimes you want to use blank arguments as input, and sometimes you want to keep additional whitespace. This can be necessary to convert some templates exactly as they were written. If you want to do this, you can set the trim and removeBlanks arguments to false.

local args = getArgs(frame, {
	trim = false,
	removeBlanks = false
})

Custom trimming and blank removal

Sometimes you want to remove some blank arguments but not others, or perhaps you might want to put all of the positional arguments in lower case. To do things like this you can use the valueFunc option. The input to this option must be a function that takes two parameters, key value, and returns the value of the argument. This function is called every time an argument is requested from the args table.

Example 1: this function preserves whitespace for the first positional argument, but trims all other arguments and removes all other blank arguments.

local args = getArgs(frame, {
	valueFunc = function(key, value)
		if key == 1 then
			return value
		else
			value = mw.text.trim(value)
			if value ~= '' then
				return value
			end
		end
	end
})

Example 2: this function removes blank arguments and converts all arguments to lower case, but doesn't trim whitespace from positional parameters.

local args = getArgs(frame, {
	valueFunc = function(key, value)
		value = mw.ustring.lower(value)
		if mw.ustring.find(value, '%S') then
			return value
		end
	end
})

Note: if you are using the getArgs function in the main function of your module, be aware that if it is called from another Lua module then value might not always be a string. This is not a problem if you are using a function specially for arguments from #invoke (i.e. you have p.main and p._main functions, or something similar).

Frames and parent frames

Arguments in the args table can be passed from the current frame or from its parent frame at the same time. To understand what this means, it is easiest to give an example. Let's say that we have a module called Module:ExampleArgs. This module prints the first three positional arguments that it is passed.

local getArgs = require('Module:Arguments').getArgs
local p = {}

function p.main(frame)
	local args = getArgs(frame)
	return p._main(args)
end

function p._main(args)
	local first = args[1] or ''
	local second = args[2] or ''
	local third = args[3] or ''
	return first .. ' ' .. second .. ' ' .. third
end

return p

Module:ExampleArgs is then called by Template:ExampleArgs, which contains the code {{#invoke:ExampleArgs|main|firstArg}}. This produces the result "firstArg".

Now if we were to call Template:ExampleArgs, the following would happen:

1. {{ExampleArgs}} → firstArg
2. {{ExampleArgs|myFirstArg}} → firstArg
3. {{ExampleArgs|myFirstArg|mySecondArg|myThirdArg}} → firstArg mySecondArg myThirdArg

If you want the value from the parent frame to have precedence over the value from the current frame (i.e. if you would like "myFirstArg" instead of "firstArg" in the second example above), you can do so with the parentFirst option.

local args = getArgs(frame, {
	parentFirst = true
})