Help:Substitution/ja

subst展開は、ページが保存されたときのページのウィキテキストの自動変換であり、ウィキテキストが1つ以上のテンプレート、変数、またはパーサー関数の時に行われます.

テンプレートsubst展開の場合、テンプレート呼び出しは、パラメーターの置換を伴うテンプレートコンテンツに置き換えられます. したがって、テンプレートはマクロとして使用され、ページが保存されるときは、通常のようにページが保存されるときではなく、ページがmacroexpandedになります. 表示されました.

変数またはパーサー関数のsubst展開の場合、それへの参照は結果の値に置き換えられます.

subst展開は、マジックワード または を、例のようにスペースを挟まずに二重中括弧の後に置くことによって行われます: および . コード は、マルチレベルsubst展開に役立ちます. 以下を参照してください.

結果(保存されたウィキテキストとの違いの形で)は、[差分を表示]を押すことで、保存する前(または保存しない)で確認できます. ただし、テキストが複数の段落をカバーしている場合、余白にプラス記号があるため、この差分ページは結果のコピーにはあまり適していません(たとえば、すべてのステップを保存せずに段階的にsubst展開する場合).

申請
テンプレートのsubst展開:


 * テンプレートから独立したレンダリングページを作成します.
 * テンプレートを編集しても、レンダリングされたページは変更されません.
 * テンプレートをコピーせずに、ページを別のMediaWikiウィキにコピーできます.
 * サーバーのページレンダリングが簡単になり、高速になります.
 * テンプレートの動作を分析してデモンストレーションします. ただし、場合によっては、subst展開の動作が異なります.
 * ウィキテキストとレンダリングされたページの対応を理解しやすくします(これが当てはまる場合もあれば、逆の場合もあります).

時刻に依存する変数のsubst展開:


 * レンダリングされたページを、時刻に依存しないようにします.

ページに依存する変数のsubst展開:


 * ランダリングしたページが改名の影響を受けないようにするにはウィキ文を別のページに転記する処理があります (もし逆に、 PAGENAME 変数がそのページを内包するページ自体の非表示部分 no-include part に記述された場合も適用).

MediaWikiの拡張機能の中には、テンプレート内で使用するとき、そのテンプレートを必ずsubst展開するように制限されたものがあります.

