ParserPower escape sequences

From Aeon Garden Software Wiki
Jump to: navigation, search

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.

For example, in MediaWiki, the pipe (|) character is used to separate parameters in template or parser function calls, which is a problem when you want to include a pipe character in a parameter value. For example, {{template|start|end}} sends start to {{{1}}} and end to {{{2}}}. Most wikis create Template:! 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 workaround template protects the pipe character from being interpreted as a parameter separator; escape sequences serve this same purpose and others.

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 (=)
\! )
\0 Nothing

Nearly all ParserPower functions and tags recognize certain escape sequences for most, of 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 Template:! workaround, 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 \!.

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. In ParserPower functions, you can do this by using the \{ and \} sequences for templates and other parser functions. You would just call the inner function like this: {\{#func:value}\}, or for a template: {\{template\!value}\}.