(→#lstsub: Fixed another improperly closed code tag) |
Rye Greenwood (talk | contribs) m (→#listunique: Fixed typos.) |
||
(One intermediate revision by one other user not shown) | |||
Line 65: | Line 65: | ||
==<code>#lstsub</code>== |
==<code>#lstsub</code>== |
||
<nowiki>{{#lstsub:list|input separator|output separator|start index|length}}</nowiki> |
<nowiki>{{#lstsub:list|input separator|output separator|start index|length}}</nowiki> |
||
− | This function returns the part of the list 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. |
+ | This function returns the part of the list, where items are delimited by <code>input separator</code>, 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. <code>1</code> refers to the top nonempty item in the list, <code>2</code> to the second, and so on. <code>-1</code> refers to the bottom nonempty item in the list, <code>-2</code> to the second nonempty item from the bottom, and so on. <code>1</code> is assumed if no value is given. |
The start index can be specified as a positive or negative number. <code>1</code> refers to the top nonempty item in the list, <code>2</code> to the second, and so on. <code>-1</code> refers to the bottom nonempty item in the list, <code>-2</code> to the second nonempty item from the bottom, and so on. <code>1</code> is assumed if no value is given. |
||
Line 71: | Line 71: | ||
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. <code>-1</code> will omit the last nonempty in the list, <code>-2</code> 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 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. <code>-1</code> will omit the last nonempty in the list, <code>-2</code> 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. |
+ | The partial list will be returned with the items delimited by the given <code>output separator</code>. |
Each parameter recognizes [[ParserPower escape sequences]], though as noted above, escape sequences are processed in the list after it is split into individual items. |
Each parameter recognizes [[ParserPower escape sequences]], though as noted above, escape sequences are processed in the list after it is split into individual items. |
||
Line 243: | Line 243: | ||
;<code>token</code> and <code>pattern</code> |
;<code>token</code> and <code>pattern</code> |
||
− | :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 <code>token</code> is found in <code>pattern</code>, it is replaced by the value to generate the key. So if you provide a <code>token</code> of <code>@@@@</code> and a <code>pattern</code> of <code><nowiki>{\{NAMESPACENUMBER:@@@@}\}</nowiki></code>, then with values <code>Main Page</code>, <code>Talk:ParserPower</code> and <code>ParserPower</code>, you'd get keys of <code>0</code>, <code>1</code>, and <code>0</code>, so only <code>Main Page</code> and <code>Talk:ParserPower</code> would be returned in the new list. As another example, a pattern of <code>{\{#sub:@@@@ |
+ | :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 <code>token</code> is found in <code>pattern</code>, it is replaced by the value to generate the key. So if you provide a <code>token</code> of <code>@@@@</code> and a <code>pattern</code> of <code><nowiki>{\{NAMESPACENUMBER:@@@@}\}</nowiki></code>, then with values <code>Main Page</code>, <code>Talk:ParserPower</code> and <code>ParserPower</code>, you'd get keys of <code>0</code>, <code>1</code>, and <code>0</code>, so only <code>Main Page</code> and <code>Talk:ParserPower</code> would be returned in the new list. As another example, a pattern of <code>{\{#sub:@@@@\!0\!1}\}</code> with a token of <code>@@@@</code> 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. |
;<code>tokensep</code> and <code>fieldsep</code> |
;<code>tokensep</code> and <code>fieldsep</code> |
Latest revision as of 21:03, 6 March 2020
|
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 usekeep
, the parametersremove
,pattern
andtemplate
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 forkeep
, so that ifitem
is inkeep
,ITEM
would be removed from the list. By default, this isno
.
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 useremove
, the parameterspattern
andtemplate
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 forvalues
, so that ifitem
is invalues
,ITEM
would not be removed from the list. By default, this isno
.
token
andpattern
- These parameters allow you to specify some wikicode to run on each item in the list that returns either
keep
orremove
. For each item in the list, the token inpattern
is replaced with the value and the wikicode is processed. Any time thatremove
is returned, the list item will be removed from the list. This is case insensitive, soREMOVE
will also remove the item. So for atoken
of@@@@
and a pattern of{{#ifeq:@@@@|Main page|remove|keep}}
, a list value ofMain page
returnsremove
and will not be in the returned list, butProject:Community portal
returnskeep
and will remain part of the list.
tokensep
andfieldsep
- These, combined with
token
andpattern
, 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 alist
ofJohn Doe,Jane Smith
. Withfieldsep
of\_
,token
of$1,$2
and apattern
of{{#ifeq:$2|Smith|remove|keep}}
,John Doe
will returnkeep
and be returned in the list, butJane Smith
will returnremove
and be removed from the list.
indextoken
- (Added in 1.0.) When combined with
token
andpattern
, 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
andfieldsep
- 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 parameter1
. The exception is if you specifyfieldsep
. In this case, the value is separated into fields and the first field is passed through to parameter1
, the second to parameter2
, and so on. Note that if you specifytemplate
,token
,tokensep
, andpattern
are ignored. As with usingtoken
andpattern
, the item will be removed only if the template returnsremove
for the item in question. Note that iftemplate
is specified,token
,tokensep
, andpattern
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
andoutro
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 theintro
andoutro
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 thelist
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 isno
. Note this is only relevant when notemplate
or notoken
andpattern
are used, because in those cases, the generated keys are compared, and that is always done in a case-sensitive manner.
token
andpattern
- 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 inpattern
, it is replaced by the value to generate the key. So if you provide atoken
of@@@@
and apattern
of{\{NAMESPACENUMBER:@@@@}\}
, then with valuesMain Page
,Talk:ParserPower
andParserPower
, you'd get keys of0
,1
, and0
, so onlyMain Page
andTalk: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
andfieldsep
- These, combined with
token
andpattern
, 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 alist
ofJohn Doe,Jane Smith,Bob Smith
. Withfieldsep
of\_
,token
of$1,$2
and apattern
of$2
, the keys becomeDoe
,Smith
andSmith
. AsJane Smith
was the first to generate theSmith
key, her name will be returned in the output list, butBob Smith
will not because theSmith
key was already generated.tokensep
only needs to be specified if you use something other than a comma to separate the tokens intoken
. (Note: this example only works when everyone has only two names.)
indextoken
- (Added in 1.0.) When combined with
token
andpattern
, 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
andfieldsep
- 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 parameter1
. The exception is if you specifyfieldsep
. In this case, the value is separated into fields and the first field is passed through to parameter1
, the second to parameter2
, and so on. Note that if you specifytemplate
,token
,tokensep
, andpattern
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
andoutro
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 theintro
andoutro
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 thelist
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 toalpha
sorts. This is ignored innumeric
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 toalpha
sorts. This is ignored innumeric
sorts.asc
: sorts in ascending order. Foralpha
sorts, this means in alphabetical order. Fornumeric
sorts, this means from smallest to largest.desc
: sorts in descending order. Foralpha
sorts, this means in reverse alphabetical order. Fornumeric
sorts, this means from largest to smallest.
- Note that if
token
andpattern
ortemplate
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 orstrip
to remove duplicates.keep
is the default option.
token
andpattern
- These are used to generate a sort key to sort the values by instead of just sorting the values themselves. When
token
is found inpattern
, it is replaced by the value to generate the sort key. So if you provide atoken
of@@@@
and apattern
of{\{NAMESPACENUMBER:@@@@}\}
, then with valuesTalk:ParserPower
,Main Page
, andProject:Community Portal
, you'd get sort keys of1
,0
, and4
, which would be useful for sorting page names by their namespace.
indextoken
- (Added in 1.0.) When combined with
token
andpattern
, 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
andfieldsep
- These, combined with
token
andpattern
, 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 alist
ofJohn Doe,Jane Smith
. Withfieldsep
of\_
,token
of$1,$2
and apattern
of$2 $1
, the sort keys becomeDoe John
andSmith 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 intoken
. (Note: this example only works when everyone has only two names.)
template
andfieldsep
- 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 parameter1
. The exception is if you specifyfieldsep
. In this case, the value is separated into fields and the first field is passed through to parameter1
, the second to parameter2
, and so on. Note that if you specifytemplate
,token
,tokensep
, andpattern
are ignored.
subsort
andsubsortoptions
subsort
accepts eitheryes
orno
. Ifyes
, this indicates that any values with the same sort key should be sorted according to the options insubsortoptions
(or the defaults if none are provided). The availablesubsortoptions
are the same as forsortoptions
.
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
andoutro
- (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 theintro
andoutro
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 thelist
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
andpattern
- The most basic way to change each value in the list is provide a
token
and apattern
that contains that token. For each item in the list, the token inpattern
is replaced with the value and the result is returned. So for atoken
of@@@@
and a pattern of[[@@@@]]
, list values ofMain page
andProject:Community portal
become[[Main page]]
and[[Project:Community portal]]
.
tokensep
andfieldsep
- These, combined with
token
andpattern
, 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 alist
ofJohn Doe,Jane Smith
. Withfieldsep
of\_
,token
of$1,$2
and apattern
of$2, $1
, the values becomeDoe, John
andSmith, Jane
.tokensep
only needs to be specified if you use something other than a comma to separate the tokens intoken
. (Note: this example only works when everyone has only two names.)
indextoken
- (Added in 1.0.) When combined with
token
andpattern
, 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
andfieldsep
- 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 parameter1
. The exception is if you specifyfieldsep
. In this case, the value is separated into fields and the first field is passed through to parameter1
, the second to parameter2
, and so on. Note that if you specifytemplate
,token
,tokensep
, andpattern
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
orpostsort
: 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, andpre/postsort
was not recognized. As it is rare for sorting before and after to be desirable, it was decided thatsort
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 toalpha
sorts. This is ignored innumeric
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 toalpha
sorts. This is ignored innumeric
sorts.asc
: sorts in ascending order. Foralpha
sorts, this means in alphabetical order. Fornumeric
sorts, this means from smallest to largest.desc
: sorts in descending order. Foralpha
sorts, this means in reverse alphabetical order. Fornumeric
sorts, this means from largest to smallest.
- Naturally, these are ignored if
sortmode
is set tonosort
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
orpoststrip
: 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 atpoststrip
, 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, andpre/poststrip
was not recognized. As it is rare for removal before and after to be desirable, it was decided thatstrip
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
andoutro
- (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 theintro
andoutro
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 thelist
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
andmergepattern
- 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
andtoken2
, which must be different for this function to work correctly. These sequences are then included in wikicode inmatchpattern
andmergepattern
. As each pair of values is processed, thetoken1
andtoken2
sequences inmatchpattern
are replaced by the first and second values in the pair, respectively. The wikicode is then processed, and if it resolves toyes
, the pair of items will then be merged. This is done by usingmergepattern
, which functions largely the same way: the token sequences are replaced and the wikicode is processed to get the new value.
tokensep
andfieldsep
- These, combined with
token1
,token2
,matchpattern
andmergepattern
, increase the flexibility of using patterns to find matches and merge like items. The character sequence specified infieldsep
is used to separate each value in the pair into fields, andtokensep
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 intoken1
cannot be reused intoken2
for the function to operate correctly.
matchtemplate
,mergetemplate
, andfieldsep
- 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 returnsyes
, themergetemplate
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 iffieldsep
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 givenfieldsep
results in each value being divided into two fields, parameters1
and2
get the fields from the first value and parameters3
and4
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
orpostsort
: 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 toalpha
sorts. This is ignored innumeric
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 toalpha
sorts. This is ignored innumeric
sorts.asc
: sorts in ascending order. Foralpha
sorts, this means in alphabetical order. Fornumeric
sorts, this means from smallest to largest.desc
: sorts in descending order. Foralpha
sorts, this means in reverse alphabetical order. Fornumeric
sorts, this means from largest to smallest.
- Naturally, these are ignored if
sortmode
is set tonosort
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
orpoststrip
: 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 atpoststrip
, 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
andoutro
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 theintro
andoutro
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 thelist
parameter itself.
|