概要
そもそも subst展開 を論じるとき、「通常のテンプレート」 とは特定のページを指し、パターン {&#123;subst:pagename &#160; &#125;} (テンプレート名前空間のページ用) もしくは {&#123;subst:fullpagename &#160; &#125;} (他の名前空間のページ用) のいずれかに該当します. 「あらかじめ定義済みのテンプレート」 predefinedis とは変数もしくはパーサ関数としてやはり substit 展開されています.

Subst 展開するとは、最初に実行される独自のプロセスのことで、その後に通常のテンプレートの展開やパーサ関数、変数やパラメータが実行されます.

個別の subst 展開の呼び出しには、別の substit 展開を（複数）の埋めこみが可能です. また同様に、入子構造として subst 展開に埋めこんだテンプレートにさらに別の subst 展開を埋めこむこともできます. テンプレート名もしくはパーサ関数名の表現を subst 展開した場合、最初に定義するのは subst 展開の対象となるテンプレートもしくはパーサ関数のパラメータ定義、加えて subst 展開テンプレートの本体の定義です.

展開はその後に実行するため、subst 展開の表現に二重カッコで挟んだ記述部分があるなら、そのカッコを平文として処理します. そこで subst 展開中はパラメータ名の一部に付いたカッコが subst 呼び出しされ（例： ）テンプレート本体の同名のパラメータに対応する（例： ）状態が発生する可能性があります.

もし存在しないテンプレートなどをsubst 展開 しようと試みても実際に展開はされず、接頭辞「subst:」はウィキ文に残ります.

実際にテンプレートその他の subst 展開処理が行われると、その結果として発生するウィキ文によってテンプレートその他の展開や他のプロセスは通常どおり、実行されます. subst 展開の終了後は、展開中に発生したパラメータ名の不一致をこれによって巻き戻すことはできません（後述の「部分展開」も参照）.

以下の各項が十分に評価された場合のみ、subst 展開が可能です.


 * テンプレート、パーサ関数、変数のそれぞれの名称
 * テンプレートが対象の場合：テンプレート呼び出しならびにテンプレート自体に含まれるパラメータ名
 * 対象が #if, #ifexpr, #ifexist と #iferror の場合、コロン記号「:」に続くパラメータ
 * 対象が #ifeq の場合、ころん記号「:」直後および2番目のパラメータ
 * 対象が #switch の場合、コロン記号直後のパラメータと等号「=」の左の記述

前述のとおりsubst 展開とは他の表現に先立って実行されるため、subst 展開ではない表現を使う場合、 上記に示した必要十分条件としての評価は行いません.

同様に別記した以外のパーサ関数は、コロン記号「:」より後に十分に評価されなかったパラメータがあると、パーサ関数は対象として展開したウィキ文ではなく、カッコで挟んだウィキ文を取り、結果に影響を与えます.

例:


 * を用いる が subst 展開しない理由は Help:L k が存在しないページだからで、 Help:Lk は Help:Lk として処理されます.  その結果、生成されるウィキ文は元のウィキ文と同文で、  として処理されます.
 * を用いる yes からウィキ文「yes」が生成され、 yes はウィキ文「no」を生成、 は「」として処理されます.

In principle the wikitext resulting from full substitution is, immediately after that, rendered the same as the wikitext with ordinary inclusion.

Note however that on substitution of a parser function, an undefined parameter with default, used in a parameter value, is not replaced by the default (in English Wikipedia), and is for example not allowed in the numerical expression evaluated on substitution of #expr:


 * gives, while gives "Expression error: unrecognised punctuation character "{""

On substitution of a template that contains this, is either replaced by the value of  or by 3, so then there is no complication.

using is rendered as ;  gives the wikitext a rendered the same as the wikitext, and on the next edit/save changed into start-a -middle--end;  gives the wikitext , rendered as. This is because, both without substitution and in the case of full substitution, the pipe characters in template calls, excluding those inside inner template calls, template parameters, links, and image tags, determine the separation of parameter definitions from each other and from the template name. This separation does not depend on possible extra pipe characters in the expanded form of the template name and parameter definitions. However, if after substitution of an inner template the pipe character is in the outer template call it is one like any other and plays its part in determining the separation. In other words, parsing is done first once for substitution, and then once for rendering, but in both cases not an extra time in between. In the case of substitution of the inner template only, two subsequent parsings are effective.

When substituting a template containing (a parameter tag with default) this results in the value of p if it is defined, and otherwise in q. For example, using &lbrace;&lbrace;timc|t pd}} (in English Wikipedia),  gives the wikitext 2.

If a page substitutes itself (e.g. in the noinclude-part of a template page) it substitutes the old version.

考慮すべき点
As mentioned, a change of an ordinary template after substitution does not affect the page in which it was substituted, and a substituted variable depending on time no longer depends on time, etc. However, a substitution of e.g. does not affect rendering at all.

The relationship between wikitext of a page and its rendering can become easier to understand after substitution, because one has all wikitext together, and parameter substitutions have been performed.

It can also become more complex. Separately focusing on understanding a template call and understanding the template content can be easier. Wikitext after substitution is often more complex than when the required wikitext would have been written directly.

Unlike a template call (if one knows about templates), wikitext after substitution does not show how one can produce a similar result. The wikitext can be long and complicated, and therefore cumbersome to write directly, or it can be simple, e.g. a number resulting from a computation, but cumbersome to find directly. When studying the wikitext of a page one may think that this wikitext is what one is supposed to write and find directly to get the result, even in cases where that would be very impractical.

In such cases documentation of the template call is useful. Just like in computer programming we change the source code and/or the data to produce new results, and we do not directly change the object file, here we would change the template calls and/or the templates, instead of changing the wikitext resulting from substitution directly.

記事テンプレート
In the case of substituting an ordinary template, the template tag is replaced by the wikitext of the template, with the parameter values substituted for the parameters.


 * Example&#58;, containing
 * and called as   (see tc) gives the wikitext:
 * , rendering as
 * start-a-middle--end.
 * start-a-middle--end.

Substitution removes the noinclude parts and the includeonly tags.

Parameters:
 * A substitution with p=r replaces and  by r; this includes the cases that r is of the form  or.
 * A substitution with undefined p preserves and replaces  by the default q (in English Wikipedia).

With "subst:" the replacement of a template tag by wikitext does not work recursively. For full recursive substitution use Special:ExpandTemplates. See also substall, and multilevel substitution below.

Stepwise substitution of templates including other templates including more templates etc. can be useful for analyzing and documenting the behaviour of complex templates, for an example see m:Template talk:Lop.

