| |||||
What is an escape sequence?[]
Escape sequences are sequences of characters that represent another character and which are used to prevent special interpretation or processing of that character.
One common example in MediaWiki is the pipe (|) character, which is used to separate parameters in template or parser function calls, making it difficult to include a pipe character in a parameter value in the odd case when this is desirable. As a simple example,{{template|start|end}} sends start to {{{1}}} and end to {{{2}}}. Most wikis provide {{!}} as a workaround that returns a pipe character, and this works much like an escape sequence. Using this workaround, for example, in {{template|start{{!}}end}}, makes sure {{{1}}} is start|end. The ParserPower escape sequences provide solutions to a number of similar problems.
Escape sequences in ParserPower[]
\n
|
New line |
\_
|
Space |
\\
|
Backslash (\)
|
\{
|
Left curly bracket ({)
|
\}
|
Right curly bracket (})
|
\(
|
Left square bracket ([)
|
\)
|
Right square bracket (])
|
\l
|
Less than (<)
|
\g
|
Greater than (>)
|
\e
|
Equal sign (=)
|
\!
|
Pipe (|)
|
\0
|
Nothing |
Nearly all ParserPower functions and tags recognize certain escape sequences for most, if not all, of their parameters. These sequences can be seen on the right. The documentation for each function will indicate when a function or parameter doesn't recognize these escape sequences, or if there are any special considerations in using them.
Note: \l, \g, and \e were added in 1.0.
Uses for escape sequences[]
Pipe characters in parameter values[]
As with {{!}}, the \! is an alternative way to get pipe characters into parameter values in ParserPower functions. In most cases, they will have the same results, but note that the list handling functions treat these somewhat differently as each is replaced at a different time when using Template:! and \!.
Note that in general, {{!}} is often a better solution outside of ParserPower functions, as the ParserPower equivalent of {{template|start{{!}}end}} is more awkward: {{template|{{#uesc:start\!end}} }}, but the ParserPower way may be superior when a lot of escaping is needed in a function or template call.
Protecting leading and trailing whitespace[]
Virtually all parser functions trim off any whitespace, including spaces and newline characters, that are at the beginning and end of a value. This is true even of ParserPower tags and functions, but some of the escape characters can be used to protect it from this trimming. This represents a large part of ParserPower's #uesc function's utility.
Protecting whitespace with \_ and \n[]
For example, let's say you have a template that takes a city and state name for cities in the United States. You want to separate them with a comma and a space if both city and state are provided, but not if only one is provided. With ParserPower and the #if function from ParserFunctions, you can do this:
{{#uesc:{{#trim:{{{city|}}} }}{{#if:{{{state|}}}|{{#if:{{{city|}}}|,\_|}}{{#trim:{{{state}}} }}|}} }}
This works because the #if function in ParserFunctions doesn't recognize that escape sequence and leaves it alone. So if city and state both have a value other than whitespace, the inner #if puts ,\_ between the city and state. The #uesc function then replaces the \_ with a space because it does recognize it. Thus, the escaped space is protected from being trimmed off by either #if function because neither see it as a space. The \n sequence protects newline characters in the same way.
Protecting whitespace with \0[]
The \0 escape sequence can also be used to protect whitespace. It is replaced with nothing, so, for example, {{#uesc:\0 word \0}} protects the three spaces on each side of word from being trimmed. This is because the trimming is performed before escape sequences are replaced, and when the replacement happens, the \0 sequences are simply removed.
Delaying template or parser function processing[]
Usually a template or parser function inside another parser function will be processed first. In some cases, you may want the outer function to be processed first, and this happens quite often in list-handling functions. This is the primary purpose of the <esc> tag: you can use something like <esc>{{#func:value}}</esc> or <esc>{{template|value}}</esc>
Alternately, you can by using the \{ and \} sequences directly for templates and other parser functions. You would just call the inner function like this: {\{#func:value}\}, or for a template: {\{template\!value}\}. (Note that escaping pipe characters with \! is also important, or the first one will be interpreted as the end of the argument value.)
One caveat is when values from template parameters needed to be included, as delaying their replacement will almost certainly not be desired. When using <esc> tags, just close the tag before the parameter and reopen after to handle the parameter correctly, like this: <esc>{{template|</esc>{{{1|}}}<esc>|value}}</esc>. In the case of using escape, just don't escape the brackets: just write it normally like {{{1|}}}
| |||||