Extension:ArrayFunctions
![]() Release status: stable |
|
---|---|
Implementation | Parser function |
Description | Provides a set of pure parser functions that operate on arrays |
Author(s) | Marijn van Wezel (Wikibase Solutions) |
Latest version | 1.2.0 (2023-03-03) |
Compatibility policy | Master maintains backward compatibility. |
MediaWiki | >=1.35.6 |
PHP | >=7.4 |
Database changes | No |
Composer | wikibase-solutions/array-functions |
License | GNU General Public License 2.0 or later |
Download | |
Quarterly downloads | 7 (Ranked 166th) |
Translate the ArrayFunctions extension if it is available at translatewiki.net | |
Issues | Open tasks · Report a bug |

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.
FunctionsEdit
This extension defines the following parser functions, Lua functions and magic words:
- Construct an array or value
Name | Description |
---|---|
#af_bool
|
Cast a string to a boolean. |
#af_float
|
Cast a string to a float. |
#af_int
|
Cast a string to an integer. |
#af_list
|
Create a new list from values. |
#af_object
|
Create a new object from values. |
#af_split
|
Split a string based on a delimiter. |
AF_EMPTY
|
The empty array. |
mw.af.export
|
Create a new array from Lua. |
- Extract information from an array
Name | Description |
---|---|
#af_count
|
Count the number of values in an array. |
#af_exists
|
Check whether a key or index exists in an array. |
#af_get
|
Retrieve an element from an array by index. |
#af_isarray
|
Check if a value is an array. |
#af_print
|
Print an array in a human-readable format. |
- Create an array from an existing array
Name | Description |
---|---|
#af_intersect
|
Compute the intersection of arrays. |
#af_keysort
|
Sort a multidimensional array based on the values of a key. |
#af_merge
|
Compute the union of arrays. |
#af_push
|
Add a value to the end of a list. |
#af_set
|
Set a value at an index. |
#af_slice
|
Extract a slice from an array. |
#af_sort
|
Sort a list. |
#af_unique
|
Remove duplicates from an array. |
#af_unset
|
Remove a value from an array by index. |
- Iterate over an array
Name | Description |
---|---|
#af_foreach
|
Iterate over an array. |
#af_join
|
Recursively join the items of an array together with a separator. |
#af_map
|
Apply a callback to each element of a list. |
#af_reduce
|
Iteratively reduce the array to a single value using a callback. |
- Miscellaneous functions
Name | Description |
---|---|
#af_if
|
Select one of two alternatives based on a predicate. |
#af_template
|
Invoke a template with the values in an array. |
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.
af_boolEdit
This parser function casts a string to a boolean. This is useful for creating an array containing a boolean.
DescriptionEdit
{{#af_bool: value }}
ParametersEdit
- value : string or boolean
- The value to cast to a boolean.
Return valuesEdit
Returns the casted boolean.
ExamplesEdit
Create an opaque representation of a boolean | {{#af_bool: yes }}, {{#af_bool: no }}, {{#af_bool: true }} |
boolean__^__1, boolean__^__0, boolean__^__1 |
Create an array containing a boolean | {{#af_print: {{#af_list: {{#af_bool: yes}} }} }} |
|
af_countEdit
This parser functions counts the number of values in an array.
DescriptionEdit
{{#af_count: array | recursive=recursive }}
ParametersEdit
- 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 valuesEdit
The number of items in the array.
ExamplesEdit
Count the number of items in a one-dimensional list | {{#af_print: {{#af_count: {{#af_list: a | b | c }} }} }} |
3 |
Count the number of items in a multi-dimensional list | {{#af_print: {{#af_count: {{#af_list: {{#af_list: a | b }} | {{#af_list: c | d }} }} }} }} |
2 |
Recursively count the number of items in a multi-dimensional list | {{#af_print: {{#af_count: {{#af_list: {{#af_list: a | b }} | {{#af_list: c | d }} }} | recursive=true }} }} |
6 |
af_existsEdit
This parser function checks whether the given key or index exists in the given array.
DescriptionEdit
{{#af_exists: array | key }}
ParametersEdit
- array : array
- The array to check.
- key : string or int
- The key to check.
Return valuesEdit
Returns true if array
contains key
, false otherwise.
ExamplesEdit
Check if a key exists | {{#af_print: {{#af_exists: {{#af_object: hello=world }} | hello }} }} |
true |
Check if an index exists | {{#af_print: {{#af_exists: {{#af_list: a | b | c }} | 2 }} }} |
true |
Check if a nested key exists | {{#af_print: {{#af_exists: {{#af_get: {{#af_list: a | {{#af_list: b | c }} }} | 1 }} | 2 }} }} |
false |
af_floatEdit
This parser function casts a string to a float. This is useful for creating an array containing a float.
DescriptionEdit
{{#af_float: value }}
ParametersEdit
- value : string or float
- The value to cast to a float.
Return valuesEdit
Returns the casted float.
ExamplesEdit
Create an opaque representation of a float | {{#af_float: 1.298 }}, {{#af_float: 0 }} |
float__^__1.298, float__^__0 |
Create an array containing a float | {{#af_print: {{#af_list: {{#af_float: 1.298 }} }} }} |
|
af_foreachEdit
This parser function provides a way to iterate over arrays.
DescriptionEdit
{{#af_foreach: array | key_name | value_name | body }}
ParametersEdit
- 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 valuesEdit
Returns the resulting wikitext.
ExamplesEdit
Iterate over a list | {{#af_foreach: {{#af_list: John | Steve | Harry }} | | name | Hello, {{{name}}}!<br/> }} |
Hello, John! Hello, Steve! Hello, Harry! |
Iterate over an object | {{#af_foreach: {{#af_object: Hello=John | Hi=Steve | Welcome=Harry }} | greeting | name | {{{greeting}}}, {{{name}}}!<br/> }} |
Hello, John! Hi, Steve! Welcome, Harry! |
af_getEdit
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.
DescriptionEdit
{{#af_get: array | *indices }}
ParametersEdit
- array : array
- The array in which to index.
- *indices : string
- The index. Multiple indices can be given to index nested arrays.
Return valuesEdit
Returns the indexed value, or the empty string if the index does not exist.
ExamplesEdit
Get a top-level element | {{#af_get: {{#af_list: a | b | c }} | 1 }} |
b |
Get a subarray | {{#af_print: {{#af_get: {{#af_list: a | {{#af_list: b | c }} }} | 1 }} }} |
|
Get a nested element | {{#af_get: {{#af_list: a | {{#af_object: hello=world }} }} | 1 | hello }} |
world |
af_ifEdit
This parser function selects one of two alternatives based on the given predicate.
DescriptionEdit
{{#af_if: predicate | consequent | alternative }}
ParametersEdit
- 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 valuesEdit
Returns the consequent if the predicate holds, or the alternative if it is given and the predicate does not hold.
ExamplesEdit
Check if a value is an array | {{#af_if: {{#af_isarray: not an array }} | A beautiful array! | Not an array! }} |
Not an array! |
af_intEdit
This parser function casts a string to an integer. This is useful for creating an array containing an integer.
DescriptionEdit
{{#af_int: value }}
ParametersEdit
- value : string or int
- The value to cast to an integer.
Return valuesEdit
Returns the casted integer.
ExamplesEdit
Create an opaque representation of an integer | {{#af_int: 42 }}, {{#af_int: -12 }} |
integer__^__42, integer__^__-12 |
Create an array containing an integer | {{#af_print: {{#af_list: {{#af_int: -129}} }} }} |
|
af_intersectEdit
This parser function computes the intersection of arrays. This function preserves keys.
DescriptionEdit
{{#af_intersect: array | *arrays }}
ParametersEdit
- array : array
- The first array.
- *arrays : array
- The other arrays.
Return valuesEdit
Returns the intersection of the given arrays.
ExamplesEdit
Compute the intersection of two identical arrays | {{#af_print: {{#af_intersect: {{#af_list: a | b | c }} | {{#af_list: a | b | c }} }} }} |
|
Compute the intersection of two partially overlapping arrays | {{#af_print: {{#af_intersect: {{#af_list: a | b | c }} | {{#af_list: c | d | e }} }} }} |
|
af_isarrayEdit
This parser function checks if the given value is an array.
DescriptionEdit
{{#af_isarray: value }}
ParametersEdit
- value : mixed
- The value to check.
Return valuesEdit
Returns true if value
is an array, false otherwise.
ExamplesEdit
Check if an array is an array | {{#af_print: {{#af_isarray: {{#af_list: a | b | c }} }} }} |
true |
Check if a string is an array | {{#af_print: {{#af_isarray: Hello, World! }} }} |
false |
af_joinEdit
This parser function recursively joins the items of an array together with a given separator.
DescriptionEdit
{{#af_join: array | glue }}
ParametersEdit
- array : array
- The array to join.
- glue : string, default=""
- The string used to join each item. This parameter recognises the following escape sequences:
\s
for spaces\n
for newlines\\
for backslashes
Return valuesEdit
Returns the joined array.
ExamplesEdit
Join a one-dimensional array | {{#af_join: {{#af_list: a | b | c }} }} |
abc |
Join a one-dimensional array using a separator | {{#af_join: {{#af_list: a | b | c }} | \s-\s }} |
a - b - c |
Join a multi-dimensional array using a separator | {{#af_join: {{#af_list: a | b | {{#af_list: c | d }} }} | \s-\s }} |
a - b - c - d |
af_keysortEdit
This parser function sorts a multidimensional array based on the values of a key.
DescriptionEdit
{{#af_keysort: array | key | descending=descending }}
ParametersEdit
- 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.
Return valuesEdit
Returns the sorted array.
ExamplesEdit
Sort based on age | {{#af_print: {{#af_keysort: {{#af_list: {{#af_object: name=John | age=56 }} | {{#af_object: name=Harry | age=12 }} | {{#af_object: name=Bob | age=24 }} }} | age }} }} |
|
Sort based on age, in descending order | {{#af_print: {{#af_keysort: {{#af_list: {{#af_object: name=John | age=56 }} | {{#af_object: name=Harry | age=12 }} | {{#af_object: name=Bob | age=24 }} }} | age | descending=true }} }} |
|
af_listEdit
This parser function creates a new list from the given parameters.
DescriptionEdit
{{#af_list: *values }}
ParametersEdit
- *values : mixed
- The values for the list.
Return valuesEdit
Returns the resulting list.
ExamplesEdit
Create a simple one-dimensional list | {{#af_print: {{#af_list: a | b | c }} }} |
|
Create a multi-dimensional list | {{#af_print: {{#af_list: {{#af_list: a | b }} | {{#af_list: c | d }} }} }} |
|
Create a list of objects | {{#af_print: {{#af_list: {{#af_object: name=Harry | age=22 }} | {{#af_object: name=Bobby | age=29 }} }} }} |
|
af_mapEdit
This parser function applies a callback to each element of a list.
DescriptionEdit
{{#af_map: array | value_name | callback }}
ParametersEdit
- 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 valuesEdit
Returns the resulting mapped array.
ExamplesEdit
Appending a string to each element | {{#af_print: {{#af_map: {{#af_list: a | b | c }} | v | {{{v}}}-appended }} }} |
|
Altering list elements | {{#af_print: {{#af_map: {{#af_list: {{#af_list: a }} | {{#af_list: b }} }} | v | {{#af_push: {{{v}}} | c }} }} }} |
|
af_mergeEdit
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.
DescriptionEdit
{{#af_merge: array | *arrays }}
ParametersEdit
- array : array
- The first array.
- *arrays : array
- The other arrays.
Return valuesEdit
Returns the union of the given arrays.
ExamplesEdit
Appending a string to each element | {{#af_print: {{#af_merge: {{#af_list: a | b | c }} | {{#af_list: d | e | f }} }} }} |
|
af_objectEdit
This parser function creates a new object from the given parameters.
DescriptionEdit
{{#af_object: **values }}
ParametersEdit
- **values : mixed
- The values for the object.
Return valuesEdit
Returns the resulting object.
ExamplesEdit
Create a simple one-dimensional object | {{#af_print: {{#af_object: a=b | b=c | c=d }} }} |
|
Create a multi-dimensional object | {{#af_print: {{#af_object: head={{#af_object: title=MediaWiki | meta={{#af_list: {{#af_object: charset=UTF-8 }} }} }} }} }} |
|
af_printEdit
This parser function prints the given value in a human-readable format.
DescriptionEdit
{{#af_print: *values | end=end }}
ParametersEdit
- *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:
\s
for spaces\n
for newlines\\
for backslashes
Return valuesEdit
Returns the value in human-readable form.
ExamplesEdit
Print a boolean | {{#af_print: {{#af_bool: yes }} }} |
true |
Print a list | {{#af_print: {{#af_list: a | b | c }} }} |
|
af_pushEdit
This parser function adds the given value to the end of the list.
DescriptionEdit
{{#af_push: array | value }}
ParametersEdit
- array : array
- The array to append the value to.
- value : mixed
- The value to add.
Return valuesEdit
Returns the array with the value appended.
ExamplesEdit
Push a value | {{#af_print: {{#af_push: {{#af_list: a | b }} | c }} }} |
|
af_reduceEdit
This parser function iteratively reduces the array to a single value using a callback. It iteratively applies callable
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.
DescriptionEdit
{{#af_reduce: array | carry_name | value_name | callable | initial }}
ParametersEdit
- 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 valuesEdit
Returns the resulting value.
ExamplesEdit
Using reduction to concatenate values | {{#af_reduce: {{#af_list: a | b | c }} | c | i | {{{c}}}{{{i}}} }} |
abc |
Using reduction to reverse and then concatenate values | {{#af_reduce: {{#af_list: a | b | c }} | c | i | {{{i}}}{{{c}}} }} |
cba |
Using reduction to build an equation | {{#af_reduce: {{#af_list: 2 | 3 | 5 | 7 | 11 }} | c | i | {{{c}}} + {{{i}}} | 0 }} |
0 + 2 + 3 + 5 + 7 + 11 |
af_setEdit
This parser function sets the given value for the given index.
DescriptionEdit
{{#af_set: value | array | *indices }}
ParametersEdit
- 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 valuesEdit
Returns the array with the given index set to the given value.
ExamplesEdit
Replace an existing value | {{#af_print: {{#af_set: d | {{#af_list: a | b | c }} | 2 }} }} |
|
Create a new index | {{#af_print: {{#af_set: far | {{#af_object: foo=bar }} | boo }} }} |
|
Create a new subarray | {{#af_print: {{#af_set: far | {{#af_object: foo=bar }} | boo | far }} }} |
|
af_sliceEdit
This parser function extracts a slice from the given array. Keys will be reset and reordered.
DescriptionEdit
{{#af_slice: array | offset | length }}
ParametersEdit
- 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 valuesEdit
The slice.
ExamplesEdit
Get the first two elements | {{#af_print: {{#af_slice: {{#af_list: a | b | c }} | 0 | 2 }} }} |
|
Get the last element | {{#af_print: {{#af_slice: {{#af_list: a | b | c }} | -1 }} }} |
|
af_sortEdit
This parser function sorts the given list.
DescriptionEdit
{{#af_sort: array | descending=descending }}
ParametersEdit
- array : array
- The array to sort.
- descending : boolean, default=false
- Whether to sort the list in descending order.
Return valuesEdit
Returns the sorted list.
ExamplesEdit
Sort a list in ascending order | {{#af_print: {{#af_sort: {{#af_list: b | c | a }} }} }} |
|
Sort a list in descending order | {{#af_print: {{#af_sort: {{#af_list: b | c | a }} | descending=true }} }} |
|
af_splitEdit
This parser function splits the given string based on a delimiter.
DescriptionEdit
{{#af_split: string | delimiter }}
ParametersEdit
- string : string
- The string to split.
- delimiter : string, default=","
- The delimiter to use. This parameter recognises the following escape sequences:
\s
for spaces\n
for newlines\\
for backslashes
Return valuesEdit
Returns the resulting list.
ExamplesEdit
Split a string based on commas | {{#af_print: {{#af_split: a, b, c }} }} |
|
Split a sentence into words | {{#af_print: {{#af_split: Lorem ipsum dolor et | \s }} }} |
|
af_templateEdit
This parser function will invoke the given template and pass the values in the given array as arguments.
DescriptionEdit
{{#af_template: name | data }}
ParametersEdit
- 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 valuesEdit
The expanded template.
ExamplesEdit
Invoking a template with a list | {{#af_template: Echo | {{#af_list: a | b }} }} |
{{Echo|a|b}} |
Invoking a template with an object | {{#af_template: Echo | {{#af_object: foo=bar | boo=far }} }} |
{{Echo|foo=bar|boo=far}} |
af_uniqueEdit
This parser function removes duplicate values from the given array. This function does not reset keys.
DescriptionEdit
{{#af_unique: array }}
ParametersEdit
- array : array
- The array from which to remove duplicates.
Return valuesEdit
Returns the array with duplicates removed.
ExamplesEdit
Remove duplicates from an array | {{#af_print: {{#af_unique: {{#af_list: a | a | b | c | b }} }} }} |
|
af_unsetEdit
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.
DescriptionEdit
{{#af_unset: array | *indices }}
ParametersEdit
- 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 valuesEdit
Returns the array with the given index removed.
ExamplesEdit
Remove a top-level index | {{#af_print: {{#af_unset: {{#af_list: a | b | c }} | 2 }} }} |
|
Remove a top-level index, keys not reset | {{#af_print: {{#af_unset: {{#af_list: a | b | c }} | 1 }} }} |
|
Remove a nested index | {{#af_print: {{#af_unset: {{#af_object: foo={{#af_object: bar=quz | far=buz }} }} | foo | bar }} }} |
|
ScribuntoEdit
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:
local p = {};
function p.world()
return mw.af.export({
["Hello"] = "World"
});
end
return p;
This module may then be invoked like so:
{{#af_print: {{#invoke: Hello | world }} }} |
|
Magic wordsEdit
The extension defines a number of magic words (variables).
AF_EMPTYEdit
This magic word returns the empty array. This is useful, because it is not possible to create an empty array with #af_list
or #af_object
.
DescriptionEdit
{{AF_EMPTY}}
Return valuesEdit
Returns the empty array.
InstallationEdit
- Download and place the file(s) in a directory called
ArrayFunctions
in yourextensions/
folder. - Add the following code at the bottom of your
LocalSettings.php
:wfLoadExtension( 'ArrayFunctions' );
- Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
FAQEdit
How can I define an array to be used throughout a page?Edit
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#No support for sequential, in-order processing of extension tags). Instead, you can pass arrays around as template parameters:
{{My template|{{#af_list:a|b|c}}}}
This way, the array is available in Template:My template
as {{{1}}}
.
How to iterate over an array?Edit
It is possible to iteratively access elements of an array using #af_foreach:
{{#af_foreach:{{#af_list:red|green|blue}}||color|<nowiki/> * {{{color}}} is my favourite. }}
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?Edit
Using #af_foreach with a delimiter is not supported. Instead, you can use the #af_map function in conjunction with the #af_join function:
{{#af_join:{{#af_map:{{#af_list:red|green|blue}}|color|* {{{color}}} is my favourite.}}|\n}}
See alsoEdit
- Extension:Arrays - similar extension that works by first defining and then manipulating arrays. Incompatible with Parsoid.
- Extension:PhpTags Functions/Functions/Array - includes over fifty functions for working with arrays using the PHP syntax.
- Extension:Scribunto - allows you to embed Lua scripts into wikipages.