Content deleted Content added
Add more information about the new additions to the module |
|||
Line 8:
| textstyle = padding: .85em; text-align: center;
}}
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.
Line 1,491 ⟶ 1,489:
* {{ml|TemplatePar|valid}}
When used to discard single parameters, this modifier is equivalent to writing <code>...|[[
{{A note}} All arguments passed to this modifier and the <code>discarding</code> modifier name itself will be trimmed of their surrounding spaces.
Line 2,197 ⟶ 2,195:
; Brief
: ''Push a copy of the current parameter list to the
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|snapshotting|pipe function name}}</syntaxhighlight>
This module has a stacking mechanism that allows to isolate groups of parameters, work separately on them, and then merge them back to the original stack. The modifiers dedicated to this mechanism are:
* <code>snapshotting</code>
* <code>[[#remembering|remembering]]</code>
* <code>[[#entering_substack|entering_substack]]</code>
* <code>[[#pulling|pulling]]</code>
* <code>[[#detaching_substack|detaching_substack]]</code>
* <code>[[#leaving_substack|leaving_substack]]</code>
* <code>[[#merging_substack|merging_substack]]</code>
* <code>[[#flushing|flushing]]</code>
Every time the <code>snapshotting</code> modifier is used, the current list of parameters (together with their values) will be copied and added to a queue. When the <code>[[#entering_substack|entering_substack]]</code> modifier is used, the list of parameters on top of the queue will temporarily become the current parameters, and all other modifiers will affect only this substack. After completing the job, the <code>[[#merging_substack|merging_substack]]</code> will merge the current substack to the parent stack.
If no parameter lists have been snapshotted before calling <code>[[#entering_substack|entering_substack]]</code>, the latter will automatically make a snapshot of the current parameters. Once inside a substack, it is possible to enter a subsubstack using the same machinery.
The <code>[[#detaching_substack|detaching_substack]]</code> modifier erases the current parameters from the parent stack, allowing the current stack to rename its parameters freely and merge them back to the parent stack, renamed.
It is possible to leave a substack without merging it to the parent by using the <code>[[#leaving_substack|leaving_substack]]</code> modifier. In this case, at some point it will be necessary to call <code>[[#flushing|flushing]]</code> to merge the stack previously left unmerged. Alternatively, it will be possible to enter it again by calling <code>[[#entering_substack|entering_substack]]</code>, and finally merge it via <code>[[#merging_substack|merging_substack]]</code>.
An example will probably clarify the mechanism better than anything else:
<syntaxhighlight lang="wikitext">{{#invoke:params|new|<!-- Ignore the incoming parameters and manually assign some parameters (we will simulate the following incoming parameters: |one|two|three|four|foo=bar|hello=world ...) -->
imposing|1|one|
imposing|2|two|
imposing|3|three|
imposing|4|four|
imposing|foo|bar|
imposing|hello|world|
entering_substack|<!-- Enter into a substack (the `snapshotting` modifier will be automatically invoked for us) -->
with_name_not_matching|^%-?%d+$|<!-- Exclude numerical parameters -->
detaching_substack|<!-- Remove the current parameters from the parent stack -->
renaming_by_replacing|^.*$|This was called “%0”|1|<!-- Rename all parameters -->
merging_substack|
entering_substack|new|<!-- Enter into an empty substack -->
pulling|1|<!-- Pull the parameter named “1” from the parent -->
mapping_by_replacing|^.*$|This value once was “one”|1|<!-- Replace the content of all parameters -->
merging_substack|
for_each|[$#:$@]}}</syntaxhighlight>
The code above will result in:
: {{#invoke:params|new|<!-- Ignore the incoming parameters and manually assign some parameters (we will simulate the following incoming parameters: |one|two|three|four|foo=bar|hello=world ...) -->
imposing|1|one|
imposing|2|two|
imposing|3|three|
imposing|4|four|
imposing|foo|bar|
imposing|hello|world|
entering_substack|<!-- Enter into a substack (the `snapshotting` modifier will be automatically invoked for us) -->
with_name_not_matching|^%-?%d+$|<!-- Exclude numerical parameters -->
detaching_substack|<!-- Remove the current parameters from the parent stack -->
renaming_by_replacing|^.*$|This was called “%0”|1|<!-- Rename all parameters -->
merging_substack|
entering_substack|new|<!-- Enter into an empty substack -->
pulling|1|<!-- Pull the parameter named “1” from the parent -->
mapping_by_replacing|^.*$|This value once was “one”|1|<!-- Replace the content of all parameters -->
merging_substack|
for_each|[$#:$@]}}
{{vpad|1.5em|clear=none}}
Line 2,219 ⟶ 2,272:
; Brief
: ''Push a copy of the original (unmodified) parameter list to the
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|remembering|pipe function name}}</syntaxhighlight>
See <code>[[#snapshotting|snapshotting]]</code> for more information on the stacking mechanism.
{{vpad|1.5em|clear=none}}
Line 2,242 ⟶ 2,293:
; Brief
: ''Enter the first stack in the queue of parameter lists, or copy the current parameters into a substack if the queue is empty''
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|entering_substack|[new]|pipe function name}}</syntaxhighlight>
See <code>[[#snapshotting|snapshotting]]</code> for more information on the stacking mechanism. Once in a substack, it is possible to go back to the parent stack using two different modifiers: <code>[[#merging_substack|merging_substack]]</code> and <code>[[#leaving_substack|leaving_substack]]</code>.
{{vpad|1.5em|clear=none}}
Line 2,264 ⟶ 2,313:
; Brief
: ''Pull a single parameter from the parent stack or from the stack of the original parameters''
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|pulling|parameter name|pipe function name}}</syntaxhighlight>
See <code>[[#snapshotting|snapshotting]]</code> for more information on the stacking mechanism. If this modifer is not used in a substack, the parameter will be pulled from the original (unmodified) parameter list.
{{vpad|1.5em|clear=none}}
Line 2,286 ⟶ 2,333:
; Brief
: ''Remove from the
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|detaching_substack|pipe function name}}</syntaxhighlight>
This modifer can only be used in a substack. See <code>[[#snapshotting|snapshotting]]</code> for more information on the stacking mechanism.
{{vpad|1.5em|clear=none}}
Line 2,308 ⟶ 2,353:
; Brief
: ''Leave the current substack without merging it, and return to the parent stack''
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|leaving_substack|pipe function name}}</syntaxhighlight>
This modifer can only be used in a substack. See <code>[[#snapshotting|snapshotting]]</code> for more information on the stacking mechanism.
{{vpad|1.5em|clear=none}}
Line 2,330 ⟶ 2,373:
; Brief
: ''Leave the current stack and merging it with the parent stack, and return to the latter''
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|merging_substack|pipe function name}}</syntaxhighlight>
This modifer can only be used in a substack. See <code>[[#snapshotting|snapshotting]]</code> for more information on the stacking mechanism.
{{vpad|1.5em|clear=none}}
Line 2,351 ⟶ 2,392:
; Brief
: ''Merge the first stack in the queue of snapshotted parameters with the current stack.''
; Syntax
: <syntaxhighlight lang="wikitext" inline>{{#invoke:params|flushing|pipe function name}}</syntaxhighlight>
See <code>[[#snapshotting|snapshotting]]</code> for more information on the stacking mechanism.
{{vpad|1.5em|clear=none}}
Line 2,379 ⟶ 2,418:
This modifier can only appear in first position, or if substacks are present, immediately after the <code>[[#entering_substack|entering_substack]]</code> directive. When in first position its main purpose is that of extending the facilities offered by this module (e.g. <code>[[#mapping_by_replacing|mapping_by_replacing]]</code>, <code>[[#with_value_matching|with_value_matching]]</code>, etc.) to custom lists of strings, independently of the incoming parameters. When inside a stack, it signals that the snapshot of the current parameters must be ignored for that stack. The existence of the <code>new</code> modifier also facilitates debugging the module.
The newly created parameter stack can be populated via <code>[[#parsing|parsing]]</code>, <code>[[#imposing|imposing]]</code>, <code>[[#reinterpreting|reinterpreting]]</code> or <code>[[#providing|providing]]</code>. The incoming parameters can always be retrieved back using the <code>[[#remembering|remembering]]</code>
Examples:
| |||