Extension:NaturalLanguageList
 Release status: stable |
|
|---|---|
| Implementation | Parser function |
| Description | For easy of creation natural language list and other list related functions |
| Author(s) | Svip (Svippongtalk) |
| Latest version | 2.6 (2014-04-01) |
| MediaWiki | 1.23+ |
| Database changes | No |
| License | WTFPL 2.0 |
| Download | |
|
$wgNllMaxListLength |
|
| Quarterly downloads | 0 |
| Translate the NaturalLanguageList extension if it is available at translatewiki.net | |
The Natural Language List extension allows for creation of simple lists in natural languages (e.g. 1, 2, 3, ... n-1 and n) at its core, but also several other sophisticated and useful list related functions.
Rationale
Ironically, many people whom I have shown this extension or indeed its concept have trouble grasping its purpose. In most cases, people say they cannot find an application for the need of automatic natural language lists. But for anyone who has a decent sized wiki, they will eventually come around a scenario, where a system that adds an 'and' between the last two elements would indeed be handy, but are forced to write excessively long wikicode to compensate for it.
- Examples
Here are some templates around several wikis that could greatly benefit from this extension:
Usage
Currently, the extension introduces three new parser functions; {{#list:}}, {{#rawlist:}} and {{#rangelist:}}. For most purposes, the former is the function you'll most be using, so let's look at that first.
{{#list:}}
This function takes an arbitrary number of arguments. Indeed, no arguments are technically required, and in such a case, it just returns nothing. Each argument that is not understood as an option will be assumed to be a field in the list.
{{#rawlist:}}
This function is slightly different, this is designed to take a raw input of strings (perhaps returned by another template, parser functions or indeed something else). Since MediaWiki usually uses pipes (|) to separate data, MediaWiki understands that it cannot return that to templates/parser functions and much less parse it correctly. This parser function allows you to make up for just that. The first argument in this system is always the separation key, specifically what the data is separated by, everything that isn't understood as an option is assumed to be input data to parse.
{{#rawlist:,|1,2,3,4,5}}
Which would become 1, 2, 3, 4 and 5.
{{#rangelist:}}
Input is a range of items. The first argument is the start, second is the end and the third is optional step. All others will be ignored, but option parameters are allowed anywhere, just as long as the three parameters follow this order. But is good to stick with the basics.
{{#rangelist:0|10|2}}
Would produce 0, 2, 4, 6, 8 and 10.
Negative lists can be produced as well.
Options
Each parameter containing data in the format of 'variable=value' will be considered an option, so for several options, separate them by a pipe. In addition, it is regardless of the position in the list of items where the options come. First, last or in the middle, the construct of 'variable=value' will be assumed to be an option, if it matches one of the following understood variables:
- duplicates (boolean)
- (Default: true) Whether the list should include duplicates, if true duplicates will be included, per default they won't.
- blanks (boolean)
- (Default: false) Whether the list should include blank elements, if true blank elements will be included, per default they won't.
- length (integer)
- (Default: no length) The maximum amount of elements in the list. It cannot be larger than $wgNllMaxListLength.
- comma (string)
- separator (string)
- outputseparator (string)
- (Default: empty) The output's separation character(s), if not set, it will default to the 1, 2, 3, ... n-1 and n format. If set, however, the ' and ' feature will not be available, and all elements will be separated the same way. So if you set it to a comma, it will simply be the same but the two last elements separated by a comma rather than an ' and '.
- and (string)
- lastseparator (string)
- (Default: empty) Allows to set a specific separator for the last two elements, if not set, it will default to the language's setting for ' and '.
- format (string)
- itemoutput (string)
- itemcover (string)
- (Default: empty) Allows to create string surrounding each item. Must contain $1 to refer to the item. When used with fieldsperitem, $2, $3, etc. may also appear.
- fieldsperitem (integer)
- itemsperitem (integer)
- (Default: 1) Allows to create more inputs per a single field in the end result, combining several fields into one. The amount it is set to is the size of the pairs of fields. It requires format to be set. Though, it is not required for format to contain more than $1. Note though, if format is set and this isn't, the system will parse through format to see if there are several $n in it, and set the fieldsperitem accordingly; remember though, you can always overwrite this by setting this parameter.
- ignore (element or elements)
- (Default: empty) This parameter includes data/element for which to be ignored, if they had been previously appearing in the list. This parameter can appear several times and add several items to the list of ignored elements, e.g.
{{#list:|1|2|3|4|5|ignore=2|ignore=4}}
- Would yield 1, 3 and 5.
- Note: When using with {{#rawlist:}}, the data to
|ignore=can be separated in the same usual data would. - data (element or elements)
- This parameter is simply a way to escape items that would otherwise be passed off as parameters by the parser, e.g.
|data=data=5would return 'data=5', even thoughdata=5would usually just return 5.
Installation
- Download and move the extracted
NaturalLanguageListfolder to yourextensions/directory.
Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/NaturalLanguageList - Add the following code at the bottom of your LocalSettings.php file:
wfLoadExtension( 'NaturalLanguageList' );
- Configure as required.
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Configuration
$wgNllMaxListLength- Integer defaulting to 1000
This sets the hard cap on the possible length of a list to avoid abuse of server performance. All elements beyond its limit will simply be cut.