Extension:ArrayFunctions



Documentation for past releases: [ 1.0] · [ 1.1] · [ 1.2] · [ 1.3] · [ 1.4] · [ 1.5] · [ 1.6]

The ArrayFunctions extension creates an additional set of pure, Parsoid-compatible (see here) parser functions that perform operations on arrays. These parser functions are pure, meaning they do not modify any previously defined arrays and only return a result based on their input arguments.

How can I define an array to be used throughout a page?
It is not possible to directly define an array to be used throughout a page, because this would require sequential processing of extension tags, which is not supported by Parsoid (see Parsoid/Extension API). Instead, you can pass arrays around as template parameters:

This way, the array is available in  as.

How to iterate over an array?
It is possible to iteratively access elements of an array using :

The expected output from the snipped above is:


 * red is my favourite.
 * green is my favourite.
 * blue is my favourite.

How to use foreach with a delimiter?
Using with a delimiter is not supported. Instead, you can use the function in conjunction with the  function:

Why are values not recognized as arrays?
This may happen because your arrays are too large. MediaWiki internally keeps a counter on the total size of template arguments, which can be increased by increasing $wgMaxArticleSize.

How is this different from extensions such as Arrays or Variables?
The main difference between ArrayFunctions and those extensions is that ArrayFunctions parser functions are pure. This means that, instead of modifying or declaring a variable, the parser function simply outputs its result. For example, when calling, the given array is not modified; instead, a copy is created, modified and then outputted. No parser function in ArrayFunctions modifies global state: all computation happens solely with the invocation of the parser function. This makes working with ArrayFunctions very different from working with other extensions such as Arrays or Variables. Instead of imperatively modifying an array stored in a variable, function composition should be used to perform complex operations. For example:


 * Arrays


 * ArrayFunctions

Functions
This section uses Python's notation for variadic parameters. A parameter prefixed with a single asterisk (*) denotes that a variable number of positional arguments can be passed, and a parameter prefixed with a double asterisk (**) denotes that a variable number of named arguments can be passed.

All keyword argument names are case-sensitive.

The extension defines the following parser functions, Lua functions and magic words:


 * Construct an array or value


 * Extract information from an array


 * Create an array from an existing array


 * Iterate over an array


 * Miscellaneous functions

af_bool
This parser function casts a string to a boolean. This is useful for creating an array containing a boolean.

Parameters

 * value : string or boolean
 * The value to cast to a boolean.

Return values
Returns the casted boolean.

af_count
This parser functions counts the number of values in an array.

Parameters

 * array : array
 * The array to count.


 * recursive : boolean, default=false
 * Whether to count items recursively. Note that elements containing a list are also counted (see examples below).

Return values
The number of items in the array.

af_difference


This parser function computes the difference between arrays. This function preserves keys.

Parameters

 * array : array
 * The first array.


 * * arrays : array
 * The other arrays.

Return values
Returns an array containing all values from  that are not present in any of the arrays in. The keys in  are preserved.

af_exists
This parser function checks whether the given key or index exists in the given array.

Parameters

 * array : array
 * The array to check.


 * key : string or int
 * The key to check.

Return values
Returns true if  contains , false otherwise.

af_float
This parser function casts a string to a float. This is useful for creating an array containing a float.

Parameters

 * value : string or float
 * The value to cast to a float.

Return values
Returns the casted float.

af_foreach
This parser function provides a way to iterate over arrays.

Parameters

 * array : array
 * The array over which to iterate.


 * key_name : string, default=null
 * The name to use for the key.


 * value_name : string, default=null
 * The name to use for the value.


 * body : string
 * The body to return for each iteration.

Return values
Returns the resulting wikitext.

af_get
This parser function retrieves the element with the given index from the given array. If the index does not exist, the empty string is returned.

Parameters

 * array : array
 * The array in which to index.


 * * indices : string
 * The index. Multiple indices can be given to index nested arrays.

Return values
Returns the indexed value, or the empty string if the index does not exist.

af_if
This parser function selects one of two alternatives based on the given predicate.

Parameters

 * predicate : boolean
 * The predicate.


 * consequent : string
 * The value to return if the predicate holds (i.e. is true).


 * alternative : string, default=""
 * The value to return if the predicate does not hold (i.e. is false).

