The
The module offers elegant shortcuts to non variadic templates as well. Outside templates it has virtually no applications; hence, if you plan to make experiments, make sure to do them from within a template, or you will not be able to see much (you can use for that). Under ./testcases you can find helper templates that can be specifically used for testing the module's capabilities in flexible ways (see in particular the template).
In case your template uses this module, please add to its documentation page, so that if breaking changes will be introduced in the future the template will be easily traceable.
Among the possibilities that the module offers there is that of performing a series of actions after novel arguments have been concatenated to templates' incoming parameters. As this makes it necessary to keep the argument slots clean from interference, 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:
For instance, as the name suggests, the [[#list|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|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
and such template were called with the following arguments,
the following result would be produced:
Beast of Bodmin: A large feline inhabiting Bodmin Moor
Morgawr: A sea serpent
Owlman: A giant owl-like creature
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,
thus yielding:
By placing the [[#with_name_matching|with_name_matching]] modifier before the [[#list|list]] function we will be able to filter some parameters out – such as, for instance, all parameter names that do not end with an “n”:
Thus, the previous code will produce:
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:
The two modifiers [[#sequential|sequential]] and [[#non-sequential|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 – 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. You might want to see also § Modifiers.
self | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function self | |
| Label1: | Num. of arguments |
| Data1: | 0 |
| Label3: | Not affected by |
| Data3: | Any modifier |
| Header4: | See also |
| Data5: | {{[[:mw:Help:Magic words#FULLPAGENAME|FULLPAGENAME]]}} |
This argumentless function guarantees that the name of the template invoking this module is shown, regardless if this is transcluded or not.
As a possible example, if a Wikipedia page named Page X contained only a transclusion of a template named
if we visited Template:Foobar we would see,
Template:Foobar Template:Foobar
whereas if we visited Page X we would see:
Template:Foobar Page X
Therefore by writing
it is possible to understand whether a page is being transcluded or not. For most cases the and will offer a simpler solution, however there can be cases in which this becomes the way to go.
If Page X transcluded
Template:Foobar Page X
A typical use case of this function is that of providing stable links for editing transcluded templates. E.g.:
Another possible use case is that of transcluding a subtemplate. E.g.:
count | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function count | |
| Label1: | Num. of arguments |
| Data1: | 0 |
| Label2: | Often preceeded by |
| Data2: | [[#sequential|sequential]] |
| Label3: | Not affected by |
| Data3: | [[#all_sorted|all_sorted]], [[#setting|setting]],[[#sorting_sequential_values|sorting_sequential_val…]],[[#mapping_by_calling|mapping_by_calling]], [[#mapping_by_invoking|mapping_by_invoking]], [[#mapping_by_magic|mapping_by_magic]] |
| Header4: | See also |
This function does not take arguments.
The number that this function yields depends on the modifiers that precede it. For instance, in a template that is called with both named and unnamed arguments,
and
will return different results.
concat_and_call | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function concat_and_call | |
| Label1: | Num. of arguments |
| Data1: | Ad libitum |
| Label2: | Not affected by |
| Data2: | [[#all_sorted|all_sorted]] |
| Header3: | See also |
| Data4: | [[#concat_and_invoke|concat_and_invoke]], [[#concat_and_magic|concat_and_magic]] |
For example, if our
and were called with,
the following call to the
By using the [[#cutting|cutting]] modifier it is possible to impose numerical positive parameters instead of prepending them. For instance, the following code echoes all incoming parameters to hello world:
If the numerical parameters to replace are a limited number, as in the example above, a better alternative might be that of using [[#imposing|imposing]].
If no other argument besides the template name are provided this function simply echoes the current parameters to another template.
All arguments passed to this function except the template name will not be trimmed of their leading and trailing spaces. The concat_and_call function name itself, however, will be trimmed of its surrounding spaces.
concat_and_invoke | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function concat_and_invoke | |
| Label1: | Num. of arguments |
| Data1: | Ad libitum |
| Label2: | Not affected by |
| Data2: | [[#all_sorted|all_sorted]] |
| Header3: | See also |
| Data4: | [[#concat_and_call|concat_and_call]], [[#concat_and_magic|concat_and_magic]] |
Exactly like [[#concat_and_call|concat_and_call]], but invokes a module instead of calling a template.
All arguments passed to this function except the module name and the function name will not be trimmed of their leading and trailing spaces. The concat_and_invoke function name itself, however, will be trimmed of its surrounding spaces.
concat_and_magic | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function concat_and_magic | |
| Label1: | Num. of arguments |
| Data1: | Ad libitum |
| Label2: | Not affected by |
| Data2: | [[#all_sorted|all_sorted]] |
| Header3: | See also |
| Data4: | [[#concat_and_call|concat_and_call]], [[#concat_and_invoke|concat_and_invoke]] |
Exactly like [[#concat_and_call|concat_and_call]], but calls a parser function instead of a template.
All arguments passed to this function except the magic word will not be trimmed of their leading and trailing spaces. The concat_and_magic function name itself, however, will be trimmed of its surrounding spaces.
value_of | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function value_of | |
| Label1: | Num. of arguments |
| Data1: | 1 |
| Data2: | h, f, n |
| Label3: | Not affected by |
| Data3: | [[#all_sorted|all_sorted]] |
| Header4: | See also |
| Data5: | [[#list_values|list_values]] |
Without modifiers this function is similar to writing
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|setting]] modifier – the strings assigned to the key-value pair delimiter (p), the iteration delimiter (i) and the last iteration delimiter (l) will be ignored.
For instance, the template could be rewritten as
Simplifying, the following wikitext expands to the first parameter that is not empty:
Whereas the following wikitext expands to the first parameter that is not blank (i.e. neither empty nor containing only whitespaces)
list | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function list | |
| Label1: | Num. of arguments |
| Data1: | Ad libitum |
| Data2: | Yes |
| Data3: | h, p, i, l, f, n |
| Header4: | See also |
| Data5: | [[#list_values|list_values]] |
This function does not take arguments.
If the [[#setting|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 last iteration delimiter (l), a footer (f), and a fallback text (n) can be declared via [[#setting|setting]].
For example, the following code
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)
list_values | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function list_values | |
| Label1: | Num. of arguments |
| Data1: | Ad libitum |
| Data2: | Yes |
| Label3: | Often preceeded by |
| Data3: | [[#sequential|sequential]] |
| Data4: | h, i, l, f, n |
| Header5: | See also |
| Data6: | [[#list|list]], [[#value_of|value_of]], |
This function does not take arguments.
The [[#sequential|sequential]] modifier often accompanies this function. If the [[#setting|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 last iteration delimiter (l), a footer (f), and a fallback text (n) can be declared via [[#setting|setting]] – the string assigned to the key-value pair delimiter (p) will be ignored.
For example, the following code
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.
call_for_each | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function call_for_each | |
| Label1: | Num. of arguments |
| Data1: | Ad libitum |
| Data2: | Yes |
| Data3: | h, i, l, f, n |
| Header4: | See also |
| Data5: | [[#call_for_each_value|call_for_each_value]], [[#invoke_for_each|invoke_for_each]], [[#magic_for_each|magic_for_each]], [[#call_for_each_group|call_for_each_group]],, |
Some functions are like shortcuts. The X_for_each|F functions are similar to mapping_by_X(ing)|F|(names_and_values|)list_values. The latter syntax (i.e. the modifier version) allows a values_and_names flag to invert the order from key-value to value-key.
All unnamed arguments following the template name will be placed after the key-value pair. Named arguments will be passed verbatim. A header (h), an iteration delimiter (i), a last iteration delimiter (l), a footer (f), and a fallback text (n) can be declared via the [[#setting|setting]] modifier – the string assigned to the key-value pair delimiter (p) will be ignored.
Calling a template for each key-value pair with
will be different from writing
In the first example each key-value pair will be passed to the $# and $@ tokens will be expanded after the
All arguments passed to this function except the template name will not be trimmed of their leading and trailing spaces. The call_for_each function name itself, however, will be trimmed of its surrounding spaces.
invoke_for_each | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function invoke_for_each | |
| Label1: | Num. of arguments |
| Data1: | Ad libitum |
| Data2: | Yes |
| Data3: | h, i, l, f, n |
| Header4: | See also |
| Data5: | [[#invoke_for_each_value|invoke_for_each_value]], [[#call_for_each|call_for_each]], [[#magic_for_each|magic_for_each]] |
Exactly like [[#call_for_each|call_for_each]], but invokes a module instead of calling a template.
Invoking a module function for each key-value pair with
will be different from writing
In the first example each key-value pair will be passed to the $# and $@ tokens will be expanded after the module function has been invoked. There might be cases in which this will make no difference, however there are several situations where it will lead to nonsensical results.
All arguments passed to this function except the module name and the function name will not be trimmed of their leading and trailing spaces. The invoke_for_each function name itself, however, will be trimmed of its surrounding spaces.
magic_for_each | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function magic_for_each | |
| Label1: | Num. of arguments |
| Data1: | Ad libitum |
| Data2: | Yes |
| Data3: | h, i, l, f, n |
| Header4: | See also |
| Data5: | [[#magic_for_each_value|magic_for_each_value]], [[#call_for_each|call_for_each]], [[#invoke_for_each|invoke_for_each]] |
Exactly like [[#call_for_each|call_for_each]], but calls a parser function instead of a template.
All arguments passed to this function except the magic word will not be trimmed of their leading and trailing spaces. The magic_for_each function name itself, however, will be trimmed of its surrounding spaces.
call_for_each_value | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function call_for_each_value | |
| Label1: | Num. of arguments |
| Data1: | Ad libitum |
| Data2: | Yes |
| Label3: | Often preceeded by |
| Data3: | [[#sequential|sequential]] |
| Data4: | h, i, l, f, n |
| Header5: | See also |
| Data6: | [[#call_for_each|call_for_each]], [[#invoke_for_each_value|invoke_for_each_value]], [[#magic_for_each_value|magic_for_each_value]], [[#call_for_each_group|call_for_each_group]],, |
The [[#sequential|sequential]] modifier often accompanies this function. All unnamed arguments following the template name will be appended after the value parameter. Named arguments will be passed verbatim. A header (h), an iteration delimiter (i), a last iteration delimiter (l), a footer (f), and a fallback text (n) can be declared via the [[#setting|setting]] modifier – the string assigned to the key-value pair delimiter (p) will be ignored.
For example, calling with each parameter can be done by writing
This will be different from writing
In the first example each value will be passed to the template, while in the second example the $@ token will be expanded after the template has been called. Here this will make no difference, however there are several situations where it will lead to nonsensical results.
All arguments passed to this function except the template name will not be trimmed of their leading and trailing spaces. The call_for_each_value function name itself, however, will be trimmed of its surrounding spaces.
invoke_for_each_value | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function invoke_for_each_value | |
| Label1: | Num. of arguments |
| Data1: | Ad libitum |
| Data2: | Yes |
| Label3: | Often preceeded by |
| Data3: | [[#sequential|sequential]] |
| Data4: | h, i, l, f, n |
| Header5: | See also |
| Data6: | [[#call_for_each_value|call_for_each_value]], [[#invoke_for_each|invoke_for_each]], [[#magic_for_each_value|magic_for_each_value]] |
Exactly like [[#call_for_each_value|call_for_each_value]], but invokes a module instead of calling a template.
Invoking a module function for each value with
will be different from writing
In the first example each value will be passed to the module function, while in the second example the $@ token will be expanded after the module function has been invoked. There might be cases in which this will make no difference, however there are several situations where it will lead to nonsensical results.
All arguments passed to this function except the module name and the function name will not be trimmed of their leading and trailing spaces. The invoke_for_each_value function name itself, however, will be trimmed of its surrounding spaces.
magic_for_each_value | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function magic_for_each_value | |
| Label1: | Num. of arguments |
| Data1: | Ad libitum |
| Data2: | Yes |
| Label3: | Often preceeded by |
| Data3: | [[#sequential|sequential]] |
| Data4: | h, i, l, f, n |
| Header5: | See also |
| Data6: | [[#call_for_each_value|call_for_each_value]], [[#invoke_for_each_value|invoke_for_each_value]], [[#magic_for_each|magic_for_each]] |
Exactly like [[#call_for_each_value|call_for_each_value]], but calls a parser function instead of a template.
For example, if a template had the following code,
and were transcluded as <nowiki>{{</nowiki>[[:mw:Help:Magic words#URL data|urlencode]]:...|QUERY<nowiki>}}</nowiki> 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.
All arguments passed to this function except the magic word will not be trimmed of their leading and trailing spaces. The magic_for_each_value function name itself, however, will be trimmed of its surrounding spaces.
call_for_each_group | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function call_for_each_group | |
| Label1: | Num. of arguments |
| Data1: | Ad libitum |
| Label2: | Often preceeded by |
| Data2: | [[#all_sorted|all_sorted]] |
| Data3: | Yes |
| Data4: | h, i, l, f, n |
| Header5: | See also |
| Data6: | [[#call_for_each|call_for_each]], [[#call_for_each_value|call_for_each_value]],, |
The custom template will be repeatedly called with the numerical id of the group (i.e. the numerical suffix) as argument zero (i.e.). This will be an empty string for the group of incoming parameters that do not have a numerical suffix. A hyphen before the numerical suffix will be interpreted as a minus sign (and therefore the group id will be treated as a negative number). Numerical incoming parameters will be treated as if their prefix is an empty string (these can be captured using {{{}}} or {{{|''fallback text''}}} in the callback template). Spaces between the prefix and the numerical suffix will be ignored (therefore writing will be identical to writing – in case of collisions one of the two values will be discarded). In the unlikely scenario that the prefix is itself a number (e.g.,, etc.), if this is 0 or a negative number it will be decreased by one unit in order to leave the parameter zero undisturbed (so 0 will become -1, -1 will become -2, and so on – if needed, you can use ...|[[#purging|purging]]|0{1|... in the callback template to renormalize these numbers).
All unnamed arguments that follow the template name in the invocation of this module will appear as sequential parameters in each call. Named arguments will be passed verbatim. Both named and unnamed arguments passed to this function will be given precedence in case of collisions. Numerical argument names below 1 will be decreased by one unit (i.e. ...|call_for_each_group|example template|0=Hello world|... will become in the callback template – see above).
A header (h), an iteration delimiter (i), a last iteration delimiter (l), a footer (f), and a fallback text (n) can be declared via the [[#setting|setting]] modifier – the string assigned to the key-value pair delimiter (p) will be ignored.
If you are a module writer, you might recognize some distant similarities between this function and [[Module:TableTools#affixNums|TableTools.affixNums]].
For example, if a template named
writing
will be equivalent to writing
The modifiers [[#sequential|sequential]], [[#non-sequential|non-sequential]] and [[#all_sorted|all_sorted]] will affect what groups of parameters will be iterated, not what parameters will be grouped. Before calling this function you will likely want to reduce the list of parameters via one of the with_*_matching group of modifiers (for instance ...|with_name_matching|.%-%d+$|or|[^%-]%d+$|call_for_each_group|... leaves only the parameters in which both the prefix and the numerical suffix are not empty strings). The [[#all_sorted|all_sorted]] modifier often accompanies this function.
In writing templates there is often the habit of signaling multilevel substitutions using the safesubst:”. Due to the fact that call_for_each_group can pass parameters with an empty name, a callback template should never use
At you can find an example of how to use this function to list authors the same way does. For instance, writing
will generate
All arguments passed to this function except the template name will not be trimmed of their leading and trailing spaces. The call_for_each_group function name itself, however, will be trimmed of its surrounding spaces.
for_each | Headerstyle: | background:lavender |
| Titlestyle: | font-weight:normal; font-size:100%; |
Function for_each | |
| Label1: | Num. of arguments |
| Data1: | 1 |
| Data2: | Yes |
| Data3: | h, i, l, f, n |
| Header4: | See also |
| Data5: | [[#list|list]], [[#list_values|list_values]],, |
$# and $@ within a given text as key and value respectivelyExample:
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|concat_and_call]] to propagate the incoming parameters altogether to the template. Example: