Extension:ParserPower/List handling functions

Manipulating lists

The most powerful feature of ParserPower is its ability to manipulate lists separated by a common delimiter. While this is a useful feature in general, this makes ParserPower a great companion to extensions such as Semantic MediaWiki.

The primary advantage gained is in being able to code templates to handle parameters that can take an arbitrary number of values.

Multiple value template parameters without ParserPower

With MediaWiki alone, or even with its packaged extensions, one is left with two choices when you need to send a list to a parameter.

The first is that you leave it to the template caller to properly format and code the list, such as say:

list=[[item1]]<br />
[[item2]]<br />
[[item3]]<br />
[[item4]]<br />

which is troublesome if you want to do something nontrivial with each value, such as categorize the page according to each one. By this method, you have to leave it to the template user to do the categorization.

The second is to provide a number of parameters for the same thing, such as:

item1=item1
item2=item2
item3=item3
item4=item4

but first, you can accept only as many values as you provide parameters for, and you have to handle each parameter separately even if you want to do the same thing with each of them. This means you copy-paste code for each parameter or write another template, and even with a separate template, you still have to write a template call for each parameter.

ParserPower's alternative for multiple value template parameters

ParserPower's list handling functions provide a more user-friendly option for both the users of your template and yourself. By using appropriate ParserPower functions in your template, the users of your template could do something like this instead:

list=item1,item2,item3,item4

and with one call to #listmap, #lstmap, or #listmaptemp, you can easily turn each into a link, categorize according to their values, and turn the commas into line breaks. In many cases, a separate template isn't needed either; most simple cases can be handled without it.

Note on lists, input separators, and escape sequences

Most of these functions accept a list and an input separator that separates the item. ParserPower escape sequences are recognized in the list, but only after it has been separated into individual items. This means if you use an escape sequence as a separator, you have to add a extra backslash to the beginning of the input separator parameter because the escape sequences there are processed before the split.

Example:

{{#lstsep:item1\!item2\!item3|\!|,\_}}

won't work as expected! It gives you item1|item2|item3 instead of item1, item2, item3.

\! will be replaced with | in the input separator, but it will try to split the list before \! is replaced in the list itself. It will try to find | in the list, and it won't see the \! as | yet.

{{#lstsep:item1\!item2\!item3|\\!|,\_}}

is correct. It gives you item1, item2, item3, as expected.

\\ in the input separator parameter will be replaced with \, and when splitting the list, it will split it by the \! sequences that haven't yet been replaced.

If you can avoid it, it is probably best not to use an escape sequence as the separator for your list. There is no harm is using the characters the escape sequences represent, though. For example:

{{#lstsep:item1 item2 item3|\_|,\_}}

will give you item1, item2, item3 as expected.

#lstcnt

{{#lstcnt:list|separator}}

(Added in 0.95). This simple list handling function counts the number of items within the given list using the given separator. Empty values are not counted.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

#lstsep

{{#lstsep:list|input separator|output separator}}

This simple list handling function exchanges the input separator in the given list with the new output separator. It is similar to the #replace function from ParserFunctions or StringFunctions in that respect, but it also trims leading and trailing whitespace from each item in the list and discards empty values.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

#lstelem

{{#lstelem:list|input separator|index}}

This function returns only the item identified by the given index, or nothing if the index refers to an item not in the list. The index can be specified as a positive or negative number. 1 refers to the top nonempty item in the list, 2 to the second, and so on. -1 refers to the bottom nonempty item in the list, -2 to the second nonempty item from the bottom, and so on.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

#lstsub

{{#lstsub:list|input separator|output separator|start index|length}}

This function returns the part of the list, where items are delimited by input separator, identified by the given start index and length. If the range defined by the start index and length is entirely outside the item, nothing is returned. If it includes items beyond the list, only the items that actually exist within the range are returned.

The start index can be specified as a positive or negative number. 1 refers to the top nonempty item in the list, 2 to the second, and so on. -1 refers to the bottom nonempty item in the list, -2 to the second nonempty item from the bottom, and so on. 1 is assumed if no value is given.

The length can also be given as a positive or negative number. When given as a positive number, the function simply returns that many nonempty items from the start index on if there are sufficient nonempty items in the list. Otherwise, it will returns all items from the start index to the end of the list. If length is given as a negative number, it will omit returning items from the end of the list. -1 will omit the last nonempty in the list, -2 will omit the last two, and so on. If length isn't specified at all, then all nonempty items from start index to the end of the list will be returned.

The partial list will be returned with the items delimited by the given output separator.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

#lstfnd

{{#lstfnd:item to find|list|separator|case sensitivity option}}

(Added in 0.95). This function searches the list for the given item, and if it finds it, it returns the first occurrence. Otherwise, it returns nothing. For case sensitivity in the search, specify cs as the case sensitivity option; this will mean a search for example will match only example, not Example or EXAMPLE. Specify ncs for a case-insensitive search, or omit it, as ncs is the default mode.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

#lstind

{{#lstind:item to find|list|separator|options}}

(Added in 1.0). This function searches the list for the given item, and if it finds it, it returns the index. Otherwise, it returns nothing.

To search the list from the end to the beginning, specify desc in the options; otherwise, specify asc or omit it to search from the beginning to the end.

If neg is specified in the options, a negative index will be returned. In this case, -1 would refer to the bottom nonempty value in the list, -2 to the first nonempty value above that, and so on. Otherwise, specify pos or omit it to have a positive index returned instead. For positive indexes, 1 refers to the topmost nonempty item in the list, 2 to the second nonempty item, and so on.

For case sensitivity in the search, specify cs in the options; this will mean a search for example will match only example, not Example or EXAMPLE. Specify ncs for a case-insensitive search, or omit it, as ncs is the default mode.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

#lstapp

{{#lstapp:list|separator|new item}}

(Added in 0.95.) This simple list handling function adds a single item to the end of a list with the given separator. Note that as with #lstsep, leading and trailing whitespace are trimmed from each value in the list and empty values are discarded.

If an empty list is specified, the new item is output with leading and trailing whitespace trimmed. If an empty new item is specified, the list is output with leading and trailing whitespace trimmed from each item.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

#lstprep

{{#lstprep:new item|separator|list}}

(Added in 0.95.) This simple list handling function adds a single item to the beginning of a list with the given separator. Note that as with #lstsep, leading and trailing whitespace are trimmed from each value in the list and empty values are discarded.

If an empty list is specified, the new item is output with leading and trailing whitespace trimmed. If an empty new item is specified, the list is output with leading and trailing whitespace trimmed from each item.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

#lstjoin

{{#lstjoin:first list|first input separator|second list|second input separator|output separator}}

(Added in 0.95.) This simple list handling function combines two lists together and can work with lists having different separators. Note that as with #lstsep, leading and trailing whitespace are trimmed from each value in each list and empty values are discarded.

The lists are combined with the output separator, and if they are different, the separators within each list are also replaced with the output separator. Either list value can be empty, in which case the other list will be output with the new output separator. If both lists are empty, nothing will be output.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

#listfilter

{{#listfilter:
  |list=
  |insep=
  |outsep=
  |keep=
  |keepsep=
  |keepcs=
  |remove=
  |removesep=
  |removecs=
  |token=
  |tokensep=
  |fieldsep=
  |indextoken=
  |pattern=
  |template=
  |counttoken=
  |intro=
  |outro=
  |default=
}}

(Added in 0.95). This list handling function takes a given list and returns a new list containing only the values that match given criteria for items to keep, or alternately, which do not match given criteria for items to remove.

Each parameter is explained below:

list

This is where the list to process goes. It's okay to put an empty list here, but the function simply outputs nothing in this case. Escape sequences are recognized after the list is split into individual items.

insep

This identifies the character sequence used to separate the items in list. Escape sequences are recognized.

outsep

This is the character sequence that should separate the items after the list is processed. Escape sequences are recognized.

keep

One basic way to specify criteria is simply to specify the exact value or values to keep. Note that this is case insensitive by default, but this can be changed by using keepcs. Note that if you use keep, the parameters remove, pattern and template will be ignored.

keepsep

This is the character used to separate the values to keep in keep. By default, this is a comma.

keepcs

Setting this to yes will make the process case-sensitive for keep, so that if item is in keep, ITEM would be removed from the list. By default, this is no.

remove

Another basic way to specify criteria is simply to specify the exact value or values to remove. Note that this is case insensitive by default, but this can be changed by using removecs. Note that if you use remove, the parameters pattern and template will be ignored.

removesep

This is the character used to separate the values to remove in remove. By default, this is a comma.

removecs

Setting this to yes will make the process case-sensitive for values, so that if item is in values, ITEM would not be removed from the list. By default, this is no.

token and pattern

These parameters allow you to specify some wikicode to run on each item in the list that returns either keep or remove. For each item in the list, the token in pattern is replaced with the value and the wikicode is processed. Any time that remove is returned, the list item will be removed from the list. This is case insensitive, so REMOVE will also remove the item. So for a token of @@@@ and a pattern of {{#ifeq:@@@@|Main page|remove|keep}}, a list value of Main page returns remove and will not be in the returned list, but Project:Community portal returns keep and will remain part of the list.

tokensep and fieldsep

These, combined with token and pattern, are used to provide more flexibility in testing values. fieldsep identifies a character sequence to use in separating each list item into fields. tokensep, which is a comma by default, lets you specify a token for each field. So, for a list of John Doe,Jane Smith. With fieldsep of \_, token of $1,$2 and a pattern of {{#ifeq:$2|Smith|remove|keep}}, John Doe will return keep and be returned in the list, but Jane Smith will return remove and be removed from the list.

indextoken

(Added in 1.0.) When combined with token and pattern, this specifies a token that will be replaced with a numeric index in each list value as it's processed. The indexes start counting at 1.

template and fieldsep

A more advanced way to test values is to pass each value to a template. You simply give the name of a template to template, and each value is passed through as parameter 1. The exception is if you specify fieldsep. In this case, the value is separated into fields and the first field is passed through to parameter 1, the second to parameter 2, and so on. Note that if you specify template, token, tokensep, and pattern are ignored. As with using token and pattern, the item will be removed only if the template returns remove for the item in question. Note that if template is specified, token, tokensep, and pattern will be ignored.

counttoken

(Added in 1.0.) This defines a optional token that will be replaced with the numeric count of items returned where it is found in intro and outro below. It is not used if neither of those parameters are specified. It can be left blank or omitted.

intro and outro

intro takes content to output before any items in the list. outro takes content to output after any items in the list. Using these is different from just placing content before and after the #listfilter call, however, because the intro and outro are suppressed if the list is empty either before or after filtering. This is useful for avoiding embedding #listmap calls awkwardly in #if calls in many situations.

default

default takes content to output should the list be empty, either before or after filtering. This is useful for avoiding embedding list function calls awkwardly in #if calls in many situations, or for doing the same in the list parameter itself.

#lstfltr

{{#lstfltr:items to keep|items separator|list|input separator|output separator|case sensitivity option}}

(Added in 0.95). This is a shortcut version of #listfilter that returns the given list with only the specified items. If the items in question are in the list multiple times, each instance is returned. The case sensitivity option can be either cs for case sensitive or ncs for case-insensitive. ncs is the default option.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

#lstrm

{{#lstrm:item to remove|list|input separator|output separator|case sensitivity option}}

(Added in 0.95). This is a shortcut version of #listfilter that returns the given list with the specified item removed. If the item in question is in the list multiple times, each instance is removed. The case sensitivity option can be either cs for case sensitive or ncs for case-insensitive. ncs is the default option.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

#lstcntuniq

{{#lstcntuniq:list|separator|case sensitivity option}}

(Added in 0.95). This simple list handling function counts the number of unique items within the given list using the given separator. Empty values are not counted. The case sensitivity option can be either cs for case sensitive or ncs for case-insensitive. ncs is the default option.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

#listunique

{{#listunique:
  |list=
  |insep=
  |outsep=
  |uniquecs=
  |token=
  |tokensep=
  |fieldsep=
  |indextoken=
  |pattern=
  |template=
  |counttoken=
  |intro=
  |outro=
  |default=
}}

This powerful function allows you to reduce a list down to unique values, either by straightforward uniqueness of the actual values, or uniqueness of a key generated by a template or provided wikicode.

Each parameter is explained below:

list

This is where the list to reduce goes. It's okay to put an empty list here, but the function simply outputs nothing in this case. Escape sequences are recognized after the list is split into individual items.

insep

This identifies the character sequence used to separate the items in list. Escape sequences are recognized.

outsep

This is the character sequence that should separate the items after the list is sorted. Escape sequences are recognized.

uniquecs

Setting this to yes will make the uniqueness comparisons case-sensitive. By default, this is no. Note this is only relevant when no template or no token and pattern are used, because in those cases, the generated keys are compared, and that is always done in a case-sensitive manner.

token and pattern

These are used to generate a key for each value, and only the first value to generate a given key is kept in the list. When token is found in pattern, it is replaced by the value to generate the key. So if you provide a token of @@@@ and a pattern of {\{NAMESPACENUMBER:@@@@}\}, then with values Main Page, Talk:ParserPower and ParserPower, you'd get keys of 0, 1, and 0, so only Main Page and Talk:ParserPower would be returned in the new list. As another example, a pattern of {\{#sub:@@@@\!0\!1}\} with a token of @@@@ would give you the first letter as a key, which would be a way to reduce values to the first one starting with a particular letter.

tokensep and fieldsep

These, combined with token and pattern, are used to provide more flexibility in generating keys. fieldsep identifies a character sequence to use in separating each list item into fields. tokensep, which is a comma by default, lets you specify a token for each field. So, for a list of John Doe,Jane Smith,Bob Smith. With fieldsep of \_, token of $1,$2 and a pattern of $2, the keys become Doe, Smith and Smith. As Jane Smith was the first to generate the Smith key, her name will be returned in the output list, but Bob Smith will not because the Smith key was already generated. tokensep only needs to be specified if you use something other than a comma to separate the tokens in token. (Note: this example only works when everyone has only two names.)

indextoken

(Added in 1.0.) When combined with token and pattern, this specifies a token that will be replaced with a numeric index in each list value as it's processed. The indexes start counting at 1.

template and fieldsep

A more advanced way to generate keys is to pass each value to a template. You simply give the name of a template to template, and each value is passed through as parameter 1. The exception is if you specify fieldsep. In this case, the value is separated into fields and the first field is passed through to parameter 1, the second to parameter 2, and so on. Note that if you specify template, token, tokensep, and pattern are ignored.

counttoken

(Added in 1.0.) This defines a optional token that will be replaced with the numeric count of items returned where it is found in intro and outro below. It is not used if neither of those parameters are specified. It can be left blank or omitted.

intro and outro

intro takes content to output before any items in the list. outro takes content to output after any items in the list. Using these is different from just placing content before and after the #listunique call, however, because the intro and outro are suppressed for empty lists. This is useful for avoiding embedding list functtion calls awkwardly in #if calls in many situations.

default

default takes content to output should the given list be empty. This is useful for avoiding embedding list function calls awkwardly in #if calls in many situations, or for doing the same in the list parameter itself.

#lstuniq

{{#lstuniq:list|input separator|output separator|case sensitivity option}}

(Functionality changed in 0.95).This does the same as #lstsep above, but it also removes duplicate items from the list. The case sensitivity option can be either cs for case sensitive or ncs for case-insensitive. ncs is the default option.

Each parameter recognizes ParserPower escape sequences, though as noted above, escape sequences are processed in the list after it is split into individual items.

Version note: In 0.9, #lstuniq did not have a case sensitivity option. It functioned in a case-sensitive manner without an alternative option, different from the default in later versions.

#listsort

{{#listsort:
  |list=
  |insep=
  |outsep=
  |sortoptions=
  |duplicates=
  |token=
  |tokensep=
  |fieldsep=
  |indextoken=
  |pattern=
  |template=
  |subsort=
  |subsortoptions=
  |intro=
  |outro=
  |default=
}}

This powerful and complex function allows you to sort a list in a variety of ways. You only have to provide the parameters you need, so it works for both simple and complex sorts, though the #lstsrt shortcut function may be preferable for simple sorts.

Each parameter is explained below:

list

This is where the list to sort goes. It's okay to put an empty list here, but the function simply outputs nothing in this case. Escape sequences are recognized after the list is split into individual items.

insep

This identifies the character sequence used to separate the items in list. Escape sequences are recognized.

outsep

This is the character sequence that should separate the items after the list is sorted. Escape sequences are recognized.

sortoptions

One or more of the following keywords:

• alpha: sort the values alphanumerically. This is default and the option to use when the list is made up of words.
• numeric: sort the values numerically. This is the option to use when the list is made up of numbers.
• ncs: short for not case sensitive, meaning that uppercase and lowercase letters are treated as the same. "alpha" will be placed before "BETA" in such a sort. This is default and only relevant to alpha sorts. This is ignored in numeric sorts.
• cs: short for case sensitive, meaning that uppercase and lowercase letters are treated differently. "BETA" will be placed before "alpha" in such a sort. This only relevant to alpha sorts. This is ignored in numeric sorts.
• asc: sorts in ascending order. For alpha sorts, this means in alphabetical order. For numeric sorts, this means from smallest to largest.
• desc: sorts in descending order. For alpha sorts, this means in reverse alphabetical order. For numeric sorts, this means from largest to smallest.

Note that if token and pattern or template are provided, these sort options apply to the sort keys generated, not to the values themselves.

duplicates

Either keep to keep all duplicates in the list or strip to remove duplicates. keep is the default option.

token and pattern

These are used to generate a sort key to sort the values by instead of just sorting the values themselves. When token is found in pattern, it is replaced by the value to generate the sort key. So if you provide a token of @@@@ and a pattern of {\{NAMESPACENUMBER:@@@@}\}, then with values Talk:ParserPower, Main Page, and Project:Community Portal, you'd get sort keys of 1, 0, and 4, which would be useful for sorting page names by their namespace.

indextoken

(Added in 1.0.) When combined with token and pattern, this specifies a token that will be replaced with a numeric index in each list value as it's processed. The indexes start counting at 1.

tokensep and fieldsep

These, combined with token and pattern, are used to provide more flexibility in generating sort keys. fieldsep identifies a character sequence to use in separating each list item into fields. tokensep, which is a comma by default, lets you specify a token for each field. So, for a list of John Doe,Jane Smith. With fieldsep of \_, token of $1,$2 and a pattern of $2 $1, the sort keys become Doe John and Smith Jane, which would sort them in last name order. tokensep only needs to be specified if you use something other than a comma to separate the tokens in token. (Note: this example only works when everyone has only two names.)

template and fieldsep

A more advanced way to generate sort keys is to pass each value to a template. You simply give the name of a template to template, and each value is passed through as parameter 1. The exception is if you specify fieldsep. In this case, the value is separated into fields and the first field is passed through to parameter 1, the second to parameter 2, and so on. Note that if you specify template, token, tokensep, and pattern are ignored.

subsort and subsortoptions

subsort accepts either yes or no. If yes, this indicates that any values with the same sort key should be sorted according to the options in subsortoptions (or the defaults if none are provided). The available subsortoptions are the same as for sortoptions.

counttoken

(Added in 1.0.) This defines a optional token that will be replaced with the numeric count of items returned where it is found in intro and outro below. It is not used if neither of those parameters are specified. It can be left blank or omitted.

intro and outro

(Added in 0.95.) intro takes content to output before any items in the list. outro takes content to output after any items in the list. Using these is different from just placing content before and after the #listsort call, however, because the intro and outro are suppressed for empty lists. This is useful for avoiding embedding list function calls awkwardly in #if calls in many situations.

default

(Added in 0.95.) default takes content to output should the given list be empty. This is useful for avoiding embedding #listmap calls awkwardly in #if calls in many situations, or for doing the same in the list parameter itself.

#lstsrt

{{#lstsrt:list|input separator|output separator|sort options}}

This is a shortcut version of #listsort for when sort keys are not needed. The sort options are the same as for sortoptions above.

#listmap

{{#listmap:
  |list=
  |insep=
  |outsep=
  |token=
  |tokensep=
  |fieldsep=
  |indextoken=
  |pattern=
  |template=
  |sortmode=
  |sortoptions=
  |duplicates=
  |counttoken=
  |intro=
  |outro=
  |default=
}}

This is the most powerful list handling function in ParserPower. It not only allows one to sort values in the list, but change them in some way. For example, one might add linking brackets to each value, or use each value to add the page to a given category, or more. Unlike #listsort, however, it does not have the ability to generate sort keys and sort by those; it can do only simple alphabetical and numerical sorts.

Each parameter is explained below:

list

This is where the list to process goes. It's okay to put an empty list here, but the function simply outputs nothing or the value of default in this case. Escape sequences are recognized after the list is split into individual items.

insep

This identifies the character sequence used to separate the items in list. Escape sequences are recognized.

outsep

This is the character sequence that should separate the items after the list is sorted. Escape sequences are recognized.

token and pattern

The most basic way to change each value in the list is provide a token and a pattern that contains that token. For each item in the list, the token in pattern is replaced with the value and the result is returned. So for a token of @@@@ and a pattern of [[@@@@]], list values of Main page and Project:Community portal become [[Main page]] and [[Project:Community portal]].

tokensep and fieldsep

These, combined with token and pattern, are used to provide more flexibility in changing values. fieldsep identifies a character sequence to use in separating each list item into fields. tokensep, which is a comma by default, lets you specify a token for each field. So, for a list of John Doe,Jane Smith. With fieldsep of \_, token of $1,$2 and a pattern of $2, $1, the values become Doe, John and Smith, Jane. tokensep only needs to be specified if you use something other than a comma to separate the tokens in token. (Note: this example only works when everyone has only two names.)

indextoken

(Added in 1.0.) When combined with token and pattern, this specifies a token that will be replaced with a numeric index in each list value as it's processed. The indexes start counting at 1.

template and fieldsep

A more advanced way to change values is to pass each value to a template. You simply give the name of a template to template, and each value is passed through as parameter 1. The exception is if you specify fieldsep. In this case, the value is separated into fields and the first field is passed through to parameter 1, the second to parameter 2, and so on. Note that if you specify template, token, tokensep, and pattern are ignored.

sortmode

(Changed in 0.95.) One of the following keywords:

• nosort: returns the values in the order they were passed in. This is default.
• presort: sorts the values before changing them. Depending on the changes, this might mean the final values aren't sorted in alphabetical or numerical order, but it may sometimes make more sense to sort by the original values. Also, if the changes won't affect the order, presorting may be a little more efficient.
• sort or postsort: sorts the values after changing them. If the changes will affect the sorting order, this is probably the most desirable option.
• pre/postsort: sorts the values before and after changing them. There may be some unusual circumstances, such as processing that uses a variable to store the previous value, where this just might be desirable, but in most cases this option is not recommended.

When in doubt, if you want sorting, one is least likely to go wrong with sort.

Before 0.95, sort sorted values both before and after the change, and pre/postsort was not recognized. As it is rare for sorting before and after to be desirable, it was decided that sort should apply to the option that will usually be the preferred option.

sortoptions

One or more of the following keywords:

• alpha: sort the values alphanumerically. This is default and the option to use when the list is made up of words.
• numeric: sort the values numerically. This is the option to use when the list is made up of numbers.
• ncs: short for not case sensitive, meaning that uppercase and lowercase letters are treated as the same. "alpha" will be placed before "BETA" in such a sort. This is default and only relevant to alpha sorts. This is ignored in numeric sorts.
• cs: short for case sensitive, meaning that uppercase and lowercase letters are treated differently. "BETA" will be placed before "alpha" in such a sort. This only relevant to alpha sorts. This is ignored in numeric sorts.
• asc: sorts in ascending order. For alpha sorts, this means in alphabetical order. For numeric sorts, this means from smallest to largest.
• desc: sorts in descending order. For alpha sorts, this means in reverse alphabetical order. For numeric sorts, this means from largest to smallest.

Naturally, these are ignored if sortmode is set to nosort or isn't set at all.

duplicates

(Changed in 0.95.) One of the following keywords:

• keep: keeps duplicate values in the list.
• prestrip: removes duplicate values before the values are changed. This is useful if you want to keep any duplicate values than occur after the items are changed. Alternatively, if the changes are such that the values will still be unique after changing, prestripping is more efficient.
• strip or poststrip: removes duplicate values after the values are changed. If you don't want any duplicates in the output and your changes might cause some different input values to become the same, you'll need to poststrip.
• pre/poststrip: removes duplicate values both before and after the values are changed. In some cases, this may avoid redundant changes in the processing stage and may be more efficient overall, especially if the changes are nontrivial. In most cases, this will have the same result at poststrip, but will do it faster in some cases and slower in others.

When in doubt, it's probably best to just choose strip if you want unique values at the end.

Before 0.95, strip removed duplicate values before and after the change, and pre/poststrip was not recognized. As it is rare for removal before and after to be desirable, it was decided that strip should apply to the option that will usually be the preferred option.

counttoken

(Added in 1.0.) This defines a optional token that will be replaced with the numeric count of items returned where it is found in intro and outro below. It is not used if neither of those parameters are specified. It can be left blank or omitted.

intro and outro

(Added in 0.95.) intro takes content to output before any items in the list. outro takes content to output after any items in the list. Using these is different from just placing content before and after the #listmap call, however, because the intro and outro are suppressed for empty lists, whether it is empty before or after processing. This is useful for avoiding embedding list function calls awkwardly in #if calls in many situations.

default

(Added in 0.95.) default takes content to output should the given list be empty or should it be empty after processing. This is useful for avoiding embedding #listmap calls awkwardly in #if calls in many situations, or for doing the same in the list parameter itself.

#lstmap

{{#lstmap:list|input separator|token|pattern|output separator|sort mode|sort options}}

This is a shortcut version of #listmap that allows you to change values with a simple single token pattern as with the token and pattern parameters of #listmap. It doesn't allow you to use a template to change values, nor does it allow the use of a field separator. To be accurate, it simply ignores any field separator in the values. You can also use the sorting options of #listmap, but you can't strip duplicates.

#lstmaptemp

{{#lstmaptemp:list|template|input separator|output separator|sort mode|sort options}}

This is a shortcut version of #listmap that allows you to change values with a template as with the template parameter of #listmap. It doesn't allow you to use a token and pattern to change values, nor does it allow the use of a field separator. To be accurate, it simply ignores any field separator in the values. You can also use the sorting options of #listmap, but you can't strip duplicates.

#listmerge

{{#listmerge:
  |list=
  |insep=
  |outsep=
  |token1=
  |token2=
  |tokensep=
  |fieldsep=
  |matchpattern=
  |mergepattern=
  |matchtemplate=
  |mergetemplate=
  |sortmode=
  |sortoptions=
  |counttoken=
  |intro=
  |outro=
  |default=
}}

This function is used to compare all items in a list to each other, one pair at a time, and merge those that are common in some way according to the specified logic. The function automatically runs additional passes over all items until the list is either reduced to a single item, or it makes it through a complete pass without the number of items in the list getting any smaller.

It can also sort the list values both before and after such merging. Unlike #listsort, however, it does not have the ability to generate sort keys and sort by those; it can do only simple alphabetical and numerical sorts.

Each parameter is explained below:

list

This is where the list to process goes. It's okay to put an empty list here, but the function simply outputs nothing or the value of default in this case. Escape sequences are recognized after the list is split into individual items.

insep

This identifies the character sequence used to separate the items in list. Escape sequences are recognized.

outsep

This is the character sequence that should separate the items after the list is sorted. Escape sequences are recognized.

token1, token2, matchpattern and mergepattern

These parameters are one way to specify the logic that determines what pairings should be merged and how that merging is handled. This is done by specifying character sequences that will represent each item in token1 and token2, which must be different for this function to work correctly. These sequences are then included in wikicode in matchpattern and mergepattern. As each pair of values is processed, the token1 and token2 sequences in matchpattern are replaced by the first and second values in the pair, respectively. The wikicode is then processed, and if it resolves to yes, the pair of items will then be merged. This is done by using mergepattern, which functions largely the same way: the token sequences are replaced and the wikicode is processed to get the new value.

tokensep and fieldsep

These, combined with token1, token2, matchpattern and mergepattern, increase the flexibility of using patterns to find matches and merge like items. The character sequence specified in fieldsep is used to separate each value in the pair into fields, and tokensep is used to specify a character that separates the tokens representing each field. tokensep is a comma by default. Again, every token must be different; a token used in token1 cannot be reused in token2 for the function to operate correctly.

matchtemplate, mergetemplate, and fieldsep

Another way to specify the logic for matching and merging pairs of values is through templates. When using this approach, each pair is processed by calling the template in matchtemplate with the first value of the pair passed as the first parameter and the second value as the second. If the template returns yes, the mergetemplate is called, again with the first value passed as the first parameter and the second value as the second. The result of that template call becomes the merged value. This behavior changes if fieldsep is specified, as this causes each value to be separated into fields by that character. For each template, each field of the first value is passed in in order, then the fields of the second. For example, if a given fieldsep results in each value being divided into two fields, parameters 1 and 2 get the fields from the first value and parameters 3 and 4 get the fields from the second value.

sortmode

One of the following keywords:

• nosort: returns the values in the order they were passed in. This is default.
• presort: sorts the values before changing them. Depending on the changes, this might mean the final values aren't sorted in alphabetical or numerical order, but it may sometimes make more sense to sort by the original values. Also, if the changes won't affect the order, presorting may be a little more efficient.
• sort or postsort: sorts the values after changing them. If the changes will affect the sorting order, this is probably the most desirable option.
• pre/postsort: sorts the values before and after changing them. There may be some unusual circumstances, such as processing that uses a variable to store the previous value, where this just might be desirable, but in most cases this option is not recommended.

When in doubt, if you want sorting, one is least likely to go wrong with postsort.

sortoptions

One or more of the following keywords:

• alpha: sort the values alphanumerically. This is default and the option to use when the list is made up of words.
• numeric: sort the values numerically. This is the option to use when the list is made up of numbers.
• ncs: short for not case sensitive, meaning that uppercase and lowercase letters are treated as the same. "alpha" will be placed before "BETA" in such a sort. This is default and only relevant to alpha sorts. This is ignored in numeric sorts.
• cs: short for case sensitive, meaning that uppercase and lowercase letters are treated differently. "BETA" will be placed before "alpha" in such a sort. This only relevant to alpha sorts. This is ignored in numeric sorts.
• asc: sorts in ascending order. For alpha sorts, this means in alphabetical order. For numeric sorts, this means from smallest to largest.
• desc: sorts in descending order. For alpha sorts, this means in reverse alphabetical order. For numeric sorts, this means from largest to smallest.

Naturally, these are ignored if sortmode is set to nosort or isn't set at all.

duplicates

One of the following keywords:

• keep: keeps duplicate values in the list.
• prestrip: removes duplicate values before the values are changed. This is useful if you want to keep any duplicate values than occur after the items are changed. Alternatively, if the changes are such that the values will still be unique after changing, prestripping is more efficient.
• strip or poststrip: removes duplicate values after the values are changed. If you don't want any duplicates in the output and your changes might cause some different input values to become the same, you'll need to poststrip.
• pre/poststrip: removes duplicate values both before and after the values are changed. In some cases, this may avoid redundant changes in the processing stage and may be more efficient overall, especially if the changes are nontrivial. In most cases, this will have the same result at poststrip, but will do it faster in some cases and slower in others.

When in doubt, it's probably best to just choose strip if you want unique values at the end.

counttoken

(Added in 1.0.) This defines a optional token that will be replaced with the numeric count of items returned where it is found in intro and outro below. It is not used if neither of those parameters are specified. It can be left blank or omitted.

intro and outro

intro takes content to output before any items in the list. outro takes content to output after any items in the list. Using these is different from just placing content before and after the #listmerge call, however, because the intro and outro are suppressed for empty lists, whether it is empty before or after the merge. This is useful for avoiding embedding #listmerge calls awkwardly in #if calls in many situations.

default

default takes content to output should the given list be empty or if the merging process results in an empty list. This is useful for avoiding embedding #listmerge calls awkwardly in #if calls in many situations, or for doing the same in the list parameter itself.