Difference between revisions of "Template:For loop/doc"

From blackwiki
Jump to navigation Jump to search
(remove outdated interwiki comment)
imported>Colonies Chris
m (minor fixes)
 
(26 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
{{Documentation subpage}}
 
{{Documentation subpage}}
{{high use|35,000}}
+
{{high-use|35,000}}
<!-- PLEASE ADD CATEGORIES AT THE BOTTOM OF THIS PAGE. -->
+
<!-- Please add categories at the bottom of this page, and interwikis at Wikidata (see Wikipedia:Wikidata) -->
 +
 
 
{{lua|Module:For loop}}
 
{{lua|Module:For loop}}
[[Template:For loop]] implements a [[for loop]] or a [[foreach loop]].
+
This template implements a [[for loop]] or a [[foreach loop]].
  
This template calls a user-specified template (the "called template") once for each value in either 1) an iterated sequence or 2) an explicit list. A specified parameter of the called template is passed each value in the sequence or list (with optional pre- and postfixes attached). The first unnamed parameter of this template (the "separator") is output between calls to the called template. In addition to the one variable-valued parameter, other "static" parameters of the called template can be passed, with the same value in each iteration.
+
This template calls a user-specified template (the "called template") multiple times: once for each value in either 1) an iterated sequence or 2) an explicit list. Each value in the sequence or list is passed to the same specified parameter of the called template (the "variable parameter"). Optionally, pre- and postfixes can be attached to the passed values.
 +
 
 +
In addition to the specified variable parameter, other parameters of the called template ("static parameters") can be given a value which is the same in each iteration.
  
 
== Usage ==
 
== Usage ==
 
{| class="wikitable"
 
{| class="wikitable"
! Parameter !! Value !! Notes
+
! Group !! Parameter !! Meaning !! Default value
 
|-
 
|-
| '''1 (unnamed)''' || separator to output between calls (whitespace is preserved) || '''MANDATORY''' (may be blank)
+
! scope=row rowspan=3 | Mandatory
 +
| '''1 (unnamed)''' || separator to output between calls (may be blank; whitespace is preserved) ||
 
|-
 
|-
| '''call''' || template to call || '''MANDATORY'''
+
| '''call''' || template to call ||
 
|-
 
|-
| '''pv''' || name of the variable parameter to pass to the called template || '''MANDATORY''' unless it is the first unnamed parameter of the called template (use integers for other unnamed parameters)
+
| '''pv''' || name (or number) of the variable parameter of the called template || style="text-align: center" | 1
 +
|- style="border-top: 3px solid grey;"
 +
! scope=row rowspan=3 | Option 1:<br/>iterated sequence
 +
| '''start''' || first numeric value to pass to variable parameter || style="text-align: center" | 1
 
|-
 
|-
| '''pc[N]n''' || name (or number) of the Nth static parameter to pass to the called template ||
+
| '''stop''' || maximum numeric value for variable parameter ||
 
|-
 
|-
| '''pc[N]v''' || value of the Nth static parameter to pass to the called template ||
+
| '''by''' || iteration step size between values passed to variable parameter || style="text-align: center" | 1
|-
+
|- style="border-top: 3px solid grey;"
| '''prefix''' || static prefix prepended to each of the variable values ||
+
! scope=row rowspan=2 | Option 2:<br/>explicit values
 +
| '''(unnamed parameters)''' || | explicit values, given as separate parameters (whitespace is stripped) ||
 
|-
 
|-
| '''postfix''' || static postfix appended to each of the variable values ||
+
| '''skipBlanks''' || set to "true" to skip empty parameter values || style="text-align: center" | false
|-  
 
| '''substall''' || false to not substitute the called template when {{tl|for loop}} is substituted (defaults to true) ||
 
 
|- style="border-top: 3px solid grey;"
 
|- style="border-top: 3px solid grey;"
| '''start''' || first value to pass to variable parameter (defaults to 1) || rowspan=3 | '''Option 1: iterator'''
+
! scope=row rowspan=5 | Other optional<br/>parameters
 +
| '''pc[N]n''' || name (or number) of the Nth static parameter of the called template ||
 
|-
 
|-
| '''stop''' || maximum value for variable parameter
+
| '''pc[N]v''' || value for the Nth static parameter of the called template ||
 
|-
 
|-
| '''by''' || iteration step size between values passed to variable parameter (defaults to 1)
+
| '''prefix''' || static prefix prepended to each value passed to the variable parameter ||
|- style="border-top: 3px solid grey;"
 
| '''(unnamed)''' || | explicit list of variable values, given as separate parameters (whitespace is stripped) || rowspan=2 | '''Option 2: explicit values'''
 
 
|-
 
|-
| '''skipBlanks''' || true to skip empty parameter values (defaults to false)
+
| '''postfix''' || static postfix appended to each value passed to the variable parameter ||
 +
|-
 +
| '''substall''' || set to "false" to not substitute the called template when {{tl|for loop}} is substituted || style="text-align: center" | true
 
|}
 
|}
  