Return values
Returns the consequent if the predicate holds, or the alternative if it is given and the predicate does not hold.

af_int
This parser function casts a string to an integer. This is useful for creating an array containing an integer.

Parameters

 * value : string or int
 * The value to cast to an integer.

Return values
Returns the casted integer.

af_intersect


This parser function computes the intersection of arrays. This function preserves keys.

Parameters

 * array : array
 * The first array.


 * * arrays : array
 * The other arrays.

Return values
Returns the intersection of the given arrays.

af_isarray
This parser function checks if the given value is an array.

Parameters

 * value : mixed
 * The value to check.

Return values
Returns true if  is an array, false otherwise.

af_join
This parser function recursively joins the items of an array together with a given separator.

Parameters

 * array : array
 * The array to join.


 * glue : string, default=""
 * The string used to join each item. This parameter recognises the following escape sequences:
 * for spaces
 * for newlines
 * for backslashes

Return values
Returns the joined array.

af_keysort
This parser function sorts a list of objects based on the values of the specified key. To sort an array by key, use.

Parameters

 * array : array
 * The array to sort.


 * key : string
 * The key of the values on which the sort should be based.


 * descending : boolean, default=false
 * Whether to sort in a descending order.


 * caseinsensitive : boolean, default=false
 * Whether to ignore case when sorting.

Return values
Returns the sorted array.

af_ksort
This parser function sorts an array by key.

Parameters

 * array : array
 * The array to sort.


 * descending : boolean, default=false
 * Whether to sort in a descending order.


 * caseinsensitive : boolean, default=false
 * Whether to ignore case when sorting.

Return values
Returns the sorted array.

af_list
This parser function creates a new list from the given parameters.

Parameters

 * * values : mixed
 * The values for the list.

Return values
Returns the resulting list.

af_map
This parser function applies a callback to each element of a list.

Parameters

 * array : array
 * The array to run through the callback.


 * value_name : string
 * The name to give to the value in the callback.


 * callback : string
 * The callback to apply to each element of the array.

Return values
Returns the resulting mapped array.

af_merge


This parser function computes the union of arrays. It merges the elements of one or more arrays together so that the values of one are appended to the end of the previous one.

If the input arrays have the same string key, then the later value for that key will overwrite the previous one. If the arrays contain numeric keys, later values will be appended instead and the later keys will be renumbered.

Parameters

 * array : array
 * The first array.


 * * arrays : array
 * The other arrays.

Return values
Returns the union of the given arrays.

af_object
This parser function creates a new object from the given parameters.

Parameters

 * ** values : mixed
 * The values for the object.

Return values
Returns the resulting object.

af_print
This parser function prints the given value for debug purposes. Unlike, it does not parse the value, but does support printing lists and objects. This function should only be used for debug purposes. Consider using to display a value to the reader.

Parameters

 * * values : mixed
 * The values to print.


 * end : string, default=""
 * The string to append to the end of each printed value. This parameter recognises the following escape sequences:
 * for spaces
 * for newlines
 * for backslashes

Return values
Returns the value in human-readable form.

af_push
This parser function adds the given value to the end of the list.

Parameters

 * array : array
 * The array to append the value to.


 * value : mixed
 * The value to add.

Return values
Returns the array with the value appended.

af_reduce
This parser function iteratively reduces the array to a single value using a callback. It iteratively applies  to the elements of the given array, so as to reduce the array to a single value. The callable is passed the value of the current iteration, as well as the result of the previous iteration.

Parameters

 * array : array
 * The array to reduce.


 * carry_name : string
 * The name to use for the carry.


 * value_name : string
 * The name to use for the value.


 * callable : string
 * The callback to use for each iteration.


 * initial : string, default=""
 * The initial carry to use.

Return values
Returns the resulting value.

af_search
This parser function searches the given array for the given value, and returns the first corresponding key if the value is found.

Parameters

 * array : array
 * The array to search in.


 * value : mixed
 * The value to search for.

Return values
Returns the first corresponding key if the value is found, nothing otherwise.

af_set
This parser function sets the given value for the given index.

Parameters

 * value : mixed
 * The value to set the index to.


 * array : array
 * To array in which to set the index.


 * * indices : string
 * The index to set. Multiple indices can be given to index nested arrays.

Return values
Returns the array with the given index set to the given value.

af_show
This parser function prints the given value in a human-readable format. Unlike, this parser function parses the value. It does not support showing lists or objects.

Parameters

 * value : mixed
 * The value to show.

Return values
Returns the value in human-readable form.

af_slice
This parser function extracts a slice from the given array. Keys will be reset and reordered.

Parameters

 * array : array
 * The array to take a slice from.


 * offset : integer
 * The offset at which the slice starts. If non-negative, the slice will start at this given offset. If negative, the sequence will start that far from the end of the array.


 * length : integer, optional
 * The length of the slice. If the length is given and positive, then the slice will have that many elements in it. If the length is given and negative, then the slice will stop that many elements from the end of the array. If it is omitted, then the slice will have everything from offset up until the end of the array.

Return values
The slice.

af_sort
This parser function sorts the given list.

Parameters

 * array : array
 * The array to sort.


 * descending : boolean, default=false
 * Whether to sort the list in descending order.


 * caseinsensitive : boolean, default=false
 * Whether to ignore case when sorting.

Return values
Returns the sorted list.

af_split
This parser function splits the given string based on a delimiter.

Parameters

 * string : string
 * The string to split.


 * delimiter : string, default=","
 * The delimiter to use. This parameter recognises the following escape sequences:
 * for spaces
 * for newlines
 * for backslashes

Return values
Returns the resulting list.

af_stringmap
This parser function applies a callback to each item of a delimited string, and returns the result as a delimited string, optionally with a different delimiter. This function is similar to Page Forms' #arraymap parser function.

Parameters

 * value : string
 * The delimited string.


 * delimiter : string
 * The delimiter to split  on. If the empty string is given, "," is used. This parameter recognises the following escape sequences:
 * for spaces
 * for newlines
 * for backslashes


 * value_name : string
 * The name to give to the value in the callback.


 * callback : string
 * The callback to apply to each element of the array.


 * new_delimiter : string, default=", "
 * The new delimiter to insert in between the mapped items. This parameter recognises the following escape sequences:
 * for spaces
 * for newlines
 * for backslashes


 * conjunction : string, default=null
 * The delimiter to place between the last two items. This allows you to create a more natural summation, such as "Alice, Bob and Eve". If no value is given, the value of  is used. This parameter recognises the following escape sequences:
 * for spaces
 * for newlines
 * for backslashes

Return values
Returns the resulting delimited string.

af_template
This parser function will invoke the given template and pass the values in the given array as arguments.

Parameters

 * name : string
 * The name of the template to invoke. If no namespace is given, it is assumed the page is in the template namespace, otherwise the given namespace is used. The page must exist, must be includable and must be readable by the user, otherwise an error is given.


 * data : array
 * The data to pass to the parameters. Values with numeric indices are passed as positional arguments and values with string indices are passed as named arguments.

Return values
The expanded template.

af_unique
This parser function removes duplicate values from the given array. This function does not reset keys.

Parameters

 * array : array
 * The array from which to remove duplicates.

Return values
Returns the array with duplicates removed.

af_unset
This parser function removes the value associated with the given index from the array and returns the result. Numeric keys are not reset after calling this function.

Parameters

 * array : array
 * The array from which to remove the given key.


 * * indices : string
 * The index to remove. Multiple indices can be given to index nested arrays.

Return values
Returns the array with the given index removed.

Scribunto
This extension is particularly useful in combination with Lua, as it can be used to create the array containing data required for the presentation of the page. This array can be exported to work with ArrayFunctions:

This module may then be invoked like so:

mw.af.export
This Lua function exports a Lua table as an ArrayFunctions array.

Description
mw.af.export( table )

Parameters

 * table : array
 * The array to export.

Return values
Returns the table as an ArrayFunctions array.

mw.af.import
This Lua function imports an ArrayFunctions array as a Lua table.

Description
mw.af.import( array )

Parameters

 * array : array
 * The array to import.

Return values
Returns the array as a Lua table.

Magic words
The extension defines a number of magic words (variables).

AF_EMPTY
This magic word returns the empty array. This is useful, because it is not possible to create an empty array with  or.

Return values
Returns the empty array.