Help:ParserFunctions and Template:System admin toc: Difference between pages

From Meta, a Wikimedia project coordination wiki
(Difference between pages)
Content deleted Content added
Omniplex (talk | contribs)
 
m chopped out a nasty long list of OSes and put the content on new page
 
Line 1:
{| border="0" cellspacing="0" cellpadding="0"
<small>'''Other languages:''' {{ParserFunctions}}</small>
|align="right"|<small>[[Help:System admin|View this alone]]</small>
{{shortcut|[[WM:PF]]}}
This MediaWiki extension is a collection of parser functions. Parser functions typically have the syntax:
:<nowiki>{{</nowiki>#functionname: argument 1 | argument 2 | argument 3...}}
 
==Functions ==
This module defines six functions at present:
<tt>[[#.23expr:|expr]]</tt>,
<tt>[[#.23if:|if]]</tt>,
<tt>[[#.23ifeq:|ifeq]]</tt>,
<tt>[[#.23ifexist:|ifexist]]</tt>,
<tt>[[#.23ifexpr:|ifexpr]]</tt>, and
<tt>[[#.23switch:|switch]]</tt>.
 
=== #expr: ===
 
The <tt>expr</tt> function computes mathematical expressions based on permutations of numbers (or [[variable]]s/[[parameter]]s that translate to numbers) and operators. It does ''not'' work with strings; use <tt>ifeq</tt> below instead. The syntax is:
 
<nowiki>{{</nowiki> #expr: ''expression'' }}
 
A list of supported operators follows. For more details about the operator precedence see [[Help:Calculation]],
it's roughly '''(1)''' grouping (parentheses), '''(2)''' unary (+/- signs and NOT), '''(3)''' multiplicative (*, /, div, mod), '''(4)''' additive (+ and -), '''(5)''' round, '''(6)''' comparative (=, !=, &lt;, &gt;, etc.), '''(7)''' logical AND, '''(8)''' logical OR.
Within the same precedence class operators are evaluated left to right. As always some redundant parentheses are better than erroneous terse code.
 
{| cellpadding="6px" border=1 style="border:1px solid #C0C0C0; border-collapse:collapse;"
! ''Operator''
! ''Operation''
! ''Example''
|-
!<br />[[Help:Administrator's Guide|Admin's Guide]]
|rowspan="2" colspan="2" align="center"| none
||<nowiki>{{#expr: 123456789012345}}</nowiki> = {{#expr: 123456789012345}}
|-
|[[Help:MediaWiki architecture|MediaWiki architecture]]
||<nowiki>{{#expr: 0.000001}}</nowiki> = {{#expr: 0.000001}}
|-
|[[Help:Database layout|Database layout]]
! ( )
|| Grouping operators
||<nowiki>{{#expr: (30 + 7) * 7 }}</nowiki> = {{#expr: (30 + 7) * 7 }}
|-
|[[Help:Job queue|Job queue]]
! +
|| Unary '''<tt>+</tt>''' sign
||{&#123;#expr: <tt>+</tt>30 * <tt>+7</tt>&#125;} = {{#expr: +30 * +7}}
|-
!<br />[[Help:Installation|Installation]]
! -
|| Unary '''<tt>-</tt>''' sign (negation)
||{&#123;#expr: <tt>-</tt>30 * <tt>-</tt>7&#125;} = {{#expr: -30 * -7}}
|-
|[[Help:Working with CVS|Working with SVN]]
! not
|| Unary NOT, logical NOT
||<nowiki>{{#expr: not 0 * 7}}</nowiki> = {{#expr: not 0 * 7}}<br /><nowiki>{{#expr: not 30+7}}</nowiki> = {{#expr: not 30+7}}
|-
|[[mw:SVN|Installing the SVN tree]]
! *
|| Multiplication
||<nowiki>{{#expr: 30 * 7}}</nowiki> = {{#expr: 30 * 7}}
|-
|[[help:OS specific help|OS specific help]]
! /
|| Division, same as '''div'''
||<nowiki>{{#expr: 30 / 7}}</nowiki> = {{#expr: 30 / 7}}
|-
|[[Running MediaWiki on Sourceforge.net| on Sourceforge.net]]
! div
|| Divsion, same as '''/''',<br />no integer division
||<nowiki>{{#expr:&#160;30&#160;div&#160;7}}</nowiki>&#160;=&#160;{{#expr: 30 div 7}}<br /><nowiki>{{#expr: 5 div 2 * 2 + 5 mod 2}}</nowiki> = {{#expr: 5 div 2 * 2 + 5 mod 2}}
|-
|[[Timezone adjustments]]
! mod
|| "Modulo",&#160;remainder&#160;of&#160;division after truncating both operands to an integer.<br />Caveat, '''div''' and '''mod''' are different from all programming languages.
||<nowiki>{{#expr: 30 mod 7}}</nowiki> = {{#expr: 30 mod 7}}<br />{&#123;#expr: <tt>-</tt>8 mod <tt>-</tt>3&#125;} = {{#expr: -8 mod -3}}<br />{&#123;#expr: <tt>-</tt>8 mod <tt>+</tt>3&#125;} = {{#expr: -8 mod +3}}<br /><nowiki>{{#expr: 8 mod 2.7}}</nowiki> = {{#expr: 8 mod 2.7}}<br /><nowiki>{{#expr: 8 mod 3.2}}</nowiki> = {{#expr: 8 mod 3.2}}<br /><nowiki>{{#expr: 8.9 mod 3}}</nowiki> = {{#expr: 8.9 mod 3}}
|-
!<br />Security <small><code>techy</code></small>
! <tt>+</tt>
|| Addition
|| {&#123;#expr: 30 <tt>+</tt> 7&#125;} = {{#expr: 30 + 7}}
|-
|[[Documentation:Security|Security]]
! <tt>-</tt>
|| Subtraction
|| {&#123;#expr: 30 <tt>-</tt> 7&#125;} = {{#expr: 30 - 7}}
|-
|[[Security Checklist]]
! round
|| Rounds off the number on the left to the power of 1/10 given on the right
||<nowiki>{{#expr: 30 / 7 round 3}}</nowiki> = {{#expr: 30 / 7 round 3}}<br /><nowiki>{{#expr: 30 / 7 round 0}}</nowiki> = {{#expr: 30 / 7 round 0}}<br /><nowiki>{{#expr: 3456 round -2}}</nowiki> = {{#expr: 3456 round -2}}
|-
|[[Paranoid Permissions]]
! =
|| Equality (numerical incl. logical)
||<nowiki>{{#expr: 30 = 7}}</nowiki> = {{#expr: 30 = 7}}
|-
|[[Setting user rights in MediaWiki|Setting user rights]]
! &lt;&gt;
|| Inequality, same as '''!='''
||<nowiki>{{#expr: 30 &lt;&gt; 7}}</nowiki> = {{#expr: 30 <> 7}}
|-
!<br />Configuration
!| !=
|| Inequality, same as '''&lt;&gt;''', logical ''xor''
||<nowiki>{{#expr: 1 != 0}}</nowiki> = {{#expr: 1 != 0}}
|-
|[[Preventing Access]]
! &lt;
|| Less than
||<nowiki>{{#expr: 30 &lt; 7}}</nowiki> = {{#expr: 30 < 7}}
|-
|[[Documentation:Configuration|Configuration]]
! &gt;
|| Greater than
||<nowiki>{{#expr: 30 &gt; 7}}</nowiki> = {{#expr: 30 > 7}}
|-
|[[Help:Configuration]]
! &lt;=
|| Less than or equal to
||<nowiki>{{#expr: 30 &lt;= 7}}</nowiki> = {{#expr: 30 <= 7}}
|-
|[http://www.mediawiki.org/wiki/Help:Configuration_settings Configuration settings]
! &gt;=
|| Greater than or equal to
||<nowiki>{{#expr: 30 &gt;= 7}}</nowiki> = {{#expr: 30 >= 7}}
|-
|[[Apache config]]
! and
|| Logical AND
||<nowiki>{{#expr: 4&lt;5 and 4 mod 2}}</nowiki> = {{#expr: 4<5 and 4 mod 2}}
|-
|[[Robots.txt]]
! or
|-
|| Logical OR
|[[Eliminating index.php from the url|Shorter URLs]]
||<nowiki>{{#expr: 4&lt;5 or 4 mod 2}}</nowiki> = {{#expr: 4<5 or 4 mod 2}}
|}-
|[[Using a very short URL]]
 
|-
The boolean operators consider '''0''' to be "false" and any other number to be "true", on output "true" is shown as '''{{#expr: 30 and 7}}'''.
|[[PHP config]]
 
|-
Numbers are given in decimal with "." for the decimal point. Scientific notation with <tt>E</tt> plus exponent is not yet supported on input, but used on output, for details see [[Help:Calculation]].
|[[MySQL config]]
 
|-
 
|[[Help:Configuration tips and tricks|Tips and tricks]]
Example:
|-
 
!<br />Customization
<nowiki>{{ #expr: (100 - 32) / 9 * 5 round 0 }}</nowiki>
|-
 
|[[Layout customization]]
gives:
|-
 
|[[Help:Timezone|Set Global Timezone]]
{{ #expr: (100 - 32) / 9 * 5 round 0 }}
|-
 
|[[MediaWiki localization]]
which is 100&deg;F in &deg;C, rounded to the nearest whole number.
|-
 
|[[Help:Interwiki links|Interwiki links]]
=== #if: ===
|-
 
|[[Help:Navigation bar|Custom navigation bar]]
The <tt>if</tt> function is an if-then-else construct. The syntax is:
|-
 
|[[Skins|Custom skins]]
{&#123; #if: ''&lt;condition&gt;'' | ''&lt;then text&gt;'' | ''&lt;else text&gt;'' }}
|-
 
|[[Help:Custom namespaces|Custom namespaces]]
If the condition is an empty string or consists only of whitespace, then it is considered false, and the ''else text'' is returned. Otherwise, the ''then text'' is returned. The ''else text'' may be omitted, in which case the result will be blank if the condition is false.
|-
 
|[[MediaWiki extensions]]
An example:
|-
<nowiki> {{Template|parameter=something}} {{Template}} {{Template|parameter=}}</nowiki>
!<br />Manage the database
<nowiki> | | |</nowiki>
|-
<nowiki> | | |</nowiki>
|[[How to move a MediaWiki Database|Move a database]]
<nowiki> | | |</nowiki>
|-
<nowiki>{{ #if: {{{parameter|}}} | Parameter is defined. | Parameter is undefined, or empty }}</nowiki>
|[[Help:Reduce size of the database|Reduce the size]]
 
|-
Note that the <tt>if</tt> function does '''not''' support "=" signs or mathematical expressions. <nowiki>{{#if: 1 = 2|yes|no}}</nowiki> will return "yes", because the string "1 = 2" is not blank. It is intended as an "if not empty" structure.
|[[Lock the database]]
 
|-
=== #ifeq: ===
!<br />Performance
 
|-
<tt>ifeq</tt> compares two strings or numbers, and returns another string depending on the result of that comparison. The syntax is:
|[[PHP caching and optimization|PHP caching]]
 
|-
<nowiki>{{</nowiki> #ifeq: ''&lt;text 1&gt;'' | ''&lt;text 2&gt;'' | ''&lt;equal text&gt;'' | ''&lt;not equal text&gt;'' }}
|[[Help:File cache|File cache]]
 
|-
If both strings can be interpreted as numbers the comparison is numerical. To force a string comparison add tokens that can't be interpreted as numbers:
|[[Squid caching]]
 
|-
:<tt>{&#123; #ifeq: +07 | 007 | 1 | 0 &#125;}</tt> gives {{#ifeq: +07 | 007 | 1 | 0 }}
|[[Cache strategy]]
:<tt>{&#123; #ifeq:"+07"|"007"| 1 | 0 &#125;}</tt> gives {{#ifeq:"+07"|"007"| 1 | 0 }}
|-
 
|[[Wikimedia servers]]
;For compatibility with older templates [[#.23if:|#if:]] cannot directly distinguish defined and undefined parameter values, it's a shorthand for a comparison with the empty string. With [[#.23ifeq:|#ifeq:]] it's directly possible to identify undefined parameters&#58;
|-
:<tt>{&#123; #if: {&#123;{x| }&#125;}'''|'''not blank'''|'''blank&#125;}</tt> = {{#if: {{{x|}}}|not blank|blank}},
|[[As your Site Grows]]
:<tt>{&#123; #ifeq: {&#123;{x| }&#125;}'''|&#160;|'''blank'''|'''not blank&#125;}</tt> = {{#ifeq: {{{x|}}}| |blank|not blank}},
|-
:<tt>{&#123; #ifeq: {&#123;{x| }&#125;}'''|'''{&#123;{x|u}&#125;}'''|'''defined'''|'''undefined&#125;}</tt> = {{#ifeq: {{{x|}}}|{{{x|u}}}|defined|undefined}}.
!<br />Maintenance
 
|-
=== #ifexist: ===
|[[Help:Maintenance scripts overview|Maintenance scripts]]
 
|-
<tt>ifexist</tt> returns one of two results based on whether or not a named title exists, e.g.
|[[Help:Upgrading MediaWiki|Upgrade Mediawiki]]
 
|-
:<code><nowiki>{{#ifexist:Foo|Bar|RFC 3092}}</nowiki></code> gives {{#ifexist:Foo|Bar|RFC 3092}} if [[Foo]] {{#ifexist:Foo|exists|doesn't exist}}.
|[[Troubleshooting math errors|Math errors]]
:<code><nowiki>{{#ifexist:ParserFunctions|Thanks|No}}</nowiki></code> gives {{#ifexist:ParserFunctions|Thanks|No}}.
|-
:<code><nowiki>{{#ifexist:m:Help:Calculation|Yes|Oops}}</nowiki></code> gives {{#ifexist:m:Help:Calculation|Yes|Oops}} although [[m:Help:Calculation]] exists, because of the interwiki prefix.
|[[LocalSettings.php]]
 
|}<noinclude><hr width="20%" />
The first parameter is the title to check for, the second is the positive result, and the third, the negative result. If the parameter passed does not produce a valid title object, then the result is negative.
 
{{tim|exists}} gives the same result, except that the result is positive for an interwiki link. {{tim|if interwiki link}} exploits this difference.
 
=== #ifexpr: ===
 
<tt>ifexpr</tt> evaluates a mathematical expression and returns one of two strings depending on the result.
 
{&#123;#ifexpr: ''&lt;expression&gt;'' | ''&lt;then text&gt;'' | ''&lt;else text&gt;'' &#125;}
 
If the expression evaluates to zero, then the ''else text'' is returned, otherwise the ''then text'' is returned. Expression syntax is the same as for <tt>expr</tt>.
 
;At the moment the ''else text'' is also returned for an empty expression&#58;
:<code><nowiki>{&#123;#ifexpr: {&#123;ns:0&#125;}|Toast|'''or else'''&#125;}</nowiki></code> gives {{#ifexpr: {{ns:0}}|Toast|'''or else'''}}
;Omitting both ''then text'' and ''else text'' gives no output except possibly an error message; this can be used to check the correctness of an expression, or to check the wording of the error message (emulated ''assertions'', forced errors)&#58;
:<code>{&#123;#ifexpr: 1/{&#123;#ifeq: {&#123;ns:4&#125;}|Meta|1|0&#125;}&#125;}</code> {{#ifexpr: 1/{{#ifeq: {{ns:4}}|Meta|1|0}}}}
:<code>{&#123;#ifexpr: 1/{&#123;#ifeq: {&#123;ns:4&#125;}|Meta|0|1&#125;}&#125;}</code> {{#ifexpr: 1/{{#ifeq: {{ns:4}}|Meta|0|1}}}}
:<code>{&#123;#if:<nowiki>{{#ifexpr: 1=2}}</nowiki>|wrong|correct&#125;}</code> {{#if:{{#ifexpr: 1=2}}|wrong|correct}}
:<code>{&#123;#if:<nowiki>{{#ifexpr: 1E2}}</nowiki>|wrong|correct&#125;}</code> {{#if:{{#ifexpr: 1E2}}|wrong|correct}}
:<code>{&#123;#if:<nowiki>{{#ifexpr: 1/0}}</nowiki>|wrong|correct&#125;}</code> {{#if:{{#ifexpr: 1/0}}|wrong|correct}}
:<code>{&#123;#if:<nowiki>{{#ifexpr: a=b}}</nowiki>|wrong|correct&#125;}</code> {{#if:{{#ifexpr: a=b}}|wrong|correct}}
For an application, see also {{tim|evalns}}.
 
 
 
=== #switch: ===
<code>switch</code> compares a single value against multiple others, returning a string if a match is found. The syntax is basically:
 
<nowiki>{{</nowiki> #switch: ''&lt;comparison value&gt;''
| ''&lt;value<sub>1</sub>&gt;'' = ''&lt;result<sub>1</sub>&gt;''
| ''&lt;value<sub>2</sub>&gt;'' = ''&lt;result<sub>2</sub>&gt;''
| ''...''
| ''&lt;value<sub>n</sub>&gt;'' = ''&lt;result<sub>n</sub>&gt;''
| ''&lt;default result&gt;''
}}
 
<code>switch</code> will search through each value passed until a match is found with the comparison value. When found, the result for that value is returned (the text string after the equal sign). If no match is found, but the last item has no equal sign in it, it will be returned as the default result. If your default result ''must'' have an equal sign, you may use <code>#default</code>:
 
<nowiki>{{</nowiki> #switch: ''&lt;comparison value&gt;''
| ''&lt;value&gt;'' = ''&lt;result&gt;''
| #default = ''&lt;default result&gt;''
}}
 
Note that it's also possible to have "fall through" for values (reducing the need to duplicate results). For example:
 
<nowiki>{{</nowiki> #switch: ''&lt;comparison value&gt;''
| ''&lt;value<sub>1</sub>&gt;''
| ''&lt;value<sub>2</sub>&gt;''
| ''&lt;value<sub>3</sub>&gt;'' = ''&lt;result<sub>3</sub>&gt;''
| ''...''
| ''&lt;value<sub>n</sub>&gt;'' = ''&lt;result<sub>n</sub>&gt;''
| ''&lt;default result&gt;''
}}
 
Note how value<sub>1</sub> and value<sub>2</sub> contain no equal sign. If they're matched, they are given the result for value<sub>3</sub> (that is, whatever is in result<sub>3</sub>).
 
As for [[##ifeq:|#ifeq:]] the comparison is numerical where possible:
 
:<tt>{&#123; #switch: +07 | 7 = Yes | 007 = Bond | No &#125;}<tt> gives {{ #switch: +07 | 7 = Yes | 007 = Bond | No }}
:<tt>{&#123; #switch:"+07"|"7"= Yes |"007"= Bond | No &#125;}<tt> gives {{ #switch:"+07"|"7"= Yes |"007"= Bond | No }}
 
The matched value can be empty, therefore the following constructs are equivalent:
 
:<tt>{&#123; #if: {&#123;ns:0&#125;} | not empty | empty &#125;}<tt> gives {{ #if: {{ns:0}} | not empty | empty }}
:<tt>{&#123; #switch:{&#123;ns:0&#125;}|=empty|not empty &#125;}<tt> gives {{ #switch:{{ns:0}}|=empty|not empty }}
 
==Substitution==
 
:''See also: '''[[Help:Substitution]]'''.''
 
Applying "subst:" to a ParserFunction works, provided that there is no space between "subst:" and "#".
 
Note that unless a technique like [[Help:Substitution#Optional substitution|optional recursive substitution]]
is used, substituting a template which uses a ParserFunction does not replace that ParserFunction with its result. This is often undesirable.
 
==Caveats==
 
===Tables===
Currently wiki pipe table syntax doesn't work inside conditionals, there are two main workarounds.
* Hide the pipe from parser functions by putting it in a template, e.g. {{tim|!}} as on [[w:en:Template:!|w:en:]].
* Use html style table syntax instead.
* See also [[Help:Table]], completely empty rows or columns are not displayed. Empty cells could be also transformed into dummy <tt>&amp;nbsp;</tt> cells on pages not affected by [[mediazilla:5569|5569]].
Note that "'''<tt>|</tt>'''" and "'''<tt>=</tt>'''" were always tricky within templates, this is no new issue.
 
===Known problems===
#The parser functions can corrupt the literal {{{ ''parameter'' }}} for undefined parameters.
#*Defined parameters are not affected.
#*[[Help:parameter default|Parameter defaults]] are affected in the case of substitution of the parser function only, see [[Help:Substitution#Corrupted default value]].
#*For details and examples see [[ParserFunctions/5678]] and [[mediazilla:5678]].
#*This bug affects also other [[Help:Colon functions|predefined templates]], example:<br /><tt>{&#123; plural: 0 | 1 | 5678 {&#123;{2}&#125;}&#125;}</tt> gives '''{{ plural: 0 | 1 | 5678 {{{2}}}}}'''
#There are several '''#expr:''' oddities:
#*'''div''' is no integer division and (as is) redundant, use '''/''' (slash) for real divisions.
#*'''mod''' is different from modulo-operators in all other programming languages, see also {{tim|mod}}.
#*Valid [[#.23expr:|#expr:]] results like {{#expr: 0.0000001}} are not yet supported as '''#expr:''' input:
#*:<nowiki>{{#expr:</nowiki>{{#expr:0.0000001}}<nowiki>}}</nowiki> yields ''{{#expr:{{#expr:0.0000001}}}}''
#*Therefore output reused as input has to be in absolute value between 1E-4 and 1E+12.
#*:Together with the div/mod oddities porting non-trivial algorithms (e.g. for dates) is a challenge.
#*Under certain conditions '''round 0''' results in '''-0''' instead of '''0'''. For an expression '''x''' using '''0+1*(x)''' can apparently fix this oddity, for a workaround see [[Template:Zero]].
 
== Installation ==
 
Download both of these files and put them in a new directory called ''ParserFunctions'' in your [[Mediawiki extensions|extensions]] directory.
 
* [http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/ParserFunctions/Expr.php Expr.php]
* [http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/ParserFunctions/ParserFunctions.php ParserFunctions.php]
 
Then put the following at the end of your [[LocalSettings.php]]:
 
require_once( "$IP/extensions/ParserFunctions/ParserFunctions.php" );
 
You can also browse the code tree here:
 
* [http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/ParserFunctions/ ParserFunctions in MediaWiki SVN]
 
=== 1.7 ===
The ParserFunctions, including #if, work under 1.7, assuming you're not using an extremely early build.
 
=== 1.6 ===
Most ParserFunctions (except #if, which does not work at all) work just as well on MediaWiki 1.6, but the syntax of ParserFunctions is without the '#' character. If you want to use the '#' character, find this section of ParserFunctions.php:
<pre><nowiki>
$wgParser->setFunctionHook( 'expr', array( &$wgExtParserFunctions, 'expr' ) );
$wgParser->setFunctionHook( 'if', array( &$wgExtParserFunctions, 'ifHook' ) );
$wgParser->setFunctionHook( 'ifeq', array( &$wgExtParserFunctions, 'ifeq' ) );
$wgParser->setFunctionHook( 'ifexpr', array( &$wgExtParserFunctions, 'ifexpr' ) );
$wgParser->setFunctionHook( 'switch', array( &$wgExtParserFunctions, 'switchHook' ) );
</nowiki></pre>
 
Then, replace it with this:
 
<pre><nowiki>
$wgParser->setFunctionHook( '#expr', array( &$wgExtParserFunctions, 'expr' ) );
$wgParser->setFunctionHook( '#if', array( &$wgExtParserFunctions, 'ifHook' ) );
$wgParser->setFunctionHook( '#ifeq', array( &$wgExtParserFunctions, 'ifeq' ) );
$wgParser->setFunctionHook( '#ifexpr', array( &$wgExtParserFunctions, 'ifexpr' ) );
$wgParser->setFunctionHook( '#switch', array( &$wgExtParserFunctions, 'switchHook' ) );
</nowiki></pre>
 
==See also==
*[[Help:Calculation]]
*[[StringFunctions]]
*[[DynamicFunctions]]
*[[:m:Category:Templates using ParserFunctions]]
*[[:en:Category:Templates using ParserFunctions]]
 
[[Category:Handbook templates|{{PAGENAME}}]]
== External links ==
</noinclude><includeonly>
* [http://mail.wikipedia.org/pipermail/wikitech-l/2006-April/thread.html#34685 The discussion about the ParserFunctions in the Wikitech-l list archive]
<br clear="right" />
* [http://mail.wikipedia.org/pipermail/wikitech-l/2006-April/034892.html ParserFunctions trial]
 
[[Category:MediaWikiSystem extensionsadmin handbook]]
</includeonly>

Revision as of 06:46, 5 July 2006