Note that ''either'' iterator parameters (option 1) ''or'' an explicit list of values (option 2) may be used, but not both.
+
''Either'' option 1 (iteration parameters) ''or'' option 2 (an explicit list of values) may be used, but not both.
  
The separator is the first unnamed parameter, allowing it to start and/or end with [[Help:newlines and spaces|newlines and spaces]]. The separator is output ''between'' calls to the template named in <code>|call=</code>. It is not output after the last call to that template. The separator parameter is prior to the value list. If a value in the list contains an equals sign, use {{tlx|{{=}}}} (see [[Help:Template#Usage hints and workarounds|Help:Template]]).  If you do not use {{tlx|{{=}}}}, the list must use named parameters, at least from that point. If you use named parameters, note that the first value is parameter 2 (e.g. <code>|2=Your1stValue</code>), because parameter 1 is the separator. If the separator contains an equals sign, {{tlx|{{=}}}} should also be used. Alternately, the separator can similarly be prefixed with "1=", but in that case it cannot contain newlines and spaces at the start and end. Also, if you use named parameters, you must not skip any numbers. The loop will terminate after the first absent numbered parameter. (Note that parameters can be blank but not absent; blank parameters are read as normal.)
+
The first unnamed parameter, prior to any explicit values, is a separator. The separator is a string that is output ''between'' calls to the template named in <code>|call=</code>. It is not output after the last call.  
  
==Examples==
+
=== Caution ===
 +
*The separator can be prefixed with "1=", but in that case it cannot contain newlines and spaces at the start and end.
 +
*If any parameter value contains an equals sign, use {{tlx|{{=}}}} (see [[Help:Template#Usage hints and workarounds|Template Usage hints and workarounds]]).
 +
*If you use named parameters, note that the first value is parameter 2 (e.g. <code>|2=Your1stValue</code>), because parameter 1 is the separator.
 +
*If you use named parameters, you must not skip any numbers. The loop will terminate after the first absent numbered parameter. (Parameters can be blank, but not absent.)
 +
 
 +
=== Substitution ===
 +
The current Lua-based template supports [[WP:SUBST|substitution]]. If {{para|substall|no}} is not specified, then substituting the template will substitute everything, including the call to the template passed in {{para|call}}. If it is specified, then the template substitutes into a sequence of calls to the template specified.
 +
 
 +
Example: {{tlxs|for loop|sep |01|02|03|04|05|06|07|call{{=}}1x}} -> <code><nowiki>01sep 02sep 03sep 04sep 05sep 06sep 07</nowiki></code>, {{tlxs|for loop|sep |01|02|03|04|05|06|07|call={{1x}}|substall{{=}}no}} -> <code><nowiki>{{1x|01}}sep {{1x|02}}sep {{1x|03}}sep {{1x|04}}sep {{1x|05}}sep {{1x|06}}sep {{1x|07}}</nowiki></code>
 +
 
 +
For full substitution [[Special:ExpandTemplates]] can also be used.
 +
 
 +
== Examples ==
 
{| class="wikitable", border=1
 
{| class="wikitable", border=1
 +
!Form
 
!Code
 
!Code
 
!Explanation
 
!Explanation
 
!Result
 
!Result
 
|-
 
|-
 +
! scope=row | Iterator
 
|
 
|
 
<pre>{{for loop|&|call = spanbox
 
<pre>{{for loop|&|call = spanbox
 +
  |pv = font size
 +
  |start=10|stop=52|by=8
 +
  |postfix = px
 
   |pc1n = 1
 
   |pc1n = 1
 
   |pc1v = A
 
   |pc1v = A
 
   |pc2n = background
 
   |pc2n = background
 
   |pc2v = yellow
 
   |pc2v = yellow
  |pv = font size
 
  |postfix = px
 
  |start=10|stop=52|by=8
 
 
}}</pre>
 
}}</pre>
| Outputting "&" between calls, call the template "spanbox" with values:
+
| Call the template "spanbox" with values:
 +
*font size = "[N]px", where N takes values starting with 10 and increasing by 8 while remaining less than or equal to 52
 
*1 (first unnamed parameter) = "A"
 
*1 (first unnamed parameter) = "A"
 
*background = "yellow"
 
*background = "yellow"
*font size = "[N]px", where N takes values starting with 10 and increasing by 8 while remaining less than or equal to 52
+
Separating outputs with "&"
 
|{{for loop|&|call = spanbox
 
|{{for loop|&|call = spanbox
 +
  |pv = font size
 +
  |start=10|stop=52|by=8
 +
  |postfix = px
 
   |pc1n = 1
 
   |pc1n = 1
 
   |pc1v = A
 
   |pc1v = A
 
   |pc2n = background
 
   |pc2n = background
 
   |pc2v = yellow
 
   |pc2v = yellow
  |pv = font size
 
  |postfix = px
 
  |start=10|stop=52|by=8
 
 
}}
 
}}
 
|-
 
|-
 +
! scope=row | Explicit values
 
|<pre>{{for loop|, |call=1x
 
|<pre>{{for loop|, |call=1x
 
|prefix=1
 
|prefix=1
Line 101: Line 125:
 
|}
 
|}
  
===Other examples===
+
=== Other examples with explicit values ===
 
 
 
<code><nowiki>{{for loop|-|a|3||c|g|call=3x}}</nowiki></code> using {{tiw|3x}} gives
 
<code><nowiki>{{for loop|-|a|3||c|g|call=3x}}</nowiki></code> using {{tiw|3x}} gives
  
Line 167: Line 190:
 
|11{{=}}{{=}}{{=}}|12|13|14|15|16|17|18|19|call=1x}}<-end
 
|11{{=}}{{=}}{{=}}|12|13|14|15|16|17|18|19|call=1x}}<-end
  
== Legacy code ==
+
== Notes about legacy codes ==
 
+
This template is currently in its third incarnation. It now uses the [[WP:Lua|Lua]] code at [[Module:For loop]]. It was ported to Lua from [[mw:Help:Extension:ParserFunctions|ParserFunctions]]. There was also a previous version with a named "sep" parameter to specify the separator value. The template was originally based on [[m:Template:For|Template:For on meta]]. The template name was changed because there was already a [[Template:For|Template:For on Wikipedia]].
This template is currently in its third incarnation. It now uses the [[WP:Lua|Lua]] code at [[Module:ForLoop]]. It was ported to Lua from [[mw:Help:Extension:ParserFunctions|ParserFunctions]]. There was also a previous version with a named "sep" parameter to specify the separator value. The template was originally based on [[:m:Template:For]]. The template name was changed because there was already a [[Template:For]] on Wikipedia.
 
  
 
The old versions were limited to 150 variable values and four fixed parameters. There are no such limits in the current version. Also, in the first version the "sep" parameter didn't allow whitespace in the separator value. This was fixed with the second version and was retained in the current version.
 
The old versions were limited to 150 variable values and four fixed parameters. There are no such limits in the current version. Also, in the first version the "sep" parameter didn't allow whitespace in the separator value. This was fixed with the second version and was retained in the current version.
  
== Substitution ==
+
== See also ==
 
 
The current Lua-based template supports [[WP:SUBST|substitution]]. If {{para|substall|no}} is not specified, then substituting the template will substitute everything, including the call to the template passed in {{para|call}}. If it is specified, then the template substitutes into a sequence of calls to the template specified.
 
 
 
Example: {{tlsx|for loop|sep |01|02|03|04|05|06|07|call{{=}}1x}} -> <code><nowiki>01sep 02sep 03sep 04sep 05sep 06sep 07</nowiki></code>, {{tlsx|for loop|sep |01|02|03|04|05|06|07|call={{1x}}|substall{{=}}no}} -> <code><nowiki>{{1x|01}}sep {{1x|02}}sep {{1x|03}}sep {{1x|04}}sep {{1x|05}}sep {{1x|06}}sep {{1x|07}}</nowiki></code>
 
 
 
For full substitution [[Special:ExpandTemplates]] can also be used.
 
 
 
 
 
==See also==
 
 
*[[mw:Template:Fe]]
 
*[[mw:Template:Fe]]
*{{tim|foreach}}
+
*[[mw:Template:foreach]]
 
*{{tim|tblb}}
 
*{{tim|tblb}}
 
*{{tiw|for nowiki}}
 
*{{tiw|for nowiki}}
Line 194: Line 207:
 
*[[mw:Extension:LoopFunctions]]
 
*[[mw:Extension:LoopFunctions]]
  
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||
+
<includeonly>{{sandbox other||
<!-- CATEGORIES HERE, THANKS -->
+
<!-- Add categories below this line, and interwikis at Wikidata -->
 
[[Category:Wikipedia formatting and function templates]]
 
[[Category:Wikipedia formatting and function templates]]
 
}}</includeonly>
 
}}</includeonly>

Latest revision as of 20:52, 30 August 2020

This template implements a for loop or a foreach loop.

This template calls a user-specified template (the "called template") multiple times: once for each value in either 1) an iterated sequence or 2) an explicit list. Each value in the sequence or list is passed to the same specified parameter of the called template (the "variable parameter"). Optionally, pre- and postfixes can be attached to the passed values.

In addition to the specified variable parameter, other parameters of the called template ("static parameters") can be given a value which is the same in each iteration.

Usage

Group Parameter Meaning Default value
Mandatory 1 (unnamed) separator to output between calls (may be blank; whitespace is preserved)
call template to call
pv name (or number) of the variable parameter of the called template 1
Option 1:
iterated sequence
start first numeric value to pass to variable parameter 1
stop maximum numeric value for variable parameter
by iteration step size between values passed to variable parameter 1
Option 2:
explicit values
(unnamed parameters) explicit values, given as separate parameters (whitespace is stripped)
skipBlanks set to "true" to skip empty parameter values false
Other optional
parameters
pc[N]n name (or number) of the Nth static parameter of the called template
pc[N]v value for the Nth static parameter of the called template
prefix static prefix prepended to each value passed to the variable parameter
postfix static postfix appended to each value passed to the variable parameter
substall set to "false" to not substitute the called template when {{for loop}} is substituted true

Either option 1 (iteration parameters) or option 2 (an explicit list of values) may be used, but not both.

The first unnamed parameter, prior to any explicit values, is a separator. The separator is a string that is output between calls to the template named in |call=. It is not output after the last call.

Caution

  • The separator can be prefixed with "1=", but in that case it cannot contain newlines and spaces at the start and end.
  • If any parameter value contains an equals sign, use {{=}} (see Template Usage hints and workarounds).
  • If you use named parameters, note that the first value is parameter 2 (e.g. |2=Your1stValue), because parameter 1 is the separator.
  • If you use named parameters, you must not skip any numbers. The loop will terminate after the first absent numbered parameter. (Parameters can be blank, but not absent.)

Substitution

The current Lua-based template supports substitution. If |substall=no is not specified, then substituting the template will substitute everything, including the call to the template passed in |call=. If it is specified, then the template substitutes into a sequence of calls to the template specified.

Example: {{subst:for loop|sep|01|02|03|04|05|06|07|call=1x}} -> 01sep 02sep 03sep 04sep 05sep 06sep 07, {{subst:for loop|sep|01|02|03|04|05|06|07|substall=no}} -> {{1x|01}}sep {{1x|02}}sep {{1x|03}}sep {{1x|04}}sep {{1x|05}}sep {{1x|06}}sep {{1x|07}}

For full substitution Special:ExpandTemplates can also be used.

Examples

Form Code Explanation Result
Iterator
{{for loop|&|call = spanbox
  |pv = font size
  |start=10|stop=52|by=8
  |postfix = px
  |pc1n = 1
  |pc1v = A
  |pc2n = background
  |pc2v = yellow
}}
Call the template "spanbox" with values:
  • font size = "[N]px", where N takes values starting with 10 and increasing by 8 while remaining less than or equal to 52
  • 1 (first unnamed parameter) = "A"
  • background = "yellow"

Separating outputs with "&"

Lua error: expandTemplate: template "spanbox" does not exist.
Explicit values
{{for loop|, |call=1x
|prefix=1
|00|01|02|03|04|05|06|07|08|09
|10|11|12|13|14|15|16|17|18|19
|20|21|22|23|24|25|26|27|28|29
|30|31|32|33|34|35|36|37|38|39
|40|41|42|43|44|45|46|47|48|49
|50|51|52|53|54|55|56|57|58|59
|60|61|62|63|64|65|66|67|68|69
|70|71|72|73|74|75|76|77|78|79
|80|81|82|83|84|85|86|87|88|89
|90|91|92|93|94|95|96|97|98|99
}}
Call the template "1x" with values "1[NN]", where NN = "00" through "99" (given explicitly), separating the outputs with the string ", " 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190, 191, 192, 193, 194, 195, 196, 197, 198, 199

Other examples with explicit values

{{for loop|-|a|3||c|g|call=3x}} using Template:3x (backlinks edit) gives

aaa-333-ccc-ggg

{{for loop|

|a|3||c|g|call=3x}} gives

aaa

333

ccc

ggg

{|class="wikitable sortable"
|-
!Test
|-
| {{for loop|
{{!}}-
{{!}} |a|b|c|d|e|call=3x}}
|}

gives:

Test
aaa
bbb
ccc
ddd
eee
{{for loop| |01|02|03|04|05|06|07|08|09|10|11|12|13|14|15|16|17|18|19
|20|21|22|23|24|25|26|27|28|29|30|31|32|33|34|35|36|37|38|39
|40|41|42|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59
|60|61|62|63|64|65|66|67|68|69|70|71|72|73|74|75|76|77|78|79
|80|81|82|83|84|85|86|87|88|89|90|91|92|93|94|95|96|97|98|99
|100|101|102|103|104|105|106|107|108|109|110|111|112|113|114|115|116|117|118|119
|120|121|122|123|124|125|126|127|128|129|130|131|132|133|134|135|136|137|138|139
|140|141|142|143|144|145|146|147|148|149|150|151|152|153|154|call=1x}}

gives:

01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154

begin->{{for loop|{{=}} |01|02|03|04|05|06|07|08|09|10
|11{{=}}{{=}}{{=}}|12|13|14|15|16|17|18|19|call=1x}}<-end

gives:

begin->01= 02= 03= 04= 05= 06= 07= 08= 09= 10= 11==== 12= 13= 14= 15= 16= 17= 18= 19<-end

Notes about legacy codes

This template is currently in its third incarnation. It now uses the Lua code at Module:For loop. It was ported to Lua from ParserFunctions. There was also a previous version with a named "sep" parameter to specify the separator value. The template was originally based on Template:For on meta. The template name was changed because there was already a Template:For on Wikipedia.

The old versions were limited to 150 variable values and four fixed parameters. There are no such limits in the current version. Also, in the first version the "sep" parameter didn't allow whitespace in the separator value. This was fixed with the second version and was retained in the current version.

See also