Module:Params/doc

The  module is designed to be adopted by those templates that want to have a deep control of their parameters. It is particularly useful to variadic templates, to which it offers the possibility to count, list, map and propagate the parameters received without knowing their number in advance.

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.

In case your template uses this module, please add to its the documentation page, so that if breaking changes will be introduced in the future the template will be easily traceable.

General usage
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:

For instance, as the name suggests, the  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  modifier, we are able to declare a key-value delimiter  and an iteration delimiter. And so, if we imagined a template named  containing the following wikitext,

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 and a footer, we can transform the previous code into a generator of definition lists,

thus yielding:


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

By placing the  modifier before the   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:


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

The two modifiers  and   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.

Functions
Here follows the list of functions. You might want to see also § Modifiers.


 * Brief
 * Count the number of parameters wherewith a template was called


 * Syntax

This function does not take arguments.


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


 * Syntax

For example, if our  had the following code,

and were called with,

the following call to the  template would be performed:

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 are not trimmed of their leading and trailing spaces. The  function name itself, however, will be trimmed of its surrounding spaces.


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


 * Syntax

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

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


 * Brief
 * Get the value of a single parameter


 * Syntax

Without modifiers this function is similar to writing. With modifiers, however, it allows to reach parameters that would be unreachable without knowing their number in advance. For instance, 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, a footer , and a fallback text can be declared via the   modifier – the strings assigned to the key-value pair delimiter  and the iteration delimiter  will be ignored.


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


 * Syntax

This function does not take arguments.

If the  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, a key-value pair delimiter , an iteration delimiter , a footer , and a fallback text can be declared via.

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)


 * Brief
 * List the values of the incoming parameters


 * Syntax

This function does not take arguments.

The  modifier normally accompanies this function. If the  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, an iteration delimiter , a footer , and a fallback text can be declared via   – the string assigned to the key-value pair delimiter  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.


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


 * Syntax

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

Calling a template for each key-value pair with

will be different than writing

In the first example each key-value pair will be passed to the foobar template, while in the second example the  and   tokens will be expanded after the foobar template has been called. In most cases 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 are not trimmed of their leading and trailing spaces. The  function name itself, however, will be trimmed of its surrounding spaces.


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


 * Syntax

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

Invoking a module function for each key-value pair with

will be different than writing

In the first example each key-value pair will be passed to the module function, while in the second example 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 are not trimmed of their leading and trailing spaces. The  function name itself, however, will be trimmed of its surrounding spaces.


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


 * Syntax

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

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


 * 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

The  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, an iteration delimiter , a footer , and a fallback text can be declared via the   modifier – the string assigned to the key-value pair delimiter  will be ignored.

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

This will be different than writing

In the first example each value will be passed to the tl template, while in the second example the  token will be expanded after the tl 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 are not trimmed of their leading and trailing spaces. The  function name itself, however, will be trimmed of its surrounding spaces.


 * 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

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

Invoking a module function for each value with

will be different than 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 are not trimmed of their leading and trailing spaces. The  function name itself, however, will be trimmed of its surrounding spaces.


 * 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

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

For example, if a template had the following code,

and were transcluded as, the   parser function would be called for each incoming parameter as first argument and with   as second argument, and finally the returned text would be prefixed with. 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 are not trimmed of their leading and trailing spaces. The  function name itself, however, will be trimmed of its surrounding spaces.


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


 * Syntax

Example:

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

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

Modifiers (piping functions)
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.


 * Brief
 * Reduce the parameter list to the subgroup of consecutive parameters that follow 


 * Syntax

Example:

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

Using  together with   will generate an error.

Like, the   modifier permanently marks a query. For instance, writing  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.


 * Brief
 * Reduce the parameter list by discarding the subgroup of consecutive parameters that follow 


 * Syntax

Example:

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

Using  together with   will generate an error.

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


 * Brief
 * When the time will come, all parameters will be dispatched sorted: first the numerical ones, then the rest in alphabetical order


 * Syntax

Example:

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

Normally only sequential parameters are dispatched sorted, whereas non-sequential ones are dispatched randomly. The  modifier ensures that nothing is left out of (alphabetical) order. Attention must be paid to the fact that parameters whose name is a negative number will appear first. To avoid this the  modifier can be used.

The  modifier only affects the way parameters are shown, but has no effects on functions that do not iterate or cannot impose an order, such as:



The  modifier cannot be used with functions that propagate several parameters together in a single call, like   and , because during a call the order of arguments is always lost. For the same reason, it is not possible to guess the order of named parameters a template was invoked with.


 * Brief
 * Define glue strings


 * Syntax

This modifier allows to set some internal variables that will be used by other functions. It takes a variable number of arguments, relying on the first argument to understand how many other arguments to read. A few examples will introduce it better than words:


 * ↳ Set the value of iteration delimiter to, then list all values
 * ↳ Set the value of both header text and iteration delimiter to, then list all values
 * ↳ Set the value of both header text and iteration delimiter to, set key-value pair delimiter to  , then list all parameters
 * ↳ Set the value of both header text and iteration delimiter to, set key-value pair delimiter to  , set fallback text to  , then list all parameters
 * ↳ Set the value of both header text and iteration delimiter to, set key-value pair delimiter to  , then list all parameters
 * ↳ Set the value of both header text and iteration delimiter to, set key-value pair delimiter to  , set fallback text to  , then list all parameters
 * ↳ Set the value of both header text and iteration delimiter to, set key-value pair delimiter to  , set fallback text to  , then list all parameters
 * ↳ Set the value of both header text and iteration delimiter to, set key-value pair delimiter to  , set fallback text to  , 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 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. ), it is possible to write separate invocations of   for each variable, as in. This method will be slightly less efficient.


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


 * Syntax

Example:

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:




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


 * Syntax

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.  indicates that the last three arguments must not be discarded.

Example:

If the absolute value of the sum of the two arguments (left and right cut) is greater than the number of sequential parameters available, the behavior will be the same as if the sum had been equal to the number of sequential parameters available, both when this is a positive value and when it is a negative value (with opposite results). After the desired sequential parameters have been discarded all numerical parameters will be shifted accordingly.

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

Although  de facto gets rid of all sequential parameters, it is clearer and more idiomatic to write   to obtain the same effect. Writing  will leave zero arguments to show.


 * Brief
 * Discard all parameters whose name does not match all the given patterns


 * Syntax

Internally this modifier uses Lua's  function to find whether parameter names match against given patterns; therefore, unless a target string is set to , please use the same syntax of Lua patterns. The plain flag can be either  or omitted. When omitted it is assumed that the target string is a Lua pattern.

To express a logical OR the  keyword is available. To express a logical AND instead, concatenate more invocations of.

For the sake of argument we will imagine that we are invoking  from within the Infobox artery template, and this is being called with the following parameters:

Test cases:


 * List only the parameters whose names match against the  pattern:
 * List the parameters whose names match against both patterns  and  :
 * List the parameters whose names match against either the  or the   pattern:
 * List the parameters whose names match against either the  plain string or the   pattern:
 * List the parameters whose names match against either the  or the   pattern:
 * List the parameters whose names match against either the  plain string or the   pattern:
 * List the parameters whose names match against either the  or the   pattern:
 * List the parameters whose names match against either the  plain string or the   pattern:
 * List the parameters whose names match against either the  plain string or the   pattern:
 * List the parameters whose names match against either the  plain string or the   pattern:

The pattern arguments passed to this function are not trimmed of their leading and trailing spaces. The  and   keywords, and the   function name itself, however, will be trimmed of their surrounding spaces.


 * Brief
 * Discard all parameters whose name matches all the given patterns


 * Syntax

Internally this modifier uses Lua's  function to find whether parameter names match against given patterns; therefore, unless a target string is set to , please use the same syntax of Lua patterns. The plain flag can be either  or omitted. When omitted it is assumed that the target string is a Lua pattern.

To express a logical OR the  keyword is available. To express a logical AND instead, concatenate more invocations of.

For the sake of argument we will imagine that we are invoking  from within the Infobox artery template, and this is being transcluded using the same parameters that we had imagined in the previous example at  :


 * List only the parameters whose names do not match against the  pattern:
 * List the parameters whose names do not match against the  plain string and do not match against the   plain string either:
 * List the parameters whose names do not match against either the  plain string or the   plain string:
 * List the parameters whose names do not match against the  plain string and do not match against the   plain string either:
 * List the parameters whose names do not match against either the  plain string or the   plain string:
 * List the parameters whose names do not match against either the  plain string or the   plain string:
 * List the parameters whose names do not match against either the  plain string or the   plain string:

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

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



The pattern arguments passed to this function are not trimmed of their leading and trailing spaces. The  and   keywords, and the   function name itself, however, will be trimmed of their surrounding spaces.


 * Brief
 * Discard all parameters whose value does not match all the given patterns


 * Syntax

Exactly like, but applied to parameter values instead of names.

Internally this modifier uses Lua's  function to find whether parameter names match against given patterns; therefore, unless a target string is set to , please use the same syntax of Lua patterns. The plain flag can be either  or omitted. When omitted it is assumed that the target string is a Lua pattern.

Example:

The pattern arguments passed to this function are not trimmed of their leading and trailing spaces. The  and   keywords, and the   function name itself, however, will be trimmed of their surrounding spaces.


 * Brief
 * Discard all parameters whose value matches all the given patterns


 * Syntax

Exactly like, but applied to parameter values instead of names.

Internally this modifier uses Lua's  function to find whether parameter names match against given patterns; therefore, unless a target string is set to , please use the same syntax of Lua patterns. The plain flag can be either  or omitted. When omitted it is assumed that the target string is a Lua pattern.

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

The pattern arguments passed to this function are not trimmed of their leading and trailing spaces. The  and   keywords, and the   function name itself, however, will be trimmed of their surrounding spaces.


 * Brief
 * Remove leading and trailing spaces from values


 * Syntax

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

Most modifiers are order-dependent, therefore placing  in different positions can generate different results. For instance, imagining our  being called with the following spaced arguments: , if   contained the following code,

the following text would be printed:. But if instead it contained the following code,

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  is placed. For instance, if a template were invoked with 50 parameters and its code contained, 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  would first discard 49 parameters and then trim the only value left, resulting in a more efficient code. As a general rule, placing  as the last modifier is always the best choice.

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

Using  makes this module behave like many Wikipedia modules behave. For example, if we wanted to emulate, writing

will be equivalent to writing,

whereas writing

will be equivalent to writing