檢視模組:TemplateParameters/doc 的原始碼

{{High-use|117801}}
本模組可以將參數填入以普通模板參數定義的[[格式化字符串]]
== 設計緣由 ==
自定義的模板參數讀取之構想早在2018年11月就已提出。當時數學類條目面臨大量[[MP:114.27]]的似是而非的破壞，不易查證真偽，因此建立了[[Module:Number]]（及[[複數 (數學)|複變]]部分的[[Module:Complex Number]]，如[[高斯整數]][[因數分解|分解]]）來自動計算並輸出數學性質，避免遭[[MP:114.27]]竄改為錯誤資訊而不易查證（例如多1少1的破壞難以察覺和驗證），但有用戶認為輸出固定字串無法被修改或添加註解、參考文獻不妥，因此出現了[[格式化字符串]]的需求，而部分用戶認為，應儘量是要設計一般維基人都能編輯的語法，因此最後[[模块讨论:Number#請問&#123;&#123;#invoke:Number&#124;numberDivisorInformation&#124;1=28&#124;use_math=yes&#125;&#125;是什麼東西？模板嗎？|決議選擇]]wikitext模板中的模板參數語法，但當時此功能獨自分散在各個需要[[格式化字符串]]功能的模組裡，例如[[Module:Number]]、[[Module:PeriodicTable]]和[[Module:Delcat]]等地方。

最初的版本僅包含簡單文字替換，-{只}-能處理已知數量的參數，而在2019年6月，有用戶問到能否不寫新的模組、也不使用大量<code><nowiki>{{#if:}}</nowiki></code>實現，因此認為可以把自動讀取參數填入[[格式化字符串]]的功能獨立出來（即建立本模組），順便提供些特殊參數解析功能，如參數批次trim和數字解析功能（根據[[MP:TG1]]請求用於{{tl|Infobox 日本的町村}}）。

== 使用說明 ==
本模組主要是提供wikitext模板中的模板參數一個API，而非設計給其他Lua函數使用，因此專門給lua呼叫的函數較少。

本模組包括的函數如下：
* [[#getFormatingStringByArgument|getFormatingStringByArgument]] ：固定參數的[[格式化字符串]]方法
* [[#FormatingArguments|FormatingArguments]] ：不定參數的[[格式化字符串]]方法
* [[#containsNumber|containsNumber]] ：判斷參數是否包含數字
* [[#getNumberValue|getNumberValue]] ：析出參數包含的數字
* [[#arg_to_spstr與pass_spstr|arg_to_spstr與pass_spstr]] ：提供不定參數迭代（跨層傳遞）的一種方式
* [[#argTrim|argTrim]] ：參數批次Trim 或 已展開的參數避免<code><nowiki>|</nowiki></code>後方內容遺失的方法
* [[#listArguments|listArguments]] ：列出所有接收到的參數，提供模板可見的除錯方式。
* [[#call|call]] ：將模板參數轉為Lua參數的方法，提供呼叫一些不支援以模板參數呼叫之Module的功能。
* [[#templateArgWarp|templateArgWarp]] ：將模組調用轉換為另一個模板且輸入參數為從外部模板(父模板)讀取之參數的未解析字串，用於替換引用。
* [[#makeTemplateParameter|makeTemplateParameter]] ：產生模板參數的未解析字串，如<code><nowiki>{{{arg}}}</nowiki></code>

== 用法 ==
=== getFormatingStringByArgument ===
功能：直接將參數透過簡單文字替換填入形如<code><nowiki>{{{X}}}</nowiki></code>的位置內
*<code><nowiki>{{</nowiki>#invoke:<span style="font-size: .5em;">TemplateParameters</span> | <span style="font-size: .6em;">getFormatingStringByArgument</span> | 在{{{學科}}}中，{{{名稱}}}是一種{{{種類}}} | 學科=數學 | 名稱=三角形 | 種類=多邊形<nowiki>}}</nowiki></code>
*:顯示為「{{#invoke:TemplateParameters|getFormatingStringByArgument|在{{{學科}}}中，{{{名稱}}}是一種{{{種類}}}|學科=數學|名稱=三角形|種類=多邊形}}」
;用途
*[[Module:Number]]中，[[模块:Number/doc#參數|客製化的性質輸出格式]]。
*[[Module:PeriodicTable]]中，選擇要在[[元素週期表]]輸出的元素性質。

=== FormatingArguments ===
功能：將未知數量的參數根據<code><nowiki>{{{X}}}</nowiki></code>規則依序填入給定的字符串中。
*模板中輸入
<pre>{{#invoke:TemplateParameters|FormatingArguments|格式=這是第{\{\{1}\}\}個參數；|count=1|usingConditionalExpressions=yes}}</pre>
*叫用模板<code><nowiki>{{</nowiki>{{gray|<small><模板名稱></small>}}<nowiki>|一|二|三|四}}</nowiki></code>
*顯示為：「{{虛擬模板| code={\{#invoke:TemplateParameters{{!}}FormatingArguments{{!}}格式=這是第{\\{\\{1}\\}\\}個參數；{{!}}count=1{{!}}usingConditionalExpressions=yes}\}|一|二|三|四}}」
*解釋：
**模板中「格式」參數原本為<code><nowiki>這是第{{{1}}}個參數；</nowiki></code>，透過加入[[跳脫字元]]防止先被解析後，透過FormatingArguments函數將傳入模組讀<u>所有參數</u>依序填入，不必透過大量的<code><nowiki>{{#if:{{{N}}}</nowiki></code>就能達成不定數量的參數傳遞。
----
*模板中輸入
<pre>{{#invoke:TemplateParameters|FormatingArguments|格式=*:[[畢氏三元數]]：{\{#tag:math{{!}}\\left({\{\{1}\}\},{\{\{2}\}\} ,{\{\{3}\}\}\\right)}\}\n|count=3|usingConditionalExpressions=yes}}</pre>
*叫用模板<code><nowiki>{{</nowiki>{{gray|<small><模板名稱></small>}}<nowiki>|3|4|5|5|12|13|7|24|25}}</nowiki></code>
*顯示為：{{虛擬模板| code={\{#invoke:TemplateParameters{{!}}FormatingArguments{{!}}格式=*:[[畢氏三元數]]：{\\{#tag:math{\{!}\}\\\\left({\\{\\{1}\\}\\},{\\{\\{2}\\}\\} ,{\\{\\{3}\\}\\}\\\\right)}\\}\\n{{!}}count=3{{!}}usingConditionalExpressions=yes}\}|3|4|5|5|12|13|7|24|25}}
*解釋：
**模板中「格式」參數原本為<code><nowiki>*:[[畢氏三元數]]：{{#tag:math|\left({{{1}}},{{{2}}} ,{{{3}}}\right)}}\n</nowiki></code>。
**:指定了數量為3（<code><nowiki> | count=3</nowiki></code>）後，會將參數每三個一組代入<code><nowiki>{{{1}}}</nowiki></code>、<code><nowiki>{{{2}}}</nowiki></code>和<code><nowiki>{{{3}}}</nowiki></code>。
----
;格式字串中支援的參數
下面為FormatingArguments支援的參數，若有同名參數可能會影響運作
*讀取不定參數：
**<code><nowiki>{{{1}}}</nowiki></code>、<code><nowiki>{{{2}}}</nowiki></code>、<code><nowiki>{{{3}}}</nowiki></code>...即以組為單位讀取不定參數。
**:例如<code><nowiki>{{|1|2|3|4|5|6|7|8|9}}</nowiki></code>如果設定為每組3個參數，
**::則第一組的<code><nowiki>{{{1}}}</nowiki></code>、<code><nowiki>{{{2}}}</nowiki></code>、<code><nowiki>{{{3}}}</nowiki></code>分別會代入1、2和3；
**::第二組的<code><nowiki>{{{1}}}</nowiki></code>、<code><nowiki>{{{2}}}</nowiki></code>、<code><nowiki>{{{3}}}</nowiki></code>分別會代入4、5和6
**:以此類推。
**<code><nowiki>{{{</nowiki>{{新增條文|1=count+1}}<nowiki>}}}</nowiki></code>、<code><nowiki>{{{</nowiki>{{新增條文|1=count+2}}<nowiki>}}}</nowiki></code>、<code><nowiki>{{{</nowiki>{{新增條文|1=count+3}}<nowiki>}}}</nowiki></code>...讀取下一組的不定參數。
**:例如<code><nowiki>{{|1|2|3|4|5|6|7|8|9}}</nowiki></code>如果設定為每組3個參數，此時<code><nowiki>{{{</nowiki>{{新增條文|1=count+1}}<nowiki>}}}</nowiki></code>即為<code><nowiki>{{{4}}}</nowiki></code>
**::則第一組的<code><nowiki>{{{4}}}</nowiki></code>、<code><nowiki>{{{5}}}</nowiki></code>、<code><nowiki>{{{6}}}</nowiki></code>分別會代入4、5和6；
**::則第二組的<code><nowiki>{{{4}}}</nowiki></code>、<code><nowiki>{{{5}}}</nowiki></code>、<code><nowiki>{{{6}}}</nowiki></code>分別會代入7、8和9；
**::則第三組的<code><nowiki>{{{4}}}</nowiki></code>、<code><nowiki>{{{5}}}</nowiki></code>、<code><nowiki>{{{6}}}</nowiki></code>因為沒有第四組，而會變成空值、預設參數或保持原樣（即<code><nowiki>{{{4}}}</nowiki></code>）；
**<code><nowiki>{{{0}}}</nowiki></code>、<code><nowiki>{{{-1}}}</nowiki></code>、<code><nowiki>{{{-2}}}</nowiki></code>...讀取前一組的不定參數。
**:例如<code><nowiki>{{|1|2|3|4|5|6|7|8|9}}</nowiki></code>如果設定為每組3個參數
**::則第一組的<code><nowiki>{{{0}}}</nowiki></code>、<code><nowiki>{{{-1}}}</nowiki></code>、<code><nowiki>{{{-2}}}</nowiki></code>因為第一組沒有前一組，而會變成空值、預設參數或保持原樣（即<code><nowiki>{{{0}}}</nowiki></code>）；
**::則第二組的<code><nowiki>{{{0}}}</nowiki></code>、<code><nowiki>{{{-1}}}</nowiki></code>、<code><nowiki>{{{-2}}}</nowiki></code>分別會代入3、2和1；
**::則第三組的<code><nowiki>{{{0}}}</nowiki></code>、<code><nowiki>{{{-1}}}</nowiki></code>、<code><nowiki>{{{-2}}}</nowiki></code>分別會代入6、5和4；
**:以此類推。
**<code><nowiki>{{{random}}}</nowiki></code>：位於本組的隨機參數。
**<code><nowiki>{{{allRandom}}}</nowiki></code>：所有參數的隨機參數。
**<code><nowiki>{{{last}}}</nowiki></code>：本組的最後一個參數。
*判斷用參數
**<code><nowiki>{{{isFirst}}}</nowiki></code>：如果這是第一組參數則為<code>1</code>，否則為空值<code></code>。
**<code><nowiki>{{{isLast}}}</nowiki></code>：如果這是最後一組參數則為<code>1</code>，否則為空值<code></code>。
**<code><nowiki>{{{count}}}</nowiki></code>：參數組的數量。
**<code><nowiki>{{{argGroupID}}}</nowiki></code>：返回目前作用中的參數是第幾組。
==== Subst方法 ====
此模板可以使用Subst，不過若用<code><nowiki><now</nowiki>iki></now<nowiki>iki></nowiki></code>搭配<code><nowiki> | delnowiki = </nowiki></code>參數的話會導致替換失敗。
*替代方案可以使用[[跳脫字元]]（如<code><nowiki>\{</nowiki></code>、<code><nowiki>\}</nowiki></code>等）以及[[H:魔術字]]（如{{tlx|!}}、<code><nowiki>{{ {{{|safesubst:}}}!}}</nowiki></code>、{{tlx|=}}、<code><nowiki>{{ {{{|safesubst:}}}=}}</nowiki></code>等）
*若覺得編輯困難可以使用 子頁面搭配<code><nowiki>{{msgnw:模板名}}</nowiki></code>以及<code><nowiki> | delmsgnw = </nowiki></code>參數 來完成
**詳細使用方式可參考[[User:A2569875/SubstTest]]搭配[[User:A2569875/SubstTest/Cell]]的範例。
**使用<code><nowiki>{{msgnw:模板名}}</nowiki></code>需要{{注意}}的是：由於使用msgnw，因此<nowiki><noinclude></noinclude></nowiki>等標記無效，因此不應該在該子模板中直接加入註解或<nowiki>{{Doc}}</nowiki>的內容，需要使用{{tlx|ifsubst}}才能運作，例如<code><nowiki>{{ {{{|safesubst:}}}ifsubst||<noinclude>{{documentation}}</noinclude>}}</nowiki></code>。
**:或者：
<pre>
{{ {{{|safesubst:}}}ifsubst||<noinclude>
不被包含引用的部分
</noinclude>}}
</pre>

=== containsNumber ===
功能：用於確定一個參數內是否有包含阿拉伯數字
*<code><nowiki>{{#invoke:TemplateParameters|containsNumber|</nowiki>{{新增條文|1=hijk42lm}}<nowiki>}}</nowiki></code>→「{{#invoke:TemplateParameters|containsNumber|hijk42}}」
*<code><nowiki>{{#invoke:TemplateParameters|containsNumber|</nowiki>{{新增條文|1=hijklm}}<nowiki>}}</nowiki></code>→「{{#invoke:TemplateParameters|containsNumber|hijklm}}」
用法
*<code><nowiki>{{#if:{{#invoke:TemplateParameters|containsNumber|</nowiki>{{新增條文|1=hijk42lm}}<nowiki>}}|有數字|沒數字}}</nowiki></code>→「{{#if:{{#invoke:TemplateParameters|containsNumber|hijk42lm}}|有數字|沒數字}}」
*<code><nowiki>{{#if:{{#invoke:TemplateParameters|containsNumber|</nowiki>{{新增條文|1=hijklm}}<nowiki>}}|有數字|沒數字}}</nowiki></code>→「{{#if:{{#invoke:TemplateParameters|containsNumber|hijklm}}|有數字|沒數字}}」
=== getNumberValue ===
功能：嘗試從一個參數內讀出一個阿拉伯數字，若讀不出來，則傳回0
*<code><nowiki>{{#invoke:TemplateParameters|getNumberValue|</nowiki>{{新增條文|1=hijk42lm}}<nowiki>}}</nowiki></code>→「{{#invoke:TemplateParameters|getNumberValue|hijk42}}」
*<code><nowiki>{{#invoke:TemplateParameters|getNumberValue|</nowiki>{{新增條文|1=hijklm}}<nowiki>}}</nowiki></code>→「{{#invoke:TemplateParameters|getNumberValue|hijklm}}」
用法
*<code><nowiki>{{#expr: </nowiki>{{新增條文|1=hijk42lm}}<nowiki> }}</nowiki></code>→「{{#expr:hijk42lm }}」
*<code><nowiki>{{#expr:{{#invoke:TemplateParameters|getNumberValue|</nowiki>{{新增條文|1=hijk42lm}}<nowiki>}} }}</nowiki></code>→「{{#expr:{{#invoke:TemplateParameters|getNumberValue|hijk42lm}} }}」
*<code><nowiki>{{#expr:</nowiki>{{新增條文|1=hijklm}}<nowiki> }}</nowiki></code>→「{{#expr:hijklm }}」
*<code><nowiki>{{#expr:{{#invoke:TemplateParameters|getNumberValue|</nowiki>{{新增條文|1=hijklm}}<nowiki>}} }}</nowiki></code>→「{{#expr:{{#invoke:TemplateParameters|getNumberValue|hijklm}} }}」
=== arg_to_spstr與pass_spstr ===
功能：arg_to_spstr會將參數轉變成一個可供pass_spstr使用的字串；pass_spstr可以將arg_to_spstr給出的參數套入模板語法
:設計動機：批次大量傳送參數的方案
<pre>
{{#invoke:TemplateParameters|pass_spstr
 | code = {{{1}}}-{{{2}}}-{{{3}}}
 | args = {{#invoke:TemplateParameters|arg_to_spstr|A|B|C}}
}}
</pre>
:顯示為「{{#invoke:TemplateParameters|pass_spstr
 | code = {{{1}}}-{{{2}}}-{{{3}}}
 | args = {{#invoke:TemplateParameters|arg_to_spstr|A|B|C}}
}}」
=== argTrim ===
功能：適用於本系列模板的trim方案（delnowiki可正常使用{{tl|trim}}），{{tl|trim}}會導致使用「{{tl|!}}」的後方內容被捨棄
*一般Trim
**模板內容<code><nowiki>{{#invoke:TemplateParameters|FormatingArguments|格式=[\[:{\{Trim{{!}} {\{\{1}\}\} }\}]\]|count=1|usingConditionalExpressions=yes}}</nowiki></code>
**叫用模板<code><nowiki>{{</nowiki>{{gray|<small><模板名稱></small>}}<nowiki>|一{{!}}遺失的內容}}</nowiki></code>
**顯示為：「<!--
-->{{虛擬模板
|code=<nowiki>{{#invoke:TemplateParameters|FormatingArguments|格式=[\[:{\{Trim{{!}} {\{\{1}\}\} }\}]\]|count=1|usingConditionalExpressions=yes}}</nowiki>
|delnowiki=1|一{{!}}遺失的內容
}}<!--
-->」
*一般Trim + delnowiki
**模板內容<code><nowiki>{{#invoke:TemplateParameters|FormatingArguments|格式=&#60;nowiki&#62;[[:{{Trim| {{{1}}} }}]]&#60;/nowiki&#62;|delnowiki=1|count=1|usingConditionalExpressions=yes}}</nowiki></code>
**叫用模板<code><nowiki>{{</nowiki>{{gray|<small><模板名稱></small>}}<nowiki>|一{{!}}遺失的內容}}</nowiki></code>
**顯示為：「<!--
-->{{虛擬模板
|code=<nowiki>{{#invoke:TemplateParameters|FormatingArguments|格式=[[:{{Trim|{{{1}}} }}]]|delnowiki=1|count=1|usingConditionalExpressions=yes}}</nowiki>
|delnowiki=1|一{{!}}遺失的內容
}}<!--
-->」
*使用argTrim 
**模板內容<code><nowiki>{{#invoke:TemplateParameters|FormatingArguments|格式=[\[:{{((}}#invoke:TemplateParameters{{!}}argTrim{{!}}{{{1}}} {{))}}]\]|count=1|usingConditionalExpressions=yes}}</nowiki></code>
**叫用模板<code><nowiki>{{</nowiki>{{gray|<small><模板名稱></small>}}<nowiki>|一{{!}}遺失的內容}}</nowiki></code>
**顯示為：「<!--
-->{{虛擬模板
|code=<nowiki>{{#invoke:TemplateParameters|FormatingArguments|格式=[\[:{{((}}#invoke:TemplateParameters{{!}}argTrim{{!}}{{{1}}} {{))}}]\]|delnowiki=1|count=1|usingConditionalExpressions=yes}}</nowiki>
|delnowiki=1|一{{!}}遺失的內容
}}<!--
-->」
*使用argTrim + delnowiki
**模板內容<code><nowiki>{{#invoke:TemplateParameters|FormatingArguments|格式=&#60;nowiki&#62;[[:{{#invoke:TemplateParameters|argTrim|{{{1}}} }}]]&#60;/nowiki&#62;[\[:{\{#invoke:TemplateParameters{{!}}argTrim{{!}}{{{1}}} }\}]\]|count=1|usingConditionalExpressions=yes}}</nowiki></code>
**叫用模板<code><nowiki>{{</nowiki>{{gray|<small><模板名稱></small>}}<nowiki>|一{{!}}遺失的內容}}</nowiki></code>
**顯示為：「<!--
-->{{虛擬模板
|code=<nowiki>{{#invoke:TemplateParameters|FormatingArguments|格式=[[:{{#invoke:TemplateParameters|argTrim|{{{1}}} }}]]|delnowiki=1|count=1|usingConditionalExpressions=yes}}</nowiki>
|delnowiki=1|一{{!}}遺失的內容
}}<!--
-->」

=== listArguments ===
功能：列出模板接收到的參數

用途：偵錯用
*輸入<code><nowiki>{{#invoke:TemplateParameters|listArguments|A|B|C|99=D|E=F}}</nowiki></code>
*顯示為：
<div style="background:#eee">
{{#invoke:TemplateParameters|listArguments|A|B|C|99=D|E=F}}
</div>

=== call ===
'''功能'''：將模板參數轉為Lua參數的方法，提供呼叫一些不支援以模板參數呼叫之Module。

'''用途'''：能讓一些未提供模板參數呼叫之Module在不建立新Module的情況下由模板調用。
:例如[[Module:yesno]]目前暫未支援由模板直接調用。
*輸入<code><nowiki>{{#invoke:TemplateParameters|call|Module:yesno|T}}</nowiki></code>
*顯示為：「{{#invoke:TemplateParameters|call|Module:yesno|T}}」（參見下方[[#call#回傳值|#回傳值]]子章節）

'''參數'''：
*第一參數為模板與模組名稱，以點「<code> <nowiki> . </nowiki> </code>」運算子來從模組中獲得函數名稱，如「<code>Module:Foo.bar</code>」指的是[[Module:Foo]]中的{{code|lang=lua|function bar( )}}，需要注意的是，為了提升效能，因此判斷是用簡單的字串分割達成，因此若模組名稱含有點「<code> <nowiki> . </nowiki> </code>」符號，則無法使用此功能。
*其他參數則會依序傳入指定的模組函數中

{{anchor|call#回傳值}}'''回傳值'''：
*若模組回傳值為[[數字]]或[[字串]]，則會直接顯示結果；
*若模組回傳值為[[布林值]]則：{{code|lang=lua|true}}以「<code>1</code>」表示，否則輸出空字串。這是為了讓結果能給{{tlxm|#if|<nowiki></nowiki>}}使用
*若模組沒有回傳值則輸出空字串；
*若模組回傳值為其他物件，則會嘗試將物件轉為[[JSON]]後輸出。此步驟有可能因為物件中包含了無法JSON化的物件導致失敗。

'''選項'''：
*<code> <nowiki> | isJSON = </nowiki> </code>：將所有輸入參數視為[[JSON]]
*:部分模組中函數可能有需要傳入特殊格式物件的需求，此時可以透過設定此選項來以[[JSON]]來輸入支援的物件。
'''注意事項'''：若指定的模組中函數本身已支援模板調用則可能出錯。因為支援模板調用的模組通常是用第一參數接收所有模板參數，而此函數會先將模板參數全部展開才傳入，可能會有參數無效或者第一參數無法使用（如支援模板調用的第一參數預期是一個包含所有模板參數資訊的lua table，但本函數將參數展開可能導致第一參數變為字符串或數字）等問題。

=== templateArgWarp ===
'''功能'''：替換引用時，將自身替換為另一個模板與參數

'''用途'''：如防止替換引用（替換引用又換回自身）或替換引用時轉成其他等價模板等。

'''參數'''：第一參數為要替換成的模板名稱。只有第一參數有效，其餘參數皆為從父模板讀取。
=== makeTemplateParameter ===
'''功能'''：產生模板參數的未解析字串，如<code><nowiki>{{{arg}}}</nowiki></code>

'''用途'''：搭配{{tl|虛擬模板}}作為替換引用的替代方案，參見{{tl|參數}}。
*輸入<code><nowiki>{{#invoke:TemplateParameters|makeTemplateParameter|arg|default}}</nowiki></code>
*顯示為：「{{#invoke:TemplateParameters|makeTemplateParameter|arg|default}}」

== 用途 ==
*[[Module:Number]]中，[[模块:Number/doc#參數|客製化的性質輸出格式]]。
*[[Module:PeriodicTable]]中，選擇要在[[元素週期表]]輸出的元素性質。

== 相關模板 ==
*{{模板|虛擬模板}}
*{{模板|解析數字}}
*{{模板|數字性質}}
<includeonly>{{Sandbox other||
<!-- 本行下加入模組的分類 -->

}}</includeonly>