View source for Module:Arguments/doc/en-gb

<noinclude><!--
-->{{#ifeq:{{SUBPAGENAME}}|doc||{{Documentation subpage}}}}<!--
--><languages /><!--
--></noinclude>{{#switch:
| =
<includeonly>{{Languages|Module:Arguments/doc}}</includeonly>
<!-- Add categories where indicated at the bottom of this page and interwikis at Wikidata -->
{{Shared Template Warning|Module:Arguments|Module:Arguments}}
{{Used in system}}
{{Module rating|release}}
{{Module rating|protected}}

<span lang="en" dir="ltr" class="mw-content-ltr">This module provides easy processing of arguments passed from {{Magic word|#invoke|...|ext=Scribunto|code=1|nowrap=1}}.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It is a meta-module, meant for use by other modules, and should not be called from {{tlc|<nowiki>#invoke:...</nowiki>}} directly.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Its features include:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">Easy trimming of arguments and removal of blank arguments.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Arguments can be passed by both the current frame and by the parent frame at the same time.</span> <span lang="en" dir="ltr" class="mw-content-ltr">(More details below.)</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Arguments can be passed in directly from another Lua module or from the debug console.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Arguments are fetched as needed, which can help avoid (some) problems with {{xtag|ref}} tags.</span>
* Most features can be customised.

<div lang="en" dir="ltr" class="mw-content-ltr">
== Basic use ==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">First, you need to load the module.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It contains one function, named <code>getArgs</code>.</span>

<syntaxhighlight lang="lua">
local getArgs = require('Module:Arguments').getArgs
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">In the most basic scenario, you can use <code>getArgs</code> inside your main function.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The variable <code>args</code> is a table containing the arguments from {{tlc|<nowiki>#invoke:...</nowiki>}}.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">(See below for details.)</span>

<syntaxhighlight lang="lua">
local getArgs = require('Module:Arguments').getArgs
local p = {}

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

return p
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">However, the recommended practice is to use a function just for processing arguments from {{tlc|<nowiki>#invoke:...</nowiki>}}.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>

<syntaxhighlight lang="lua">
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
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
If you want multiple functions to use the arguments, and you also want them to be accessible from {{tlc|<nowiki>#invoke:...</nowiki>}}, you can use a wrapper function.
</div>

<syntaxhighlight lang="lua">
local getArgs = require('Module:Arguments').getArgs

local p = {}

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

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

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Options ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">The following options are available.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">They are explained in the sections below.</span>

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
	trim = false,
	removeBlanks = false,
	valueFunc = function (key, value)
		-- Code for processing one argument
	end,
	frameOnly = true,
	parentOnly = true,
	parentFirst = true,
	wrappers = {
		'Template:A wrapper template',
		'Template:Another wrapper template'
	},
	readOnly = true,
	noOverwrite = true
})
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Trimming and removing blanks ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Blank arguments often trip up coders new to converting MediaWiki templates to Lua.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In template syntax, blank strings and strings consisting only of whitespace are considered <code>false</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">However, in Lua, blank strings and strings consisting of whitespace are considered <code>true</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This means that if you don't pay attention to such arguments when you write your Lua modules, you might treat something as <code>true</code> that should actually be treated as <code>false</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">To avoid this, by default this module removes all blank arguments.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Similarly, whitespace can cause problems when dealing with positional arguments.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Although whitespace is trimmed for named arguments coming from {{tlc|<nowiki>#invoke:...</nowiki>}}, it is preserved for positional arguments.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Most of the time this additional whitespace is not desired, so this module trims it off by default.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">However, sometimes you want to use blank arguments as input, and sometimes you want to keep additional whitespace.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This can be necessary to convert some templates exactly as they were written.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If you want to do this, you can set the <code>trim</code> and <code>removeBlanks</code> arguments to <code>false</code>.</span>

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
	trim = false,
	removeBlanks = false
})
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Custom formatting of arguments ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">To do things like this you can use the <code>valueFunc</code> option.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The input to this option must be a function that takes two parameters, <code>key</code> and <code>value</code>, and returns a single value.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This value is what you will get when you access the field <code>key</code> in the <code>args</code> table.</span>

'''<span lang="en" dir="ltr" class="mw-content-ltr">Example 1:</span>'''
<span lang="en" dir="ltr" class="mw-content-ltr">This function preserves whitespace for the first positional argument, but trims all other arguments and removes all other blank arguments.</span>

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
	valueFunc = function (key, value)
		if key == 1 then
			return value
		elseif value then
			value = mw.text.trim(value)
			if value ~= '' then
				return value
			end
		end
		return nil
	end
})
</syntaxhighlight>

'''<span lang="en" dir="ltr" class="mw-content-ltr">Example 2:</span>'''
<span lang="en" dir="ltr" class="mw-content-ltr">This function removes blank arguments and converts all arguments to lower case, but doesn't trim whitespace from positional parameters.</span>

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
	valueFunc = function (key, value)
		if not value then
			return nil
		end
		value = mw.ustring.lower(value)
		if mw.ustring.find(value, '%S') then
			return value
		end
		return nil
	end
})
</syntaxhighlight>

{{Note|text=
<span lang="en" dir="ltr" class="mw-content-ltr">The above functions will fail if passed input that is not of type <code>string</code> or <code>nil</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This might be the case if you use the <code>getArgs</code> function in the main function of your module, and that function is called by another Lua module.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In this case, you will need to check the type of your input.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This is not a problem if you are using a function specially for arguments from {{tlc|<nowiki>#invoke:...</nowiki>}} (i.e. you have <code>p.main</code> and <code>p._main</code> functions, or something similar).</span>
}}

{{Collapse top|1=<span lang="en" dir="ltr" class="mw-content-ltr">Examples 1 and 2 with type checking</span>}}
<div lang="en" dir="ltr" class="mw-content-ltr">
Example 1:
</div>
<syntaxhighlight lang="lua">
local args = getArgs(frame, {
	valueFunc = function (key, value)
		if key == 1 then
			return value
		elseif type(value) == 'string' then
			value = mw.text.trim(value)
			if value ~= '' then
				return value
			else
				return nil
			end
		else
			return value
		end
	end
})
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
Example 2:
</div>
<syntaxhighlight lang="lua">
local args = getArgs(frame, {
	valueFunc = function (key, value)
		if type(value) == 'string' then
			value = mw.ustring.lower(value)
			if mw.ustring.find(value, '%S') then
				return value
			else
				return nil
			end
		else
			return value
		end
	end
})
</syntaxhighlight>
{{Collapse bottom}}

<div lang="en" dir="ltr" class="mw-content-ltr">
Also, please note that the <code>valueFunc</code> function is called more or less every time an argument is requested from the <code>args</code> table, so if you care about performance you should make sure you aren't doing anything inefficient with your code.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Frames and parent frames ===
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">Arguments in the <code>args</code> table can be passed from the current frame or from its parent frame at the same time.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">To understand what this means, it is easiest to give an example.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Let's say that we have a module called <code>Module:ExampleArgs</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This module prints the first two positional arguments that it is passed.</span>

{{Collapse top|1=<span lang="en" dir="ltr" class="mw-content-ltr">Module:ExampleArgs code</span>}}
<syntaxhighlight lang="lua">
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 ''
	return first .. ' ' .. second
end

return p
</syntaxhighlight>
{{Collapse bottom}}

<span lang="en" dir="ltr" class="mw-content-ltr"><code>Module:ExampleArgs</code> is then called by <code>Template:ExampleArgs</code>, which contains the code <code><nowiki>{{#invoke:ExampleArgs|main|firstInvokeArg}}</nowiki></code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This produces the result "firstInvokeArg".</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
Now if we were to call <code>Template:ExampleArgs</code>, the following would happen:
</div>

{{(!}} class="wikitable" style="width: 50em; max-width: 100%;"
{{!}}-
! style="width: 60%;" {{!}} <span lang="en" dir="ltr" class="mw-content-ltr">Code</span>
! style="width: 40%;" {{!}} <span lang="en" dir="ltr" class="mw-content-ltr">Result</span>
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
{{!}} firstInvokeArg secondTemplateArg
{{!)}}

<span lang="en" dir="ltr" class="mw-content-ltr">There are three options you can set to change this behaviour: <code>frameOnly</code>, <code>parentOnly</code> and <code>parentFirst</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If you set <code>frameOnly</code> then only arguments passed from the current frame will be accepted; if you set <code>parentOnly</code> then only arguments passed from the parent frame will be accepted; and if you set <code>parentFirst</code> then arguments will be passed from both the current and parent frames, but the parent frame will have priority over the current frame.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Here are the results in terms of <code>Template:ExampleArgs</code>:</span>

<dl>
<dt><code>frameOnly</code></dt>
<dd>
{{(!}} class="wikitable" style="width: 50em; max-width: 100%;"
{{!}}-
! style="width: 60%;" {{!}} <span lang="en" dir="ltr" class="mw-content-ltr">Code</span>
! style="width: 40%;" {{!}} <span lang="en" dir="ltr" class="mw-content-ltr">Result</span>
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
{{!}} firstInvokeArg
{{!)}}
</dd>

<dt><code>parentOnly</code></dt>
<dd>
{{(!}} class="wikitable" style="width: 50em; max-width: 100%;"
{{!}}-
! style="width: 60%;" {{!}} <span lang="en" dir="ltr" class="mw-content-ltr">Code</span>
! style="width: 40%;" {{!}} <span lang="en" dir="ltr" class="mw-content-ltr">Result</span>
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs}}</nowiki></code>
{{!}}
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
{{!}} firstTemplateArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
{{!}} firstTemplateArg secondTemplateArg
{{!)}}
</dd>

<dt><code>parentFirst</code></dt>
<dd>
{{(!}} class="wikitable" style="width: 50em; max-width: 100%;"
{{!}}-
! style="width: 60%;" {{!}} <span lang="en" dir="ltr" class="mw-content-ltr">Code</span>
! style="width: 40%;" {{!}} <span lang="en" dir="ltr" class="mw-content-ltr">Result</span>
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
{{!}} firstTemplateArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
{{!}} firstTemplateArg secondTemplateArg
{{!)}}
</dd>
</dl>

{{Note|text=
{{Ordered list
|1=
<span lang="en" dir="ltr" class="mw-content-ltr">If you set both the <code>frameOnly</code> and <code>parentOnly</code> options, the module won't fetch any arguments at all from {{tlc|<nowiki>#invoke:...</nowiki>}}.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This is probably not what you want.</span>
|2=
<span lang="en" dir="ltr" class="mw-content-ltr">In some situations a parent frame may not be available, e.g. if <code>getArgs</code> is passed the parent frame rather than the current frame.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In this case, only the frame arguments will be used (unless <code>parentOnly</code> is set, in which case no arguments will be used) and the <code>parentFirst</code> and <code>frameOnly</code> options will have no effect.</span>
}}
}}

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Wrappers ===
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">The <code>wrappers</code> option is used to specify a limited number of templates as ''wrapper templates'', that is, templates whose only purpose is to call a module.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If the module detects that it is being called from a wrapper template, it will only check for arguments in the parent frame; otherwise it will only check for arguments in the frame passed to <code>getArgs</code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This allows modules to be called by either {{tlc|<nowiki>#invoke:...</nowiki>}} or through a wrapper template without the loss of performance associated with having to check both the frame and the parent frame for each argument lookup.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">For example, the only content of {{tlx|Navbox}} (excluding content in {{tag|noinclude}} tags) is <code><nowiki>{{#invoke:Navbox|navbox}}</nowiki></code>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">There is no point in checking the arguments passed directly to the {{tlc|<nowiki>#invoke:...</nowiki>}} statement for this template, as no arguments will ever be specified there.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">We can avoid checking arguments passed to {{tlc|<nowiki>#invoke:...</nowiki>}} by using the <code>parentOnly</code> option, but if we do this then {{tlc|<nowiki>#invoke:...</nowiki>}} will not work from other pages either.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If this were the case, then {{tmpl|0={{para|text|$1}}|Some text}} in the code {{tmpl|0={{tlc|<nowiki>#invoke:Navbox</nowiki>|navbox|3=text=$1}}|Some text}} would be ignored completely, no matter what page it was used from.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">By using the <code>wrappers</code> option to specify [[Template:Navbox]] as a wrapper, we can make {{tmpl|0={{tlc|<nowiki>#invoke:Navbox</nowiki>|main|3=text=$1}}|Some text}} work from most pages, while still not requiring that the module check for arguments on the [[Template:Navbox]] page itself.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
Wrappers can be specified either as a string, or as an array of strings.
</div>

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
	wrappers = 'Template:Wrapper template'
})
</syntaxhighlight>

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
	wrappers = {
		'Template:Wrapper 1',
		'Template:Wrapper 2',
		-- Any number of wrapper templates can be added here.
	}
})
</syntaxhighlight>

{{Note|text=
{{Ordered list
|1=
<span lang="en" dir="ltr" class="mw-content-ltr">The module will automatically detect if it is being called from a wrapper template's <code>/sandbox</code> subpage, so there is no need to specify sandbox pages explicitly.</span>
|2=
<span lang="en" dir="ltr" class="mw-content-ltr">The <code>wrappers</code> option effectively changes the default of the <code>frameOnly</code> and <code>parentOnly</code> options.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If, for example, <code>parentOnly</code> were explicitly set to <code>false</code> with <code>wrappers</code> set, calls via wrapper templates would result in both frame and parent arguments being loaded, though calls not via wrapper templates would result in only frame arguments being loaded.</span>
|3=
<span lang="en" dir="ltr" class="mw-content-ltr">If the <code>wrappers</code> option is set and no parent frame is available, the module will always get the arguments from the frame passed to <code>getArgs</code>.</span>
}}
}}

=== Writing to the <code>args</code> table ===
<span lang="en" dir="ltr" class="mw-content-ltr">Sometimes it can be useful to write new values to the <code>args</code> table.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This is possible with the default settings of this module.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">(However, bear in mind that it is usually better coding style to create a new table with your new values and copy arguments from the <code>args</code> table as needed.)</span>

<syntaxhighlight lang="lua">
args.foo = 'some value'
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">It is possible to alter this behaviour with the <code>readOnly</code> and <code>noOverwrite</code> options.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If <code>readOnly</code> is set then it is not possible to write any values to the <code>args</code> table at all.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If <code>noOverwrite</code> is set, then it is possible to add new values to the table, but it is not possible to add a value if it would overwrite any arguments that are passed from {{tlc|<nowiki>#invoke:...</nowiki>}}.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Ref tags ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">This module uses [[mw:Special:MyLanguage/Extension:Scribunto/Lua reference manual#Metatables|metatables]] to fetch arguments from {{tlc|<nowiki>#invoke:...</nowiki>}}.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This allows access to both the frame arguments and the parent frame arguments without using the <code>pairs()</code> function.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This can help if your module might be passed {{xtag|ref}} tags as input.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">As soon as {{xtag|ref}} tags are accessed from Lua, they are processed by the MediaWiki software and the reference will appear in the reference list at the bottom of the article.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If your module proceeds to omit the reference tag from the output, you will end up with a phantom reference - a reference that appears in the reference list, but no number that links to it.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This has been a problem with modules that use <code>pairs()</code> to detect whether to use the arguments from the frame or the parent frame, as those modules automatically process every available argument.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">This module solves this problem by allowing access to both frame and parent frame arguments, while still only fetching those arguments when it is necessary.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The problem will still occur if you use <code>pairs(args)</code> elsewhere in your module, however.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Known limitations ===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">The use of metatables also has its downsides.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Most of the normal Lua table tools won't work properly on the <code>args</code> table, including the <code>#</code> operator, the <code>next()</code> function, and the functions in the <code>table</code> library.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If using these is important for your module, you should use your own argument processing function instead of this module.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Tests ==
</div>
{{ModuleQuality}}
<includeonly>{{Sandbox other||
<!-- Categories below this line; interwikis at Wikidata -->
[[Category:Lua metamodules{{#translation:}}]]
}}</includeonly><noinclude>
[[Category:Module documentation pages{{#translation:}}]]
</noinclude>
| #default=
  {{#invoke:Template translation|renderTranslatedTemplate|template=Module:Arguments/doc|noshift=1|uselang={{int:lang}}}}
}}