Content deleted Content added
mNo edit summary |
Update the documentation |
||
Line 11:
The <syntaxhighlight lang="wikitext" inline>{{#invoke:params}}</syntaxhighlight> 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 template]]s, 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 (you can use {{tl|Template sandbox}} for that). Under {{rel|Module:Params/testcases}} you can find helper templates that can be specifically used for testing the module's capabilities in flexible ways
{{A note}} In case your template uses <syntaxhighlight lang="wikitext" inline>{{#invoke:params}}</syntaxhighlight>, please add {{tji|lua|Module:Params}} to its documentation page, so that if breaking changes will be introduced in the future the template will be easily traceable without performing <span class="plainlinks">[//en.wikipedia.org/w/index.php?search=insource%3A%2Finvoke%3Aparams%2F&title=Special%3ASearch&profile=advanced&fulltext=1&ns10=1&limit=500&sort=last_edit_desc an “in source” search]</span>.
Please, do not edit this module without having done extensive testing in the [[Module:Params/sandbox|module's sandbox]] first.
== General usage ==
Line 555:
| label4 = Relevant [[#setting|runtime variables]] | data4 = <code>h</code>, <code>i</code>, <code>l</code>, <code>f</code>, <code>n</code>
| header5 = See also
| data6 = <code>[[#grouping_by_calling|grouping_by_calling]]</code>, <code>[[#call_for_each|call_for_each]]</code>, <code>[[#call_for_each_value|call_for_each_value]]</code>, {{mlx|for loop|}}, {{tl2|for loop}}
}}
Line 1,413:
: ''Discard all parameters whose name ''does not match '''any''''' of the given patterns''
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|with_name_matching|
Internally this modifier uses Lua's <code>[[:mw:Extension:Scribunto/Lua reference manual#string.find|string.find()]]</code> function to find whether parameter names match against given patterns; therefore, unless a ''plain flag'' is set, please use the same syntax of [[:mw:Extension:Scribunto/Lua reference manual#Patterns|Lua patterns]]. The ''plain flag'' can be either <code>plain</code> or <code>strict</code> or omitted. When omitted it is assumed that the target string is a Lua pattern. The difference between <code>plain</code> and <code>strict</code> is that the latter also requires that the lengths match (this happens only when the two strings are 100% identical). In order to facilitate wikitext scripting in the ''plain flag'' argument, the <code>pattern</code> keyword is available too, equivalent to omitting the argument.
Line 1,465:
{{vpad|clear=none}}
{{A note}} The
{{vpad|1.5em|clear=none}}
Line 1,482:
: ''Discard all parameters whose name ''matches '''all''''' the given patterns''
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|with_name_not_matching|
Internally this modifier uses Lua's <code>[[:mw:Extension:Scribunto/Lua reference manual#string.find|string.find()]]</code> function to find whether parameter names match against given patterns; therefore, unless a plain flag is set, please use the same syntax of [[:mw:Extension:Scribunto/Lua reference manual#Patterns|Lua patterns]]. The plain flag can be either <code>plain</code> or <code>strict</code> or omitted. When omitted it is assumed that the target string is a Lua pattern. The difference between <code>plain</code> and <code>strict</code> is that the latter also requires that the lengths match (this happens only when the two strings are 100% identical). In order to facilitate wikitext scripting in the ''plain flag'' argument, the <code>pattern</code> keyword is available too, equivalent to omitting the argument.
Line 1,506:
{{N.b.}} For the sake of efficiency, please don't use this modifier with the <code>strict</code> flag, use <code>[[#discarding|discarding]]</code> instead!
{{A note}} The
{{vpad|1.5em|clear=none}}
Line 1,523:
: ''Discard all parameters whose value ''does not match '''any''''' of the given patterns''
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|with_value_matching|
Exactly like <code>[[#with_name_matching|with_name_matching]]</code>, but applied to parameter values instead of names.
Line 1,535:
{{vpad|clear=none}}
{{A note}} The
{{vpad|1.5em|clear=none}}
Line 1,552:
: ''Discard all parameters whose value ''matches '''all''''' the given patterns''
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|with_value_not_matching|
Exactly like <code>[[#with_name_not_matching|with_name_not_matching]]</code>, but applied to parameter values instead of names.
Line 1,568:
{{vpad|clear=none}}
{{A note}} The
{{vpad|1.5em|clear=none}}
Line 1,628:
| label2 = Repeatable | data2 = Yes
| header3 = See also
| data4 = <code>[[#call_for_each|call_for_each]]</code>, <code>[[#call_for_each_value|call_for_each_value]]</code>, <code>[[#mapping_by_invoking|mapping_by_invoking]]</code>, <code>[[#mapping_by_magic|mapping_by_magic]]</code>, <code>[[#mapping_by_replacing|mapping_by_replacing]]</code>, <code>[[#renaming_by_calling|renaming_by_calling]]</code>, <code>[[#renaming_by_invoking|renaming_by_invoking]]</code>, <code>[[#renaming_by_magic|renaming_by_magic]]</code>, <code>[[#renaming_by_replacing|renaming_by_replacing]]</code>, <code>[[#grouping_by_calling|grouping_by_calling]]</code>
}}
Line 1,712:
| label2 = Repeatable | data2 = Yes
| header3 = See also
| data4 = <code>[[#invoke_for_each|invoke_for_each]]</code>, <code>[[#invoke_for_each_value|invoke_for_each_value]]</code>, <code>[[#mapping_by_calling|mapping_by_calling]]</code>, <code>[[#mapping_by_magic|mapping_by_magic]]</code>, <code>[[#mapping_by_replacing|mapping_by_replacing]]</code>, <code>[[#renaming_by_calling|renaming_by_calling]]</code>, <code>[[#renaming_by_invoking|renaming_by_invoking]]</code>, <code>[[#renaming_by_magic|renaming_by_magic]]</code>, <code>[[#renaming_by_replacing|renaming_by_replacing]]</code>, <code>[[#grouping_by_calling|grouping_by_calling]]</code>
}}
Line 1,755:
| label2 = Repeatable | data2 = Yes
| header3 = See also
| data4 = <code>[[#magic_for_each|magic_for_each]]</code>, <code>[[#magic_for_each_value|magic_for_each_value]]</code>, <code>[[#mapping_by_calling|mapping_by_calling]]</code>, <code>[[#mapping_by_invoking|mapping_by_invoking]]</code>, <code>[[#mapping_by_replacing|mapping_by_replacing]]</code>, <code>[[#renaming_by_calling|renaming_by_calling]]</code>, <code>[[#renaming_by_invoking|renaming_by_invoking]]</code>, <code>[[#renaming_by_magic|renaming_by_magic]]</code>, <code>[[#renaming_by_replacing|renaming_by_replacing]]</code>, <code>[[#grouping_by_calling|grouping_by_calling]]</code>
}}
Line 1,798:
| label2 = Repeatable | data2 = Yes
| header3 = See also
| data4 = <code>[[#mapping_by_calling|mapping_by_calling]]</code>, <code>[[#mapping_by_invoking|mapping_by_invoking]]</code>, <code>[[#mapping_by_magic|mapping_by_magic]]</code>, <code>[[#renaming_by_calling|renaming_by_calling]]</code>, <code>[[#renaming_by_invoking|renaming_by_invoking]]</code>, <code>[[#renaming_by_magic|renaming_by_magic]]</code>, <code>[[#renaming_by_replacing|renaming_by_replacing]]</code>, <code>[[#grouping_by_calling|grouping_by_calling]]</code>
}}
Line 1,804:
: ''[[Map (higher-order function)|Map]] all parameter values performing [[String operations#String substitution|string substitutions]]''
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|mapping_by_replacing|
This modifier (temporarily) changes the content of the parameters the current template is being called with, replacing each of them with the result of a string substitution. Its syntax is very simlar to {{mfl|string|replace}}.
Line 1,826:
{{vpad|clear=none}}
{{A note}} The
{{vpad|1.5em|clear=none}}
Line 1,837:
| label2 = Repeatable | data2 = Yes
| header3 = See also
| data4 = <code>[[#mapping_by_calling|mapping_by_calling]]</code>, <code>[[#mapping_by_invoking|mapping_by_invoking]]</code>, <code>[[#mapping_by_magic|mapping_by_magic]]</code>, <code>[[#mapping_by_replacing|mapping_by_replacing]]</code>, <code>[[#renaming_by_invoking|renaming_by_invoking]]</code>, <code>[[#renaming_by_magic|renaming_by_magic]]</code>, <code>[[#renaming_by_replacing|renaming_by_replacing]]</code>, <code>[[#grouping_by_calling|grouping_by_calling]]</code>
}}
Line 1,870:
| label2 = Repeatable | data2 = Yes
| header3 = See also
| data4 = <code>[[#mapping_by_calling|mapping_by_calling]]</code>, <code>[[#mapping_by_invoking|mapping_by_invoking]]</code>, <code>[[#mapping_by_magic|mapping_by_magic]]</code>, <code>[[#mapping_by_replacing|mapping_by_replacing]]</code>, <code>[[#renaming_by_calling|renaming_by_calling]]</code>, <code>[[#renaming_by_magic|renaming_by_magic]]</code>, <code>[[#renaming_by_replacing|renaming_by_replacing]]</code>, <code>[[#grouping_by_calling|grouping_by_calling]]</code>
}}
Line 1,899:
| label2 = Repeatable | data2 = Yes
| header3 = See also
| data4 = <code>[[#mapping_by_calling|mapping_by_calling]]</code>, <code>[[#mapping_by_invoking|mapping_by_invoking]]</code>, <code>[[#mapping_by_magic|mapping_by_magic]]</code>, <code>[[#mapping_by_replacing|mapping_by_replacing]]</code>, <code>[[#renaming_by_calling|renaming_by_calling]]</code>, <code>[[#renaming_by_invoking|renaming_by_invoking]]</code>, <code>[[#renaming_by_replacing|renaming_by_replacing]]</code>, <code>[[#grouping_by_calling|grouping_by_calling]]</code>
}}
Line 1,928:
| label2 = Repeatable | data2 = Yes
| header3 = See also
| data4 = <code>[[#mapping_by_calling|mapping_by_calling]]</code>, <code>[[#mapping_by_invoking|mapping_by_invoking]]</code>, <code>[[#mapping_by_magic|mapping_by_magic]]</code>, <code>[[#mapping_by_replacing|mapping_by_replacing]]</code>, <code>[[#renaming_by_calling|renaming_by_calling]]</code>, <code>[[#renaming_by_invoking|renaming_by_invoking]]</code>, <code>[[#renaming_by_magic|renaming_by_magic]]</code>, <code>[[#grouping_by_calling|grouping_by_calling]]</code>
}}
Line 1,934:
: ''Rename all parameters, replacing their former names with the text returned by a [[String operations#String substitution|string substitutions]]''
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|renaming_by_replacing|
This modifier works similarly to <code>[[#mapping_by_replacing|mapping_by_replacing]]</code>, but instead of replacing parameters' values '''it renames the parameters themselves'''. Care must be used knowing that if a new name collides with another new name one of the two parameters will be removed without knowing which one. New names and old names do not create collisions. If a name is returned identical it will be considered as “unchanged” and in case of conflicts the renamed one will prevail. Possible leading and trailing spaces in the new names are always stripped.
Line 1,946:
{{vpad|clear=none}}
{{A note}} The
{{vpad|1.5em|clear=none}}
=== <code>grouping_by_calling</code> ===
{{Infobox|headerstyle=background:lavender
| titlestyle = font-weight:normal; font-size:100%;
| title = Modifier <code>grouping_by_calling</code> <span style="nowrap">({{module:params/doc/link to the code|grouping_by_calling|code}})</span>
| label1 = Num. of arguments | data1 = ''Ad libitum''
| label2 = Repeatable | data2 = Yes<ref>Unless followed by <code>[[#renaming_by_replacing|renaming_by_replacing]]</code> in few bizarre situations, there is virtually no use in calling this modifier more than once.</ref>
| header3 = See also
| data4 = <code>[[#call_for_each_group|call_for_each_group]]</code>, <code>[[#mapping_by_calling|mapping_by_calling]]</code>, <code>[[#mapping_by_invoking|mapping_by_invoking]]</code>, <code>[[#mapping_by_magic|mapping_by_magic]]</code>, <code>[[#mapping_by_replacing|mapping_by_replacing]]</code>, <code>[[#renaming_by_calling|renaming_by_calling]]</code>, <code>[[#renaming_by_invoking|renaming_by_invoking]]</code>, <code>[[#renaming_by_magic|renaming_by_magic]]</code>, <code>[[#renaming_by_replacing|renaming_by_replacing]]</code>
}}
; Brief
: ''Group the parameters that have the same numerical suffix into novel parameters, whose names will be numbers and whose values will be decided by a custom template''
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|grouping_by_calling|template name|[let]|[...]|[number of additional arguments]|[argument 1]|[argument 2]|[...]|[argument N]|pipe function name}}</syntaxhighlight>
This is the piping version of <code>[[#call_for_each_group|call_for_each_group]]</code>. This means that after calling this modifier the old parameters will be (temporarily) gone and the only parameters left will be novel parameters whose names will be numbers – or an empty string if parameters without numerical suffix were present – and whose content will be decided by a custom template.
Like other modifiers in the <code>mapping_*</code> and <code>renaming_*</code> family, it is possible to impose own parameters on the callback template by using the syntax <code>...|[let]|[...]|[number of additional arguments]|[argument 1]|[argument 2]|[...]|[argument N]|...</code>. Unlike the other <code>mapping_*</code> and <code>renaming_*</code> modifiers, however (but like <code>[[#call_for_each_group|call_for_each_group]]</code>), sequential parameters here will not be prepended, but will ''replace'' possible parsed parameters.
And so, writing
<syntaxhighlight lang="wikitext">{{#invoke:params|...|grouping_by_calling|MY TEMPLATE|let|foo|bar|let|hello|world|3|one|two|three|list_values}}</syntaxhighlight>
is identical to writing
<syntaxhighlight lang="wikitext">{{#invoke:params|...|call_for_each_group|MY TEMPLATE|foo=bar|hello=world|one|two|three}}</syntaxhighlight>
In the example above the main difference will be that the first solution will allow to pass the newly grouped parameters at once to another template or module (via <code>[[#concat_and_call|concat_and_call]]</code> or <code>[[#concat_and_invoke|concat_and_invoke]]</code>) or, if needed, perform further fine-tuning operations concerning the new parameters.
Please refer to the documentation of <code>[[#call_for_each_group|call_for_each_group]]</code> for further information on the parameters passed to the callback template.
{{vpad|clear=none}}
{{A note}} All arguments passed to this modifier except the <code>grouping_by_calling</code> modifier name itself, the ''template name'', the <code>let</code> keyword, the passed parameter names, and the number of additional parameters will not be trimmed of their leading and trailing spaces.
{{vpad|1.5em|clear=none}}
| |||