Module:Params/doc

Among the possibilities that the module offers there is that of performing a series of actions after novel arguments have been concatenated to a template's incoming parameters. As this makes it necessary to keep the argument slots clean from interferences, instead of named arguments in order to specify options this module uses piping functions (i.e. functions that expect to be piped instead of returning to the caller), or modifiers. This creates a syntax similar to the following example:

{{#invoke:params|[modifier]|[...]|[modifier]|[...]|function|[...]}}

For instance, as the name suggests, the list function lists the parameters wherewith a template was called. By default it does not add delimiters, but returns an indistinct blob of text in which keys and values are sticked to each other. However, by using the setting modifier, we are able to declare a key-value delimiter (p) and an iteration delimiter (i). And so, if we imagined a template named {{Example template}} containing the following wikitext,

{{#invoke:params|setting|i/p|<br />|: |list}}

and such template were called with the following arguments,

the following result would be produced:

Owlman: A giant owl-like creature
Beast of Bodmin: A large feline inhabiting Bodmin Moor
Morgawr: A sea serpent

We can also do more sophisticated things; for instance, by exploiting the possibility to set a header (h) and a footer (f), we can transform the previous code into a generator of definition lists,

{{#invoke:params|setting|h/p/i/f|<dl><dt>|</dt><dd>|</dd><dt>|</dd></dl>|list}}

thus yielding:

Beast of Bodmin

A large feline inhabiting Bodmin Moor

Morgawr

A sea serpent

Owlman

A giant owl-like creature

By placing the with_name_matching modifier before the list function we would be able to filter some parameters out – such as, for instance, all parameter names that do not end with an “n”:

{{#invoke:params|with_name_matching|n$|setting|h/p/i/f|<dl><dt>|</dt><dd>|</dd><dt>|</dd></dl>|list}}

Thus, the previous code would produce:

Beast of Bodmin

A large feline inhabiting Bodmin Moor

Owlman

A giant owl-like creature

This mechanism has the intrinsic advantage that it allows to concatenate infinite modifiers. And so, in order to get the accurate result that we want to obtain we could write:

{{#invoke:params|non-sequential|with_name_matching|^B|with_name_matching|n$|with_value_matching|feline|setting|h/p/i/f|<dl><dt>|</dt><dd>|</dd><dt>|</dd></dl>|list}}

The two modifiers sequential and non-sequential refer to a technical jargon used in wikitext: given a parameter list, the subgroup of sequential parameters is constituted by the largest group of consecutive numerical parameters starting from |1= – this is known as the parameters' “sequence”. A parameter list that does not have a first parameter specified does not possess a sequence.

Here follows the list of functions. All modifiers are applicable to all of them (see § Modifiers).

Template:Unstructured infobox

Brief

Count the number of parameters wherewith a template was called

Syntax

{{#invoke:params|count}}

This function does not take arguments.

Template:Unstructured infobox

Brief

Prepend numerical arguments to the current parameters or impose non-numerical arguments, then propagate everything to a custom template

Syntax

{{#invoke:params|concat_and_call|template name|[prepend 1]|[prepend 2]|[...]|[prepend n]|[named item 1=value 1]|[...]|[named item n=value n]|[...]}}

For example, if our {{Example template}} had the following code,

{{#invoke:params|concat_and_call|foo bar|elbow|earth|room|7=classy|hello=not today}}

and were called with,

the following call to the {{Foo bar}} template would be performed:

If no other argument besides the template name are provided this function simply echoes the current parameters to another template.

  Note: All arguments passed to this function except the template name are not trimmed of their leading and trailing spaces. The concat_and_call function name itself, however, will be trimmed of its surrounding spaces.

Template:Unstructured infobox

Brief

Prepend numerical arguments to the current parameters, or impose non-numerical arguments; then propagate everything to a custom module

Syntax

{{#invoke:params|concat_and_invoke|module name|function name|[prepend 1]|[prepend 2]|[...]|[prepend n]|[named item 1=value 1]|[...]|[named item n=value n]|[...]}}

Exactly like concat_and_call, but invokes a module instead of calling a template.

  Note: All arguments passed to this function except the module name and the function name are not trimmed of their leading and trailing spaces. The concat_and_invoke function name itself, however, will be trimmed of its surrounding spaces.

Template:Unstructured infobox

Brief

Get the value of a single parameter

Syntax

{{#invoke:params|value_of|parameter name}}

Without modifiers this function is similar to writing {{{parameter name|}}}. With modifiers, however, it allows to reach parameters that would be unreachable without knowing their number in advance. For instance, writing

{{#invoke:params|cutting|-2|0|value_of|1}}

will expand to the value of the second-last sequential parameter, independently of how many parameters the template was called with. If no matching parameter is found this function expands to nothing. A header (h), a footer (f), and a fallback text (n) can be declared via the setting modifier – the strings assigned to the key-value pair delimiter (p) and the iteration delimiter (i) will be ignored.

Template:Unstructured infobox

Brief

List the template parameters (both their names and their values)

Syntax

{{#invoke:params|list}}

This function does not take arguments.

If the setting modifier was not placed earlier, this function will not add delimiters, but will return an indistinct blob of text in which keys and values are sticked to each other. A header (h), a key-value pair delimiter (p), an iteration delimiter (i), a footer (f), and a fallback text (n) can be declared via setting.

For example, the following code

{{#invoke:params|setting|h/i/p/f/n|'''Parameters passed:''' |); | (|)|'''No parameters were passed'''|list}}

will generate an output similar to the following.

Parameters passed: Owlman (A giant owl-like creature); Beast of Bodmin (A large feline inhabiting Bodmin Moor); Morgawr (A sea serpent)

Template:Unstructured infobox

Brief

List the values of the incoming parameters

Syntax

{{#invoke:params|list_values}}

This function does not take arguments.

The sequential modifier normally accompanies this function. If the setting modifier was not placed earlier, this function will not add delimiters, but will return an indistinct blob of text in which values are sticked to each other. A header (h), an iteration delimiter (i), a footer (f), and a fallback text (n) can be declared via setting – the string assigned to the key-value pair delimiter (p) will be ignored.

For example, the following code

{{#invoke:params|setting|h/i/p/f/n|'''Parameters passed:''' |); | (|)|'''No parameters were passed'''|list}}

will generate an output similar to the following.

Values of parameters passed: A giant owl-like creature; A large feline inhabiting Bodmin Moor; A sea serpent.

Template:Unstructured infobox

Brief

For each parameter passed to the caller template, call a custom template with at least two parameters (key and value)

Syntax

{{#invoke:params|call_for_each|template name|[append 1]|[append 2]|[...]|[append n]|[named param 1=value 1]|[...]|[named param n=value n]|[...] }}

All unnamed parameters following the template name will be placed after the key-value pair. Named parameters will be passed verbatim. A header (h), an iteration delimiter (i), a footer (f), and a fallback text (n) can be declared via the setting modifier – the string assigned to the key-value pair delimiter (p) will be ignored.

Calling a template for each key-value pair with

{{#invoke:params|sequential|call_for_each|foobar}}

will be more efficient than writing

{{#invoke:params|sequential|for_each|{{foobar|$#|$@}}}}

Furthermore, in the second example the $# and $@ tokens will be expanded after the template has been called – in most cases this will make no difference, however there are several situations where it will lead to nonsensical results.

  Note: All arguments passed to this function except the template name are not trimmed of their leading and trailing spaces. The call_for_each function name itself, however, will be trimmed of its surrounding spaces.

Template:Unstructured infobox

Brief

For each parameter passed to the caller template, invoke a custom module function with at least two arguments (key and value)

Syntax

{{#invoke:params|invoke_for_each|module name|module function|[append 1]|[append 2]|[...]|[append n]|[named param 1=value 1]|[...]|[named param n=value n]|[...]}}

Exactly like call_for_each, but invokes a module instead of calling a template.

Invoking a module function for each key-value pair with

{{#invoke:params|sequential|invoke_for_each|foobar|main}}

will be more efficient than writing

{{#invoke:params|sequential|for_each|{{#invoke:foobar|main|$#|$@}}}}

Furthermore, in the second example the $# and $@ tokens will be expanded after the module function has been called – in most cases this will make no difference, however there are several situations where it will lead to nonsensical results.

  Note: All arguments passed to this function except the module name and the function name are not trimmed of their leading and trailing spaces. The invoke_for_each function name itself, however, will be trimmed of its surrounding spaces.

Template:Unstructured infobox

Brief

For each parameter passed to the caller template, call a magic word with at least two arguments (key and value)

Syntax

{{#invoke:params|magic_for_each|parser function|[append 1]|[append 2]|[...]|[append n]|[named param 1=value 1]|[...]|[named param n=value n]|[...]}}

Exactly like call_for_each, but calls a parser function instead of a template.

  Note: All arguments passed to this function except the magic word are not trimmed of their leading and trailing spaces. The magic_for_each function name itself, however, will be trimmed of its surrounding spaces.

Template:Unstructured infobox

Brief

For each parameter passed to the caller template, call a custom template with at least one parameter (i.e. the parameter's value)

Syntax

{{#invoke:params|call_for_each_value|template name|[append 1]|[append 2]|[...]|[append n]|[named param 1=value 1]|[...]|[named param n=value n]|[...]}}

The sequential modifier normally accompanies this function. All unnamed parameters following the template name will be appended after the value parameter. Named parameters will be passed verbatim. A header (h), an iteration delimiter (i), a footer (f), and a fallback text (n) can be declared via the setting modifier – the string assigned to the key-value pair delimiter (p) will be ignored.

For example, calling {{tl}} with each parameter can be done by writing

{{#invoke:params|sequential|setting|i|, |call_for_each_value|tl}}

This will be more efficient than writing

{{#invoke:params|sequential|setting|i|, |for_each|{{tl|$@}}}}

Furthermore, in the second example the $@ token will be expanded after the {{tl}} template has been called – in most cases this will make no difference, however there are several situations where it will lead to nonsensical results.

  Note: All arguments passed to this function except the template name are not trimmed of their leading and trailing spaces. The call_for_each_value function name itself, however, will be trimmed of its surrounding spaces.

Template:Unstructured infobox

Brief

For each parameter passed to the caller template, invoke a custom module function with at least one argument (i.e. the parameter's value)

Syntax

{{#invoke:params|invoke_for_each_value|module name|module function|[append 1]|[append 2]|[...]|[append n]|[named param 1=value 1]|[...]|[named param n=value n]|[...]}}

Exactly like call_for_each_value, but invokes a module instead of calling a template.

Invoking a module function for each value with

{{#invoke:params|sequential|invoke_for_each_value|foobar|main}}

will be more efficient than writing

{{#invoke:params|sequential|for_each|{{#invoke:foobar|main|$@}}}}

Furthermore, in the second example the $@ token will be expanded after the module function has been invoked – in most cases this will make no difference, however there are several situations where it will lead to nonsensical results.

  Note: All arguments passed to this function except the module name and the function name are not trimmed of their leading and trailing spaces. The invoke_for_each_value function name itself, however, will be trimmed of its surrounding spaces.

Template:Unstructured infobox

Brief

For each parameter passed to the caller template, call a magic word with at least one argument (i.e. the parameter's value)

Syntax

{{#invoke:params|magic_for_each_value|parser function|[append 1]|[append 2]|[...]|[append n]|[named param 1=value 1]|[...]|[named param n=value n]|[...]}}

Exactly like call_for_each_value, but calls a parser function instead of a template.

For example, if a template had the following code,

{{#invoke:params|sequential|setting|ih|&preloadparams%5b%5d{{=}}|magic_for_each_value|urlencode|QUERY}}

and were transcluded as {{example template|hello world|àèìòù|foo bar}}, the {{urlencode:...|QUERY}} parser function would be called for each incoming parameter as first argument and with QUERY as second argument, and finally the returned text would be prefixed with &preloadparams%5b%5d=. This would generate,

&preloadparams%5b%5d=hello+world&preloadparams%5b%5d=%C3%A0%C3%A8%C3%AC%C3%B2%C3%B9&preloadparams%5b%5d=foo+bar

which can be used to allow the creation of pages with preloaded text and parameters.

  Note: All arguments passed to this function except the magic word are not trimmed of their leading and trailing spaces. The magic_for_each_value function name itself, however, will be trimmed of its surrounding spaces.

Template:Unstructured infobox

Brief

For each parameter passed to the caller template, expand all occurrences of $# and $@ within a given text as key and value respectively

Syntax

{{#invoke:params|for_each|wikitext}}

Example:

{{#invoke:params|for_each|Arg name: $#, Arg value: $@}}

The text returned by this function is not expanded further (currently this module does not offer an expand_for_each function). If you need wikitext expansion, use concat_and_call to propagate the incoming parameters altogether to the {{for nowiki}} template. Example:

{{#invoke:params|sequential|concat_and_call|for nowiki|[separator]|<nowiki>{{{i}}} is {{urlencode:{{{1}}}|QUERY}}</nowiki>}}

  Note: The argument passed to this function is not trimmed of its leading and trailing spaces. The for_each function name itself, however, will be trimmed of its surrounding spaces.

The following are modifiers, i.e. functions that expect to be piped instead of returning to the caller. Each of them can be followed by either another modifier or a non-piping function.

Template:Unstructured infobox

Brief

Reduce the parameter list to the subgroup of consecutive parameters that follow |1=

Syntax

{{#invoke:params|sequential|pipe function name}}

Example:

{{#invoke:params|sequential|count}}

This modifier does not take arguments besides the name of the function that will follow.

Using sequential together with non-sequential will generate an error.

  Note: Like non-sequential, the sequential modifier permanently marks a query. For instance, writing {{#invoke:params|sequential|with_name_not_matching|1|...}} will first mark the query as “sequential”, then will discard the first element from the sequence (leaving all the others intact). And so, no matter how many other parameters will be present, nothing will be shown.

Template:Unstructured infobox

Brief

Reduce the parameter list by subtracting the subgroup of consecutive parameters that follow |1=

Syntax

{{#invoke:params|non-sequential|pipe function name}}

Example:

{{#invoke:params|non-sequential|setting|ih/p|{{!}}|{{=}}|list}}

This modifier does not take arguments besides the name of the function that will follow.

Using non-sequential together with sequential will generate an error.

  Note: Like sequential, the non-sequential modifier permanently marks a query, and no matter what transformations will follow (see squeezing) the parameters' “sequence” will not be shown.

Template:Unstructured infobox

Brief

Set internal variables

Syntax

{{#invoke:params|setting|directives|...|pipe function name}}

This modifier allows to set some internal variables that will be used by other functions. The function takes a variable number of arguments, relying on the first argument to understand how many other arguments to read. It will be best introduced by a few examples:

• {{#invoke:params|setting|i|{{!}}|list_values}}

  ↳ Set the value of iteration delimiter to |, then list all values

• {{#invoke:params|setting|ih|{{!}}|list_values}}

  ↳ Set the value of both header text and iteration delimiter to |, then list all values

• {{#invoke:params|setting|ih/p|{{!}}|{{=}}|list}}

  ↳ Set the value of both header text and iteration delimiter to |, set key-value pair delimiter to =, then list all parameters

• {{#invoke:params|setting|ih/p/n|{{!}}|{{=}}|No parameters were passed|list}}

  ↳ Set the value of both header text and iteration delimiter to |, set key-value pair delimiter to =, set fallback text to No parameters were passed, then list all parameters

The first argument is a slash-separated list of lists of slots to assign; one slot is referred by exactly one character and each slash-separated list of slots maps exactly one argument. A slot indicates which internal variable to set. If more than one slot is aggregated within the same slash-separated list the same text will be assigned to more than one variable.

The slots available are the following:

In theory, instead of assigning different slots at once (i.e. {{...|setting|ih/p|{{!}}|{{=}}|...}}), it is possible to write separate invocations of setting for each variable, as in {{...|setting|ih|{{!}}|setting|p|{{=}}...}}. This method will be slightly less efficient.

Template:Unstructured infobox

Brief

Rearrange all parameters that have numerical names and form a compact sequence starting from 1, keeping the same order

Syntax

{{#invoke:params|squeezing|pipe function name}}

Example:

{{#invoke:params|squeezing|sequential|setting|i/p|<br />|: |list}}

This modifier does not take arguments besides the name of the function that will follow.

The following three concatenations will lead to the same result of discarding all parameters with numerical names:

1. {{...|non-sequential|squeezing|...}}
2. {{...|squeezing|non-sequential|...}}
3. {{...|with_name_not_matching|^%-?%d+$|...}}

Template:Unstructured infobox

Brief

Remove zero or more parameters from the beginning and the end of the parameter list

Syntax

{{#invoke:params|cutting|left trim|right trim|pipe function name}}

The first argument indicates how many sequential parameters must be removed from the beginning of the parameter list, the second argument indicates how many sequential parameters must be removed from the end of the parameter list. If any of the two arguments is a negative number its absolute value indicates what must be left on the other side – i.e. {{#invoke:params|cutting|-3|0|list}} indicates that the last three arguments must not be discarded.

Example:

{{#invoke:params|cutting|0|2|sequential|call_for_each_value|example template}}

In some cases it might be necessary to concatenate more than one invocation of the cutting function. For instance, notice the |cutting|1|0|cutting|-1|0 code in the following imaginary {{Foobar see also}} template in order to properly show the “and” conjunction and possibly an Oxford comma when more than two page names are provided:

{{Hatnote|{{{altphrase|Foobar see also}}}: {{#if:{{{1|}}}
		|[[{{{1}}}]]{{#invoke:params|sequential|cutting|1|1|for_each|, [[$@]]}}{{#invoke:params|sequential|cutting|1|0|cutting|-1|0|for_each|{{#if:{{{3|}}}|,}} and [[$@]]}}
		|{{Error|{{tl|Foobar see also}} requires at least one page name}}
	}}
}}

  Suggestion: Although {{#invoke:params|cutting|-1|1|...}} de facto gets rid of all sequential parameters, it is clearer and more idiomatic to write {{#invoke:params|non-sequential|...}} to obtain the same effect. Writing {{#invoke:params|sequential|cutting|-1|1|...}} will leave zero arguments to show.

Template:Unstructured infobox

Brief

Discard all parameters whose name does not match the given pattern

Syntax

{{#invoke:params|with_name_matching|pattern|pipe function name}}

Internally this modifier uses Lua's string.find() function to find whether parameter names match against a given pattern. For the pattern argument (|1=) please use the same syntax of Lua patterns.

Example:

{{#invoke:params|with_name_matching|n$|setting|h/p/i/f|<dl><dt>|</dt><dd>|</dd><dt>|</dd></dl>|list}}

  Note: The argument passed to this function is not trimmed of its leading and trailing spaces. The with_name_matching function name itself, however, will be trimmed of its surrounding spaces.

Template:Unstructured infobox

Brief

Discard all parameters whose name matches the given pattern

Syntax

{{#invoke:params|with_name_not_matching|pattern|pipe function name}}

Internally this modifier uses Lua's string.find() function to find whether parameter names match against a given pattern. For the pattern argument (|1=) please use the same syntax of Lua patterns.

Example:

{{#invoke:params|with_name_not_matching|n$|count}}

It is possible to use this function to check for unknown parameters:

{{#ifexpr:{{#invoke:params|with_name_not_matching|^hello$|with_name_not_matching|^wind$|count}} > 0
	|{{#invoke:Error|error|Error: The only parameters accepted are {{para|hello}} and {{para|wind}}.}}
	|Everything is good: do something
}}

For simple cases like this, however, specialized modules are available; you might want to have a look at:

• {{#invoke:Check for unknown parameters|check}}
• {{#invoke:Check for deprecated parameters|check}}
• {{#invoke:Check for clobbered parameters|check}}
• {{#invoke:Parameter validation|function}}
• {{#invoke:TemplatePar|function}}

  Note: The argument passed to this function is not trimmed of its leading and trailing spaces. The with_name_not_matching function name itself, however, will be trimmed of its surrounding spaces.

Template:Unstructured infobox

Brief

Discard all parameters whose value does not match the given pattern

Syntax

{{#invoke:params|with_value_matching|pattern|pipe function name}}

Internally this modifier uses Lua's string.find() function to find whether parameter values match against a given pattern. For the pattern argument (|1=) please use the same syntax of Lua patterns.

Example:

{{#invoke:params|with_value_matching|banana|count}}

  Note: The argument passed to this function is not trimmed of its leading and trailing spaces. The with_value_matching function name itself, however, will be trimmed of its surrounding spaces.

Template:Unstructured infobox

Brief

Discard all parameters whose value matches the given pattern

Syntax

{{#invoke:params|with_value_not_matching|pattern|pipe function name}}

Internally this modifier uses Lua's string.find() function to find whether parameter values match against a given pattern. For the pattern argument (|1=) please use the same syntax of Lua patterns.

For instance, before calling list, the following code will get rid of all blank parameters (i.e. parameters whose values contain only zero or more spaces):

{{#invoke:params|with_value_not_matching|^%s*$|setting|hi/p|{{!}}|{{=}}|list}}

  Note: The argument passed to this function is not trimmed of its leading and trailing spaces. The with_value_not_matching function name itself, however, will be trimmed of its surrounding spaces.

Template:Unstructured infobox

Brief

Remove leading and trailing spaces from values

Syntax

{{#invoke:params|trimming_values|pipe function name}}

This modifier does not take arguments besides the name of the function that will follow.

Most modifiers are order-dependent, therefore placing trimming_values in different positions can generate different results. For instance, imagining our {{Example template}} being called with the following spaced arguments: {{Example template| wanna | be | my | friend | ? }}, if {{Example template}} contained the following code,

{{#invoke:params|with_value_matching|%s+$|trimming_values|setting|i/p|{{!}}|{{=}}|list}}

the following text would be printed: 1=wanna|2=be|3=my|4=friend|5=?. But if instead it contained the following code,

{{#invoke:params|trimming_values|with_value_matching|%s+$|setting|i/p|{{!}}|{{=}}|list}}

no arguments would be shown.

Order affects also performance, and how many values will be trimmed of their leading and trailing spaces will depend on where trimming_values is placed. If a template were invoked with 50 parameters and its code contained {{#invoke:params|trimming_values|cutting|-1|0|list}}, first all its values would be trimmed of leading and trailing blank spaces and then its first 49 parameters would be discarded. On the other hand, writing {{#invoke:params|cutting|-1|0|trimming_values|list}} would first discard 49 parameters and then trim the only value left, resulting in a more efficient code. As a general rule, placing trimming_values as the last modifier is always the best choice.

Placing trimming_values together with non-sequential will result in an empty call with no effects, because non-sequential parameters are stripped of their leading and trailing spaces by default.

Order difference does not affect only performance.

Using trimming_values makes this module behave like many Wikipedia modules behave. For example, if we wanted to emulate {{#invoke:Separated entries|main}}, writing

{{#invoke:params|sequential|squeezing|trimming_values|setting|i|XXXX|list_values}}

will be equivalent to writing,

{{#invoke:separated entries|main|separator=XXXX}}

whereas writing

{{trim|{{{1|}}}}}{{#invoke:params|sequential|squeezing|cutting|1|1|trimming_values|setting|ih|XXXX|list_values}}{{#invoke:params|sequential|squeezing|cutting|1|0|cutting|-1|0|trimming_values|setting|h|YYYY|value_of|1}}

will be equivalent to writing

{{#invoke:separated entries|main|separator=XXXX|conjunction=YYYY}}

• {{#invoke:TemplatePar|function}}
• {{#invoke:ParameterCount|function}}
• {{#invoke:Separated entries|main}}
• {{#invoke:Check for unknown parameters|check}}
• {{#invoke:Check for deprecated parameters|check}}
• {{#invoke:Check for clobbered parameters|check}}
• {{#invoke:Parameter validation|function}}
• {{#invoke:Expand wikitext|main}}
• {{#invoke:For loop|main}} and {{For loop}}
• {{#invoke:For nowiki|main}} and {{For nowiki}}
• Project:TemplateData