However, after a substitution a page may render differently, e.g. if templates produce braces, pipes, and/or equals signs which after substitution determine expansion of other templates, but without substitution are treated as plain text.

In the absence of parameters, template substitution can be compared with copying the wikitext, or the rendering of a previewed or saved {&#123; &#160; pagename &#160; &#125;} inclusion. However, template substitution excludes  parts, removes   tags, and replaces undefined parameters with defaults by those defaults.

事前定義されたテンプレート
In the case of substituting a predefined template, without parameters depending on other templates, the tag is replaced by the result.

Note:  has to be added directly in front of the predefined template name without intervening spaces.

Applying subst to a variable works like applying it to a template. E.g. a timestamp:


 * -- T UTC :

may give the wikitext


 * 2010-04-10 T 06:30 UTC

rendered as
 * 2010-04-10 T 06:30 UTC

In the case of substituting a predefined template with a parameter depending on another template, that has to be substituted too, with a separate  modifier, otherwise the result is undefined.


 * gives IN, the same wikitext as is expanded to; UC: is applied to the output "in" of Tc.
 * gives File.
 * gives wikitext     rendered as.
 * gives the wikitext startHelpend (see t1)
 * gives the wikitext start12end
 * gives the wikitext startABCDEFend
 * gives the wikitext 1331
 * gives the wikitext ABCABCABC
 * gives the wikitext 1e-05 (see LC:)
 * gives (at the time of writing) the wikitext 30
 * gives (at the time of writing) the wikitext THURSDAY

However:
 * 1)  gives the wikitext   rendered as.
 * 2)  stays , rendered as  (see ns:).

As mentioned before, on substitution, all calls without substitution of templates, variables, and parser functions are treated as plain text. As a result substitution of the outer  in a nested often is only suitable if all inner  are also substituted.

In the case of substitution of a predefined template, if the expression for one of its parameters contains with undefined p, this code reduces to 3. However, on the page itself, is treated as such, not as 3.

Examples:
 * gives
 * gives
 * gives Expression error: Unrecognized punctuation character &quot;{&quot;.
 * substituting a template containing gives 6 if p is not assigned a value, and twice the number p if it is assigned a value.
 * the same result can be obtained from a template containing, if the substitution call has a parameter of " ".

Compare:
 * 2* gives 2*
 * 2* gives 2*
 * gives the wikitext 2* rendered as 2*

and also (from above):
 * gives IN, just like does; UC is applied to the output "in" of Tc.
 * gives the wikitext  rendered as.

In the substitution of UC, the inclusion tag is treated as string just like.

部分的なsubst展開
Inside an ordinary template one can apply substitution to an ordinary template call containing a parameter, to replace it by the direct wikitext containing the parameter. It amounts to automatically merging the two templates (creating a "composite template" like a composite function). It is not possible if the inner and/or outer template is predefined. (However, manually merging e.g. a call of #expr inside another one is useful for increasing the accuracy of the result by avoiding intermediate rounding to 12 digits.)

This way one can dispense with the optional substitution technique described below, and apply substitution of the resulting outer template by simply using "subst:" (unless there are more nesting levels).

Example:
 * gives the wikitext start--end, just that of , without noinclude parts and includeonly tags
 * ab gives the wikitext start-ab-end

Examples with double substitution:
 * gives the wikitext start--endstart--endstart--endstart--end
 * gives the wikitext start--endstart--endstart--end

多重subst展開
When substituting a template it may be desirable to carry out a substitution inside the template too. This can be done with "safesubst:" in the template. To prevent premature substitution (i.e., when the template is saved), this code is provided as default value of an unused parameter. Since the empty string is a possible—but for other purposes uncommon—parameter name, it is usually a suitable choice for the name of this unused parameter, so we can use the code.

The difference with  is that , evaluating to   if the parameter with the empty string as name is undefined, not only allows multilevel substitution but also multilevel transclusion, because on transclusion it is ignored. To make the template such that it allows the choice between these two options as well as one-level substitution (and more choices if more templates, parser functions and/or variables are involved) one or more parameters are needed, see below.

Sometimes a template call defines a value of the parameter with the empty string as name, just for inserting this value as comment inside the template tag, or for lay-out of the template tag, see template tag lay-out. This would affect the working of the code. To allow this other dummy use of the parameter, another parameter name can be used in, or to avoid any possible clash of dummy parameter names, includeonly tags can be used, see below.

Multilevel substitution with independent control of each substitution separately
A parameter subst (or more, each with its own name) can be used with "safesubst:" and the empty string as possible values. Thus we can for example control whether an inner template is substituted too when the outer template is substituted. Either possibility can be made the default.

Inner templates with parameters may control further inner substitutions in the same way; these parameters may depend on the substitution parameter controlling the substitution of the inner template, since if that is not substituted, inner substitutions within that template are not possible.

Similarly, if there are multiple templates, parser functions, and/or variables in the inner template(s) we can control substitution of all, either independently by using different parameters, or with some or all using the same parameter.

For example, if template T uses parameter subst1:
 * with the empty string as default, T calls inner templates and parser functions prefixing their names with ; for calling T we can use:
 * .. (no substitution)
 * .. (one-level substitution)
 * .. (two-level substitution)
 * .. (ditto)
 * with default "safesubst:", T calls inner templates and parser functions prefixing their names with ; for calling T we can use
 * .. (no substitution)
 * .. (one-level substitution)
 * .. (two-level substitution)

To transfer the choice of substituting or not to templates and parser functions called inside the inner templates of T, we can add to the call of these inner templates something of the form subst2= or subst2= , respectively (parser functions and variables don't get the additional parameter).

See also m:Help:Calculation and.

Partial substitution
Using a template prepared for optional  only with ordinary substitution, without specifying parameter values, allows to insert its code into another template, like copy and paste, but all parts and  keywords automatically stripped. Executing inserted code instead of calling it may be more efficient for the server.

A typical example for this technique is expanding, within another template, a template used as test expression in a #switch: like : parameter tag case 0 etc. parameter tag case 0 etc. parameter tag case 0 etc. m:Template:len is prepared for optional substitution, therefore both solutions work, but the latter solution substituting its code is simpler and more efficient.
 * 1) Development code:
 * 1) Standard solution:
 * 1) Better solution: create template code by applying substitution using this wikitext:

See m:Template:csn and m:Template:lz12 for cases where Template:len was substituted in this way.

If a template uses a parameter whose name is an expression containing a template or parser function, and the template is called with a corresponding parameter definition (in terms of the final name of the parameter) it expands properly only if at the time of expansion of the template the expression for the name of the parameter is or has been evaluated. Thus if the template is substituted without substituting the expression for the parameter name, the parameter definition is "lost", so the parameter becomes undefined. Therefore in such a case no substitution can give the same rendered result as full substitution, while partial substitution gives a different result. See e.g..

Composite operations
By a template A is called with, as parameter, a call of template B with a parameter p. We could integrate such template calls to a single call  of a "composite template" C with parameter p.


 * The wikitext for template C would be, or with optional substitution the following construct&#58;
 * {&#123; &#160;{&#123;{subst }&#125;}&#160; A|{&#123; &#160;{&#123;{subst  }&#125;}&#160; B| &#160;|subst={&#123;{subst  }&#125;}&#160; &#125;} &#160;|subst={&#123;{subst  }&#125;}&#160; &#125;}
 * The subst=  is only necessary for recursive substitution as explained above.

Note that it is not useful to specify " subst: " since in the substitution phase this tag does not reduce to the default "subst:".

If A and/or B is predefined the construct is similar, but without subst= for that template.

Includeonly
An alternative method to prevent premature substitution, known as "includeonly subst magic", is with a pair of includeonly tags. Substitution is prevented by having the template call inside these tags. Substitution is also prevented by having one or both tags anywhere in the template call except inside a parameter definition. Thus the tag(s) can be before, inside, or after "safesubst:" or "subst:", or inside or after the template name. The positions of the two tags only influence the rendering of the template page itself.

The form {&#123; something&#125;} suggests that substitution is prevented by discarding "safesubst:" on the page itself, but actually substitution is prevented because the safesubst-syntax is disturbed by the tags.

It doesn't substitute "something" at the time of the creation of the relevant template, but has the desired effect when the template is substituted.

For examples see "preload" in Extension:InputBox and "substitution" in Help:Magic words.

Creating a page which applies substitution on the next save
See m:Help:Recursive conversion of wikitext.

Forced substitution
Some templates deliberately refuse to work without substitution, for an example see Conv-dist. This technique is essential for templates like prod producing some kind of timestamp, e.g. adding pages to dated categories.


 * The following code in any template T outputs a warning unless recursive substitution with  is in effect&#58;
 * Output for {&#123;T&#125;} or {&#123;subst:T&#125;}&#58; Warning,
 * output for {&#123;T|subst=subst:&#125;}&#58; ,
 * output for {&#123;subst:T|subst=subst:&#125;}&#58; nothing (no remaining wikitext).
 * output for {&#123;subst:T|subst=subst:&#125;}&#58; nothing (no remaining wikitext).


 * This is a rare case where replacing ifdef by #if: doesn't work directly.

Substitution of part of the parameters
Let template A use parameters 1 and 2. Consider creating a template B with one parameter 1, corresponding to A, with a given value q of parameter 2. Compare and. They look the same on the template page, see e.g., but the first does not work because is treated as text, not as parameter.

However, with substitution (using "subst:" or Special:Expandtemplates) the resulting wikitext is the same, without distinction between a text and a parameter, it is a parameter anyway, so "1=" is not needed.

If A contains e.g. #expr with an expression containing both parameters the same applies, except that we can only substitute the highest level (A), not the parser function, so we cannot use Special:Expandtemplates.

In general, substituting a parameter and applying a template or parser function sometimes gives the same result as substituting the template or parser function with the triple-braced parameter code and then substituting the parameter.

Without defaults (all rendered the same in one-step substitution as without substitution):

Examples with equality:
 * A template containing pqr substituted with 1=u, 2=v gives puqvr; substituted with 2=v it gives pqvr, which itself, substituted with 1=u gives also puqvr.
 * Two-level substitution of a template containing with 3=u, 4=v gives up; substituted with 4=v it gives p, which itself, substituted with 3=u gives up.

Examples without equality:
 * Two-level substitution of a template containing with 3=, 4=v gives the empty string; substituted with 4=v it gives vp, which itself, substituted with 3=u remains vp.
 * Two-level substitution of a template containing with 1=u, 2=v gives up; substituted with 2=v it gives pp (the bug), which itself, substituted with 3=u, gives upp.
 * Two-level substitution of a template containing with 1=7, 2=8 gives 56; substituted with 2=8 it gives &lt;strong class="error">Expression error: Unrecognised punctuation character "{"&lt;/strong>, which itself, substituted with 1=7, remains the same.

Thus without equality we may or may not get an error message.

One example shows that substitution of one parameter can be affected by the bug mentioned above. However, we can then replace e.g. by  and do full substitution, except that substvoid is undefined, preventing the bug. The result works already correctly with transclusion. Subsequently it can be substituted with substvoid=subst: so that we get the plain.

With defaults:

Rendered the same as without substitution:
 * Two-level substitution of a template containing pqr with 2=v gives pqvr.
 * Two-level substitution of a template containing with 4=v gives p.

Not rendered the same as without substitution:
 * Two-level substitution of a template containing with 4=v gives vp.
 * Two-level substitution of a template containing with 2=v gives pp (the bug).
 * Two-level substitution of a template containing with 2=8 gives &lt;strong class="error">Expression error: Unrecognised punctuation character "{"&lt;/strong>.

After substitution with the parameter definition:
 * vp gives vp.
 * p gives pp (the bug).
 * gives &lt;strong class="error">Expression error: Unrecognised punctuation character "{"&lt;/strong>.

Rewritten:
 * gives the empty string.
 * p gives dp.
 * gives 48.

制限
subst展開は、およびタグの中では使用できません. もし と記述すると、subst 展開も参照読み込みもせず、単に文字どおりの表示になります.

subst展開の文書化
を介してテンプレートを使っても、ページの変更履歴には自動で表示されません. そこでウィキ文唐「subst:」を含む行を編集要約欄に明示すると、とても役に立ちます.

さらに subst 展開したテンプレートをページに使用するとバックリンクに表示されず、当該のテンプレートは編集したページの「参照読み込みテンプレートのリスト」にも拾われません. テンプレート側から subst 展開したページを追跡用カテゴリに追加できますが、特定ページにそのリストを転載すると、今度はコンテンツ基準のカテゴリにそのページを表示した場合に、ごちゃごちゃしてしまいます. また、noinclude タグで挟んでいないコメントはウィキ文内に明示されます. そこで、コメントを利用して当該のテンプレートに言及する方法はあります. その中にパラメータ値も記すことも可能で、subst したパラメータはコメント内でも有効だからです.

関連項目

 * Help:Substitution/tl;dr – tl;dr
 * w:Help:Substitution
 * w:Wikipedia:Template substitution – partly technical, partly policy
 * T4003 – feature request to allow marking a template as being substituted without "subst:"
 * Templates containing a call to itself with "subst:" and producing a similar call with updated info, either replacing or adding to the previous info: