Extension:NaturalLanguageList

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
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.5 (18 April 2011)
MediaWiki 1.15.0+
Database changes No
License DWTFYWWI
Download
Parameters

$wgNllMaxListLength

Hooks used
ParserFirstCallInit

Translate the NaturalLanguageList extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

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.

Overview[edit | edit source]

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:}}[edit | edit source]

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:}}[edit | edit source]

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:}}[edit | edit source]

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.

Why?[edit | edit source]

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[edit | edit source]

Here are some templates around several wikis that could greatly benefit from this extension:

Installation[edit | edit source]

  1. Get it through the distributor or get the Code from the repository.
  2. Throw it into your wiki/extensions/NaturalLanguageList directory.
  3. Add this to your LocalSettings.php:
    require_once( "$IP/extensions/NaturalLanguageList/NaturalLanguageList.php" );
    
  4. Add any global variables if needed.

Code[edit | edit source]

Live![edit | edit source]

Since this extension is not implemented anywhere else than my place, you can currently see it in action here:

Documentation[edit | edit source]

Options[edit | edit source]

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=5 would return 'data=5', even though data=5 would usually just return 5.

Global variables[edit | edit source]

$wgNllMaxListLength[edit | edit source]

Type
Integer
Default
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.