Using_Parser_Functions.md #1

Using MediaWiki Parser Functions
--------------------------------

A survey of some commonly used parser functions and their uses. The
examples on this page refer to templates frequently, so [Using
Templates](Using_Templates "wikilink") is recommended pre-reading.

### What are parser functions used for?

Parser functions are a very advanced MediaWiki feature, either included
in MediaWiki or implemented by extensions, that are typically used in
templates to provide behavior that's more complex than filling in
blanks. Parser functions can be used to do many things, including:

-   Include or exclude a piece of content based on a logical condition
-   Perform mathematical operations
-   Retrieve the current date or time
-   Perform URL encoding on a string prior to constructing a link out of
    it
-   Extract a subset of a string
-   Replace one string with another
-   Create a link conditionally on the existence of the target

Complex templates like <Template:Project> make heavy use of parser
functions to make "decisions" about what behavior to produce depending
on the provided parameter values.

### How do parser functions work?

The basic syntax for parser functions is similar to that used for
templates:

`{{#`**`function`**`:`**`param1`**`|`**`param2...`**`}}`

Note the **\#** before the function name, and the **:** between the
function name and the first parameter.

Unlike templates, which can be added by any contributor just by creating
new pages, new parser functions can only be implemented by MediaWiki
extensions that define their behavior, so unless you're ready to start
writing your own extension and then get the wiki admin to install it,
you're limited to the set of parser functions implemented by the wiki
you're using. The <Special:Version> page lists all of the extensions
installed on the wiki, with extensions that add parser functions listed
under the "parser hooks" heading. MediaWiki itself comes with a few
parser functions as well that are documented in the [MediaWiki
help](http://www.mediawiki.org/wiki/Help:Magic_words#Parser_functions).

An example of a parser function added by an extension is the **\#expr:**
function, which evaluates mathematical expressions. The function accepts
only a single parameter, which is a string containing any of a wide set
of mathematical operators similar to what you might find in a normal
programming language or a decent pocket calculator; see the
\[<http://www.mediawiki.org/wiki/Help:Extension:ParserFunctions>\#.23expr:
help page\] for a list of supported operators. For example, adding the
following code to a page:

`2 + 3 = {{ #expr: 2 + 3 }}`

will produce the following text:

`2 + 3 = {{ #expr: 2 + 3 }}`

This same function might be used to create a simple template called
**Template:Sum** whose source looks like:

`{{{1|0}}} + {{{2|0}}} = {{ #expr: {{{1|0}}} + {{{2|0}}} }}`

and invoking this template with any two numeric values:

`{{Sum|6|9}}`

would produce a string of text representing their sum:

`6 + 9 = 15`

Since there are dozens of parser functions implemented on this wiki, the
usage of each one will not be demonstrated here, but the entries on
<Special:Version> link back to project pages that include documentation
and examples of the functions implemented by each extension.

### Example: creating a link conditionally

The **\#ifexist:** function is a good example of a conditional
statement; that is, a parser function that returns one outcome or
another depending on a condition. This function can be used to create a
template which generates a wiki link if and only if the target already
exists (that is, it will never create a "red link").

The source of the template will be:

`{{#ifexist:{{{1|}}}|[[{{{1|}}}]]|{{{1|}}}}}`

Since that looks like a string of line noise, here it is with some extra
whitespace and with the parameter bolded:

`{{ #ifexist: `**`{{{1|}}}`**` | `[`}}}'''`]('''<nowiki>{{{</nowiki>1 "wikilink")` | `**`{{{1|}}}`**` }}`

This expression says that if the page referenced by the parameter
{{{1|}}} exists, the output will be "\[\[{{{1|}}}\]\]", that is, the
parameter with double brackets around it (creating a link to it). If
not, the output will simply be the unaltered parameter, {{{1|}}}.

Supposing we call our template **Template:SafeLink**, giving the name of
a real page as the parameter:

`{{SafeLink|FAQ}}`

gets us a link:

`{{#ifexist:FAQ|`[`FAQ`](FAQ "wikilink")`|FAQ}}`

whereas passing in a nonexistent page name:

`{{SafeLink|OIWEJFLKJSLDKJF}}`

gets us plain text:

`{{#ifexist:OIWEJFLKJSLDKJF|`[`OIWEJFLKJSLDKJF`](OIWEJFLKJSLDKJF "wikilink")`|OIWEJFLKJSLDKJF}}`

This type of expression is used a few times in <Template:Project> to
generate links to user pages and categories if and only if they already
exist.

### Example: DepotBrief

<Template:DepotBrief> is a fairly complex example of manipulating a
string using parser functions. Here is the source for it:

`{{#ifeq: {{#sub:{{{1}}}|-1}} | / | `\
`  {{ DepotPath|{{{1}}}| {{#sub:{{{1}}}|{{#expr:{{#rpos:{{#sub:{{{1}}}|0|-1}}|/}}+1}}|0}} }} |`\
`  {{#ifeq: {{#sub:{{{1}}}|-4}} | /... |`\
`    {{ DepotPath|{{#sub:{{{1}}}|0|-3}}| {{#sub:{{#sub:{{{1}}}|0|-3}}|{{#expr:{{#rpos:{{#sub:{{#sub:{{{1}}}|0|-3}}|0|-1}}|/}}+1}}|0}} }} |`\
`    {{ DepotFile|{{{1}}}|{{#sub:{{{1}}}|{{#expr:{{#rpos:{{{1}}}|/}}+1}}|0}} }}`\
`  }}`\
`}}`

The purpose of this template is to examine its parameter to determine if
it's a depot directory path (ending in "/...") or a depot file path, and
generate a useful link that uses the last component of the path as the
link text. If it's a directory path, <Template:DepotPath> is used to
generate a P4Web link to it; if it's a file path, <Template:DepotFile>
is used to generate a WebKeeper link. In either case, a sequence of
string operations is used to find the last component of the path (by
finding the index of the last "/" character and extracting everything
after that index), and this is passed as the link text.

It is not recommended that you try to create something like this as your
first experiment with templates and parser functions.

### Example: RecentChanges

<Template:RecentChanges> is a simpler example that uses the
**\#p4changes:** function implemented by the Perforce extension, along
with a couple of other templates, <Template:DepotRSS> and
<Template:DepotNormalized>, to generate a section on a page out of
changelists recently submitted to a given depot path:

`===Recent Changes {{DepotRSS|{{{1}}}}} ===`\
`{{#p4changes:5|{{DepotNormalized|{{{1}}}}}|full}}`

<Template:DepotNormalized> itself uses a few string parser functions and
another template, <Template:TrimWhitespace>, to ensure that the
parameter is returned in a "normalized" style with extraneous whitespace
removed and trailing "/" characters converted to the Perforce wildcard
expression "/...":

`{{#ifeq:{{#sub:{{TrimWhitespace|{{{1}}}}}|-1}}|/|{{TrimWhitespace|{{{1}}}}}...|{{TrimWhitespace|{{{1}}}}}}}`

The **\#p4changes:** function is then passed 5 (the number of
changelists to return), the normalized depot path resulting from passing
the parameter to <Template:DepotNormalized>, and "full" (for full change
descriptions). The table returned by this function is placed under a
level 3 heading with an RSS feed icon provided by <Template:DepotRSS>.

For examples of this template in action, go to the
<Template:RecentChanges> page and click "What links here" from the
Toolbox.