Module:Params/doc: Difference between revisions

Revision as of 03:57, 11 July 2023

Revision as of 07:58, 12 July 2023

Line 10:

<syntaxhighlight lang="wikitext">{{#invoke:params|[modifier]|[...]|[modifier]|[...]|function|[...]}}</syntaxhighlight>

For instance, as the name suggests, the [[#list|<code>list</code>]] 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|<code>setting</code>]] modifier, we are able to declare a key-value delimiter (<code>p</code>) and an iteration delimiter (<code>i</code>). And so, if we imagined a template named <code><nowiki>{{Example template}}</nowiki></code> containing the following wikitext,

<syntaxhighlight lang="wikitext">{{#invoke:params|listsetting|<i/dt><dd>p|<br /dd><dt>|<dl><dt>: |</dd></dl>list}}</syntaxhighlight>

and such template were called with the following arguments,

{{tj|Example template|Beast of Bodmin: A large feline inhabiting Bodmin Moor.

|Morgawr: A sea serpent.|Owlman: A giant owl-like creature.}}

the following result would be produced:

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

We can also do more sophisticated things, and by exploiting the possibility to set a header (<code>h</code>) and a footer (<code>f</code>) we an transform the previous code into a generator of [https://html.spec.whatwg.org/multipage/grouping-content.html#the-dl-element definition lists],

<syntaxhighlight lang="wikitext">{{#invoke:params|setting|h/p/i/f|<dl><dt>|</dt><dd>|</dd><dt>|</dd></dl>|list}}</syntaxhighlight>

thus yielding:

:; Beast of Bodmin

:: A large feline inhabiting Bodmin Moor.

:; Morgawr

:: A sea serpent.

:; Owlman

:: A giant owl-like creature.

However, byBy placing the [[#with_name_matching|<code>with_name_matching</code>]] modifier before the [[#list|<code>list</code>]] function we would be able to filter some parameters out – such as, for instance, all parameter names that do not end with an “n”:

<syntaxhighlight lang="wikitext">{{#invoke:params|with_name_matching|n$|listsetting|<h/dtp/i/f|<dl><dddt>|</dddt><dtdd>|<dl/dd><dt>|</dd></dl>|list}}</syntaxhighlight>

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:

<syntaxhighlight lang="wikitext">{{#invoke:params|non-sequential|with_name_matching|^B|with_name_matching|n$|with_name_matchingwith_value_matching|^Afeline|non-sequentialsetting|with_name_matchingh/p/i/f|<dl><dt>|</dt><dd>|</dd><dt>|banana</dd></dl>|list}}</syntaxhighlight>

The two modifiers [[#sequential|<code>sequential</code>]] and [[#non-sequential|<code>non-sequential</code>]] 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 {{para|1}} – this is known as the parameters' “sequence”. A parameter list that does not have a first parameter specified does not possess a sequence.

Line 61 ⟶ 69:

{{vpad|1.5em}}

=== <code>value_ofconcat_and_call</code> ===

; Brief

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

: ''Get the value of a single parameter''

; Syntax

: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|value_ofconcat_and_call|parametertemplate name|[headerprepend 1]|[prepend 2]|[...]|[prepend n]|[named item 1=value 1]|[...]|[named item n=value n]|[footer...]}}</syntaxhighlight>

}}</syntaxhighlight>

For example, if our <code><nowiki>{{Example template}}</nowiki></code> had the following code,

Without modifiers this function is similar to writing <syntaxhighlight lang="wikitext" inline>{{{parameter name|}}}</syntaxhighlight> – with optional header and footer to be displayed only when the parameter is found. With modifiers, however, it allows to reach parameters that would be unreachable without knowing their number in advance. For instance, writing

<syntaxhighlight lang="wikitext">{{#invoke:params|cuttingconcat_and_call|-2foo bar|0elbow|value_ofearth|1room|7=classy|hello=not today}}</syntaxhighlight>

and were called with,

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

{{tj|Example template|one|two|three|hello: world|wind: spicy}}

{{A note}} The header ({{para|2}}) and footer ({{para|3}}) arguments are not trimmed of their leading and trailing spaces. The <code>value_of</code> function name itself and the parameter name ({{para|1}}), on the other hand, will be trimmed of their surrounding spaces.

the following call to the <code><nowiki>{{Foo bar}}</nowiki></code> template would be performed:

{{tj|Foo bar|elbow|earth|room|7: classy|8: one|9: two|10: three

|wind: spicy|hello: not today}}

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

{{A note}} All arguments passed to this function except the template name are not trimmed of their leading and trailing spaces. The <code>concat_and_call</code> function name itself, however, can be surrounded by spaces.

{{vpad|1.5em}}

=== <code>listconcat_and_invoke</code> ===

; Brief

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

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

; Syntax

: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|listconcat_and_invoke|module name|function name|[key-valueprepend separator1]|[argumentprepend separator2]|[header...]|[prepend n]|[named item 1=value 1]|[...]|[named item n=value n]|[footer...]}}</syntaxhighlight>

}}</syntaxhighlight>

Exactly like [[#concat_and_call|<code>concat_and_call</code>]], but invokes a module instead of calling a template.

If no arguments are passed the vertical bar (<code>&#124;</code>) will be used as parameter separator and the equals sign (<code>=</code>) will be used as key-value separator, with no header and no footer.

{{A 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 <code>listconcat_and_invoke</code> function name itself, however, can be surrounded by spaces.

{{vpad|1.5em}}

=== <code>list_valuesvalue_of</code> ===

; Brief

: ''ListGet the templatevalue parameterof valuesa single parameter''

; Syntax

: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|list_valuesvalue_of|[argumentparameter separator]|[header]|[footer]name}}</syntaxhighlight>

Without modifiers this function is similar to writing <syntaxhighlight lang="wikitext" inline>{{{parameter name|}}}</syntaxhighlight>. With modifiers, however, it allows to reach parameters that would be unreachable without knowing their number in advance. For instance, writing

If no arguments are passed the vertical bar (<code>&#124;</code>) will be used as parameter separator, with no header and no footer.

<syntaxhighlight lang="wikitext">{{#invoke:params|cutting|-2|0|value_of|1}}</syntaxhighlight>

{{A note}} All arguments passed to this function are not trimmed of their leading and trailing spaces. The <code>list_values</code> function name itself, however, can be surrounded by spaces.

will write 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 (<code>h</code>), a footer (<code>f</code>), and a fallback text (<code>n</code>) are available via the [[#setting|<code>setting</code>]] modifier (the strings assigned to the key-value pair delimiter (<code>p</code>) and the iteration delimiter (<code>i</code>) will be ignored).

{{vpad|1.5em}}

=== <code>concat_and_calllist</code> ===

; Brief

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

: ''Prepend user-given numerical arguments to the current parameters, or impose user-given non-numerical arguments; then propagate everything to a custom template''

; Syntax

: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|concat_and_call|template name|[prepend 1]|[prepend 2]|[...]|[prepend n]|[named item 1=value 1]|[...]|[named item n=value n]|[...]list}}</syntaxhighlight>

}}</syntaxhighlight>

This function does not take arguments.

For example, if our <code><nowiki>{{Example template}}</nowiki></code> had the following code,

If the [[#setting|<code>setting</code>]] modifier was not placed before, 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 (<code>h</code>), a key-value pair delimiter (<code>p</code>), an iteration delimiter (<code>i</code>), a footer (<code>f</code>), and a fallback text (<code>n</code>) are available via [[#setting|<code>setting</code>]].

<syntaxhighlight lang="wikitext">{{#invoke:params|concat_and_call|foo bar|elbow|earth|room|7=classy|hello=not today}}</syntaxhighlight>

For example, the following code

and were called with,

<syntaxhighlight lang="wikitext">{{#invoke:params|setting|h/i/p/f/n|'''Parameters passed:''' |); | (|)|'''No parameters were passed'''|list}}</syntaxhighlight>

{{tj|Example template|one|two|three|hello: world|wind: spicy}}

will generate an output similar to the following.

the following call to the <code><nowiki>{{Foo bar}}</nowiki></code> template would be performed:

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

{{tj|Foo bar|elbow|earth|room|7: classy|8: one|9: two|10: three

|wind: spicy|hello: not today}}

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

{{A note}} All arguments passed to this function except the template name are not trimmed of their leading and trailing spaces. The <code>concat_and_call</code> function name itself, however, can be surrounded by spaces.

{{vpad|1.5em}}

=== <code>concat_and_invokelist_values</code> ===

; Brief

: ''List the values of the incoming parameters''

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

; Syntax

: <syntaxhighlight lang="wikitext" inline>{{#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]|[...]list_values}}</syntaxhighlight>

}}</syntaxhighlight>

This function does not take arguments.

Exactly like [[#concat_and_call|<code>concat_and_call</code>]], but invokes a module instead of calling a template.

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

{{A 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 <code>concat_and_invoke</code> function name itself, however, can be surrounded by spaces.

For example, the following code

<syntaxhighlight lang="wikitext">{{#invoke:params|setting|h/i/p/f/n|'''Parameters passed:''' |); | (|)|'''No parameters were passed'''|list}}</syntaxhighlight>

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.

{{vpad|1.5em}}

Line 147 ⟶ 169:

}}</syntaxhighlight>

All other unnamed parameters following the template name will be appendedplaced toafter the key-value pair. Named parameters will be passed verbatim. A header (<code>h</code>), an iteration delimiter (<code>i</code>), a footer (<code>f</code>), and a fallback text (<code>n</code>) are available via the [[#setting|<code>setting</code>]] modifier (the string assigned to the key-value pair delimiter (<code>p</code>) will be ignored).

Calling a template for each key-value pair with

Line 182 ⟶ 204:

{{A 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 <code>invoke_for_each</code> function name itself, however, can be surrounded by spaces.

{{vpad|1.5em}}

=== <code>magic_for_each</code> ===

; Brief

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

; Syntax

: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|magic_for_each|parser function|[append 1]|[append 2]|[...]|[append n]|[named param 1=value 1]|[...]|[named param n=value n]|[...]}}</syntaxhighlight>

Exactly like [[#call_for_each|<code>call_for_each</code>]], but calls a [[:mw:Help:Magic words#Parser functions|parser function]] instead of a template.

{{A note}} All arguments passed to this function except the magic word are not trimmed of their leading and trailing spaces. The <code>magic_for_each</code> function name itself, however, can be surrounded by spaces.

{{vpad|1.5em}}

Line 191 ⟶ 225:

: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|call_for_each_value|template name|[append 1]|[append 2]|[...]|[append n]|[named param 1=value 1]|[...]|[named param n=value n]|[...]}}</syntaxhighlight>

AllThe other[[#sequential|<code>sequential</code>]] 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 (<code>h</code>), an iteration delimiter (<code>i</code>), a footer (<code>f</code>), and a fallback text (<code>n</code>) are available via the [[#setting|<code>setting</code>]] modifier (the string assigned to the key-value pair delimiter (<code>p</code>) will be ignored).

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

Calling a template for each value with

<syntaxhighlight lang="wikitext">{{#invoke:params|sequential|setting|i|, |call_for_each_value|foobartl}}</syntaxhighlight>

This will be more efficient than writing

<syntaxhighlight lang="wikitext">{{#invoke:params|sequential|setting|i|, |for_each|{{foobartl|$@}}}}</syntaxhighlight>

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

{{A note}} All arguments passed to this function except the template name are not trimmed of their leading and trailing spaces. The <code>call_for_each_value</code> function name itself, however, can be surrounded by spaces.

Line 226 ⟶ 260:

{{A 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 <code>invoke_for_each_value</code> function name itself, however, can be surrounded by spaces.

{{vpad|1.5em}}

=== <code>magic_for_each_value</code> ===

; 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

: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|magic_for_each_value|parser function|[append 1]|[append 2]|[...]|[append n]|[named param 1=value 1]|[...]|[named param n=value n]|[...]}}</syntaxhighlight>

Exactly like [[#call_for_each_value|<code>call_for_each_value</code>]], but calls a [[:mw:Help:Magic words#Parser functions|parser function]] instead of a template.

For example, if a template had the following code,

<syntaxhighlight lang="wikitext">{{#invoke:params|sequential|setting|ih|&preloadparams%5b%5d{{=}}|magic_for_each_value|urlencode|QUERY}}</syntaxhighlight>

and were transcluded as <syntaxhighlight lang="wikitext" inline>{{example template|hello world|àèìòù|foo bar}}</syntaxhighlight>, the <code><nowiki>{{</nowiki>[[:mw:Help:Magic words#URL data|urlencode]]:...|QUERY<nowiki>}}</nowiki></code> parser function would be called for each incoming parameter as first argument and with <code>QUERY</code> as second argument, and finally the returned text would be prefixed with <code>&preloadparams%5b%5d=</code>. This would generate,

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

which can be used to allow [[:mw:Manual:Creating pages with preloaded text#Using parameters|the creation of pages with preloaded text and parameters]].

{{A note}} All arguments passed to this function except the magic word are not trimmed of their leading and trailing spaces. The <code>magic_for_each_value</code> function name itself, however, can be surrounded by spaces.

{{vpad|1.5em}}

Line 231 ⟶ 287:

=== <code>for_each</code> ===

; Brief

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

; Syntax

: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|for_each|wikitext|[header]|[footer]}}</syntaxhighlight>

Example:

Line 239 ⟶ 295:

<syntaxhighlight lang="wikitext">{{#invoke:params|for_each|Arg name: $#, Arg value: $@}}</syntaxhighlight>

{{A note}} AllThe argumentsargument passed to this function areis not trimmed of theirits leading and trailing spaces. The <code>for_each</code> function name itself, however, can be surrounded by spaces.

{{vpad}}

Line 277 ⟶ 333:

Using <code>non-sequential</code> together with [[#sequential|<code>sequential</code>]] will generate an error.

{{vpad|1.5em}}

=== <code>setting</code> ===

; Brief

: ''Set internal variables''

; Syntax

: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|setting|directives|...|pipe function name}}</syntaxhighlight>

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.

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

The slots available are the following:

{| class="wikitable" style="margin-left: auto; margin-right: auto;"

|-

! Slots

! Variable

! Description

|-

| <code>i</code>

| ''Iteration delimiter''

| The string of text that will be placed between each iteration; it is never inserted unless there are two or more parameters to show.

|-

| <code>p</code>

| ''Key-value pair delimiter''

| The string of text that will be placed between each parameter name and its value; it is never inserted by functions that only iterate between values, or by functions that pass the key-value pairs to external calls.

|-

| <code>h</code>

| ''Header text''

| The string of text that will be placed before the iteration begins; it is inserted printed if there are no parameters to show.

|-

| <code>f</code>

| ''Footer text''

| The string of text that will be placed after the iteration is over; it is never inserted if there are no parameters to show.

|-

| <code>n</code>

| ''Fallback text''

| The string of text that will be placed if there are no parameters to show.

|}

Examples:

* <syntaxhighlight lang="wikitext" inline>{{#invoke:params|setting|i|{{!}}|list_values}}</syntaxhighlight>

*: ↳ Sets the value of ''iteration delimiter'' to <code>|</code>, then list all values

* <syntaxhighlight lang="wikitext" inline>{{#invoke:params|setting|ih|{{!}}|list_values}}</syntaxhighlight>

*: ↳ Sets the value of both ''header text'' and ''iteration delimiter'' to <code>|</code>, then list all values

* <syntaxhighlight lang="wikitext" inline>{{#invoke:params|setting|ih/p|{{!}}|{{=}}|list}}</syntaxhighlight>

*: ↳ Sets the value of both ''header text'' and ''iteration delimiter'' to <code>|</code>, set ''key-value pair delimiter'' to <code>=</code>, then list all parameters

* <syntaxhighlight lang="wikitext" inline>{{#invoke:params|setting|ih/p/n|{{!}}|{{=}}|No parameters were passed|list}}</syntaxhighlight>

*: ↳ Sets the value of both ''header text'' and ''iteration delimiter'' to <code>|</code>, set ''key-value pair delimiter'' to <code>=</code>, set ''fallback text'' to <code>No parameters were passed</code>, then list all parameters

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

{{vpad|1.5em}}

Line 295 ⟶ 405:

<syntaxhighlight lang="wikitext">{{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| and [[$@]]|{{#if:{{{3|}}}|,}} and [[$@]]}}

|{{Error|{{tl|Foobar see also}} requires at least one page name}}

}}

Line 314 ⟶ 424:

Example:

<syntaxhighlight lang="wikitext">{{#invoke:params|with_name_matching|n$|listsetting|<h/dtp/i/f|<dl><dddt>|</dddt><dtdd>|<dl/dd><dt>|</dd></dl>|list}}</syntaxhighlight>

{{A note}} The argument passed to this function is not trimmed of its leading and trailing spaces. The <code>with_name_matching</code> function name itself, however, can be surrounded by spaces.

Line 361 ⟶ 471:

Example:

<syntaxhighlight lang="wikitext">{{#invoke:params|with_value_matching|n$banana|count}}</syntaxhighlight>

{{A note}} The argument passed to this function is not trimmed of its leading and trailing spaces. The <code>with_value_matching</code> function name itself, however, can be surrounded by spaces.

Line 377 ⟶ 487:

Example:

<syntaxhighlight lang="wikitext">{{#invoke:params|with_value_not_matching|n$deprecated|count}}</syntaxhighlight>

{{A note}} The argument passed to this function is not trimmed of its leading and trailing spaces. The <code>with_value_not_matching</code> function name itself, however, can be surrounded by spaces.