The
Arrays
extension (formerly known as
ArrayExtension
) creates an additional set of
parser functions
that operate on
arrays
.
Functions
[
edit
]
This extension defines the following parser functions:
Group
|
Functions
|
Construct an array, (with unique, sort, print options)
|
#arraydefine
|
Extract information from an array
|
#arrayprint
,
#arrayindex
,
#arraysize
,
#arraysearch
,
#arraysearcharray
,
#arrayslice
|
Alter an array
|
#arrayreset
,
#arrayunique
,
#arraysort
|
Interaction between several arrays
|
#arraymerge
,
#arrayunion
,
#arrayintersect
,
#arraydiff
|
In case
Extension:HashTables
is installed, for array/hash-table interaction
|
#hashtoarray
,
#arraytohash
|
Constructing arrays
[
edit
]
arraydefine
[
edit
]
This function constructs an array (identified by 'key') using a list of 'values' separated by the 'delimiter'.
The variable can be accessed by other functions later.
Syntax:
{{#arraydefine:key|values|delimiter|options}}
Notes:
- values
is a list of strings separated by
delimiter
.
- The resulting array is an array of strings.
- The default delimiter is ',' if not specified, a delimiter can be a string (the white-spaces surrounding delimiter will be trimmed) or a Perl regular expression, e.g.
/\s*,\s*/
(see
preg_split
).
- Users can define an empty array (see example).
- Users can specify options including unique, sort, and print (see example).
- Options are ignored unless a delimiter is also specified.
Examples:
Define a one-element array named 'a'
|
{{#arraydefine:a|red}}
|
Define a four-element array named 'b', use default delimiter (',')
|
{{#arraydefine:b|orange, red, yellow, yellow}}
|
Define/set an empty array named 'c'
|
{{#arraydefine:c}}
|
Define a two-element array named 'd', using ';' as delimiter
|
{{#arraydefine:d|apple; pear|;}}
|
Define a three-element array named 'e', using the regular expression
/\s*[;,]\s*/
as delimiter
|
{{#arraydefine:e|apple, pear; orange|/\s*[;,]\s*/}}
|
Define a three-element array named 'f', use delimiter (','), "unique, sort=desc, print=list" options (the array elements are unique, sorted in descending order and being printed). For more option-values of sort, see
#arraysort
.
|
{{#arraydefine:f|orange, red, yellow, yellow |, |unique, sort=desc, print=list}}
|
Working with arrays
[
edit
]
arrayprint
[
edit
]
This function prints the values of an array in customizable format.
Syntax:
{{#arrayprint:key|delimiter|pattern|subject|options}}
Notes:
- subject
accepts wiki links, templates and parser functions.
- Within the
subject
, you
don't
have to escape pipe characters '
|
'. Within the whole construct, the
pattern
will be searched and replaced with the current (escaped) array value of each loop. Finally, the whole string will be parsed and put into an array of results which will be imploded with
delimiter
as separator.
- In case the array which should be printed doesn't exist, an empty string will be returned (Introduced in 1.4 alpha, part of compatibility mode).
- The default delimiter is language dependent, for English it is '
,
' (Introduced in 2.0, part of compatibility mode).
Examples:
Task
|
Example code
|
Output (the array b is defined above)
|
Print - using language dependent default list delimiter
|
{{#arrayprint:b}}
|
- orange, red, yellow, yellow
|
Print - without delimiter
|
{{#arrayprint:b | }}
|
|
Print - using '
<
br
/>
' (line-break) as delimiter
|
{{#arrayprint:b |<br/> }}
|
orange
red
yellow
yellow
|
Pretty list output where the last two elements are chained with an '
and
' (or the local languages equivalent). Even though the
delimiter
parameter is empty, '
,
' (or the languages equivalent) will be used since it wouldn't be pretty otherwise.
|
{{#arrayprint:b ||@ |@ |print=pretty }}
|
|
Embed wiki link to categories
|
{{#arrayprint:b |<br/> |@@@@ |[[:Category:@@@@|@@@@]] }}
|
orange
red
yellow
yellow
|
Define a Semantic MediaWiki property value
|
{{#arrayprint:b |<br/> |@@@@ |[[prop1::@@@@]] }}
|
|
Embed parser function
|
{{#arrayprint:b |<br/> |@@@@ |length of @@@@:{{#len:@@@@}} }}
|
|
Embed template (with parameters)
|
{{#arrayprint:b|<br/>|@@@@|{{template|prop2|@@@@}} }}
|
|
arrayindex
[
edit
]
This function prints the value of an array (identified by
key
) at position
index
.
Syntax:
{{#arrayindex:key|index|default}}
Notes:
- Invalid index (non-number, out of bound) will result in printing an empty string.
- The index is 0-based, i.e. the first element's index is 0.
- Negative indexes will return an element that far from the end (e.g.
-1
would be the arrays last element).
- default
will be returned in case the array doesn't exist, the key doesn't exist within the array or if the value is an empty string.
Examples:
Third element within array
a
|
{{#arrayindex:a |2 }}
|
Last element within array
b
|
{{#arrayindex:b |-1 }}
|
Print default value for invalid index
|
{{#arrayindex:c |foo |bad value }}
|
arraysize
[
edit
]
This function returns the size (number of elements) of an array.
See
https://php.net/function.count
In case the given array doesn't exist the output of the function will be a void string instead of a number. This allows to check whether the array exists.
Syntax:
{{#arraysize:key}}
Examples:
Size of array
a
:
|
{{#arraysize:a}}
|
Check whether array
a
exists or not:
|
{{#if: {{#arraysize:b}} | ''array exists'' | ''array not defined'' }}
|
arraysearch
[
edit
]
This function returns the index of the first occurrence of the 'value' in the array (identified by 'key') starting from the position identified by 'index' parameter, and returns an empty string when failed.
When
yes
and/or
no
specified, this will expand the value set to
yes
if found, value of
no
otherwise.
See
https://php.net/function.array-search
Syntax:
{{#arraysearch:key|value|index|yes|no}}
Examples:
Return index of first occurrence of a value
|
{{#arraysearch:b|white}}
{{#arraysearch:b|red}}
use offset
{{#arraysearch:b|red|0}}
{{#arraysearch:b|red|2}}
use preg regular expression match
{{#arraysearch:b|/low/}}
{{#arraysearch:b|/LOW/i}} - case insensitive
{{#arraysearch:b|low}}
use yes no print option
{{#arraysearch:b|white|0|yes|no}}
{{#arraysearch:b|yellow|0|yes|no}}
|
arraysearcharray
[
edit
]
This function searches an array (identified by
key
) and creates a new array (identified by
new_key
) from the search with all the results. The search criteria
value
can be a string or a regular expression. If
index
is given the search will start there,
limit
can define the maximum search results. The parameter identified by
transform
can be used if
value
is a regular expression. It can transform the result of the matched entries into the
new_key
array like
PHP preg_replace
would do it.
Syntax:
{{#arraysearcharray:new_key|key|value|index|limit|transform}}
Notes:
- If
value
is a string, the
new_key
array will only contain entries of exact this string.
- Negative
index
values like
-n
can be used to search the last
n
entries only.
- If
Extension:Regex Fun
is available within the wiki, Regex Fun's
e
modifier can be used within the regex. This has nothing to do with PHPs
e
modifier (which would be a security breach). With active
e
modifier the
transform
string will be parsed after back-refs are inserted, after that it will replace the actual match.
Examples:
Find all entries in array 'a' that start with
A
followed by a space and put them into a new array 'x'.
|
{{#arraysearcharray:x |a |/^A\s.+/ }}
|
Searching all entries of array 'a' which end with numbers and put the numbers only into a new array 'y'.
|
{{#arraysearcharray:y |a |/^.*?(\d+)$/ |0 |-1 | $1 }}
|
Searching all entries of array 'a' which end with numbers and put the length of these items into the new array (this requires
Regex Fun
extension).
|
{{#arraysearcharray:y |y |/^.*?\d+$/e |0 |-1 | {{#len:$0}} }}
|
Remove empty values from array 'a'.
|
{{#arraysearcharray:a|a|/\S+/}}
|
arrayslice
[
edit
]
This function extracts a sub-array from an array (identified by 'key') into a new array (identified by 'new_key').
See
https://php.net/function.array-slice
Syntax:
{{#arrayslice:new_key|key|offset|length}}
Notes:
- Offset indicates starting point of slice, it can be non-negative number or negative number for backwards index (e.g. the last element of the array's offset is -1). Offset is different from index (which must be non-negative number)
- Length indicates how many element to extract. If it is omitted, then the sequence will have everything from offset up until the end of the array.
- If offset is no less than array size, empty array will be returned, if offset if no greater than negative array size, a new array with all elements will be returned.
Examples:
Extract a two-element slice starting from the element at offset 1.
|
{{#arrayslice:x|b|1|2}}
|
Extract a two-element slice starting from the element at offset -2.
|
{{#arrayslice:x|b|-2|2}}
|
Alteration
[
edit
]
Functions which alter an array directly instead of creating a new array.
arrayunique
[
edit
]
This function converts an array (identified by 'key') into a set (no duplicated members, no empty element).
See
https://php.net/function.array-unique
Syntax:
{{#arrayunique:key}}
Example:
Convert array to set.
|
{{#arrayunique:b}}
|
arrayreset
[
edit
]
This function will unset some or all defined arrays.
Syntax:
{{#arrayreset:}}
<!-- will unset ALL arrays -->
{{#arrayreset:key1 |key2 |... |key-n }}
Notes:
- Using
arraysize
on them will return an empty string instead of
0
, so they are really unset, not empty. To simply empty an array one can use
{{#arraydefine:key}}
.
- Prior to version 1.4 alpha '
,
' is used to separate several arrays which should be unset.
arraysort
[
edit
]
This function sorts an array in the following order.
Syntax:
{{#arraysort:key|order}}
Note:
- Each array element is being treated as a string, this means numbers might not be ordered as expected.
Examples:
Sort an array.
|
{{#arraysort:x|desc}}
|
Randomize an array.
|
{{#arraysort:x|random}}
|
Reverse an array.
|
{{#arraysort:x|reverse}}
|
Interaction
[
edit
]
Functions which work with more than one array, creating one new array or overwriting an existing one as result. Since version 2.0, these functions can interact with more than just two arrays at a time. In case they deal with only one array, they simply create a copy of that array. Any non-existent arrays will simply be ignored by these functions.
arraymerge
[
edit
]
This function merges values of two or more arrays into a new array (identified by
new_key
).
See
https://php.net/function.array-merge
Syntax:
{{#arraymerge:new_key |key1 |key2 |... |key-n }}
Examples:
Merge two arrays.
|
{{#arraymerge:x |a |b }}
|
Duplicate an array (keep the third argument of
arraymerge
empty).
|
{{#arraymerge:x |b }}
|
arrayunion
[
edit
]
This function merges values of two or more arrays into a new array (identified by
new_key
) without duplicated values.
Syntax:
{{#arrayunion:new_key |key1 |key2 |... |key-n }}
Notes:
- This is a set operator, i.e., the returned array is a set without duplicated values.
- This is equal to
arraymerge
with
arrayunique
afterwards.
Example:
Union of three arrays.
|
{{#arrayunion:x |a |b |c }}
|
arraydiff
[
edit
]
This function computes the (set theoretic) difference of two or more arrays. The result array is identified by
new_key
.
The returned array is a set that contains elements of the first given array (identified by
key1
) which are not defined within any of the other arrays.
See
https://php.net/function.array-diff
Syntax:
{{#arraydiff:new_key |key1 |key2 |... |key-n }}
Note:
- This is a set operator, i.e. the returned array is a set without duplicated values.
- This function can be used to test sub-class relation.
Examples:
Diff (b-a)
|
{{#arraydiff:x |b |a }}
|
Diff (a-b)
|
{{#arraydiff:x |a |b }}
|
Diff (a-(b+c))
|
{{#arraydiff:x |a |b |c }}
|
arrayintersect
[
edit
]
This function computes the set theoretic intersection of two or more given arrays. The result array is identified by
new_key
.
See
https://php.net/function.array-intersect
Syntax:
{{#arrayintersect:new_key |key1 |key2 |... |key-n }}
Note:
- This is a set operator, i.e., the returned array is a set without duplicated values.
Example:
Intersect of three arrays put into new array
x
|
{{#arrayintersect:x |a |b |c }}
|
Installation
[
edit
]
- Download
and move the extracted
Arrays
folder to your
extensions/
directory.
Developers and code contributors should install the extension
from Git
instead, using:
cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Arrays
- Add the following code at the bottom of your
LocalSettings.php
file:
wfLoadExtension
(
'Arrays'
);
- Configure as required.
-
Done
? Navigate to
Special:Version
on your wiki to verify that the extension is successfully installed.
Configuration
[
edit
]
Arrays
2.0 introduces two configuration variables:
- $egArraysCompatibilityMode
- (
$egArrayExtensionCompatbilityMode
in 1.4 alpha) Set to
true
, this will activate the compatibility mode which will bring back the behavior of the old
ArrayExtension
1.3.2 as far as possible. This is because in Version 2.0 several breaking changes have been introduced. So using this compatibility mode allows a smooth switch from 1.x to 2.x
Arrays
extension. By default, compatibility mode is inactive. If you have been using the old
ArrayExtension
within your wiki before, you might want to take a look at that list and adjust your templates before switching to
Arrays
without compatibility mode.
- $egArraysExpansionEscapeTemplates
- Contains a key-value pair list of characters that should be replaced by a template or parser function call within array values included into an
#arrayprint
. By replacing these special characters before including the values into the string which is being expanded afterwards, array values can't distract the surrounding MW code. Otherwise the array values themselves would be parsed as well. By default this will escape the following characters with the following template or parser function calls:
=
=
{{=}}
("Template:=" should print '
=
')
|
=
{{!}}
("Template:!" should print '
|
')
-
Note:
Starting with MW 1.24.0 it is no longer necessary to create "Template:!" since its purpose is served by the new
{{!}}
magic word.
{{
=
{{((}}
("Template:((" should print '
{{
')
}}
=
{{))}}
("Template:))" should print '
}}
')
- Make sure these templates or parser functions exist within your wiki or change this variable accordingly. If this is not set up properly,
#arrayprint
might print unexpected values in case one of these character sequences is being used within array values.
- $egArraysExpansionEscapeTemplates
also can simply be set to
null
, in this case it switches back to pre 2.0 behavior where array values with these character sequences did break the given
subject
code within
#arrayprint
. If the compatibility mode is active, this will always be treated as set to
null
.
Iteratively accessing array elements
[
edit
]
It is possible to iteratively access elements of an array using
#arrayprint
or
Extension:Loops
.
Using arrayprint
[
edit
]
<!-- define an array -->
{{#arraydefine:colors|Red,Blue,Yellow}}
{{#arrayprint:colors||@@@@|
<
nowiki
/>
* length of @@@@: {{#len:@@@@}}
}}
Below is the expected output:
- length of Red: 3
- length of Blue: 4
- length of Yellow: 6
|
More examples can be found at
the former Tetherless World Wiki
.
Reusing keys
[
edit
]
Once an array previously defined is printed, the same key can be reused for another array further down the page. As long as this sequence is observed, there is no need to define a unique key for every array.
Using Loops extension
[
edit
]
For more complex tasks it is possible to loop through an array using the
Loops
extension.
{{ #arraydefine: colors | red;#FF0000, green;#00FF00, blue;#0000FF }}
{{
#loop: i
| 0
<!-- loops start value for {{ #var:i }} -->
| {{ #arraysize:colors }}
<!-- number of loops -->
|
<
nowiki
/>
* {{
#arraydefine: val | {{ #arrayindex:colors | {{ #var:i }} }} | ;
}}
<
span
style
=
"color:{{ #arrayindex: val | 1 }}"
>
{{ #arrayindex: val | 0 }}
</
span
>
}}
This would output something like:
There are two ways populating an array with semantic data. The first solution, using Semantic Result Formats is faster and more reliable, also works with complex data sets including record data and multiple values for one property.
Semantic Result Formats (SRF) introduces the
Array
format in version 1.6.1. It can be used to query data which will automatically be stored within an
Extension:Arrays
array. This is the preferred solution dealing with semantic data in arrays. Details can be found on the
semantic-mediawiki.org
.
Example:
{{#ask: [[Category:Color]][[:+]] |format=array |name=colors}}
{{#arrayprint: colors}}
Using a standard query
[
edit
]
If you can't use the SRF solution above,
Arrays
also allows to populate an array using a SMW query result of the
list
format:
Example A:
To create a list of instances of the class 'Color'
{{#arraydefine:colors|{{#ask:[[Category:Color]][[:+]] |sep =, |limit=1000}} }}
Example B:
To create a unique list of values of property 'has color'
{{#arraydefine:colors|{{#ask:[[has color::+]][[:+]] |?color= |mainlabel=- |sep =, |limit=1000}} |,|unique}}
Example C:
To deal with 2D array generated by SWM query (e.g. record-type property)
given a 2D array "red;#da2021, yellow;#fcff00, green;#00ff00"
1. create an array 'colors'
{{#arraydefine:colors|red;#da2021, yellow;#fcff00, green;#00ff00}}
2. split the first element of 'colors' into another array 'colors0'
{{#arraydefine:color0|{{#arrayindex:colors|0}}|;}}
Notes:
- semantic query parameters
limit=1000
option is used to exhaust all returned results of the semantic query
sep=,
option is used to set the separator for entries of the results
mainlabel=-
option to cut off the page column
In a similar way as described above for SMW the
Arrays
extension can be used to store results of a
DPL query
. A result list can be inverted. We collect all parameter values which are used by certain pages when they include a given template. We store pairs of
template parameter value
and
pagename
. Then we sort the array and print the pairs. If consecutive array elements have the same first part (i.e. the parameter values are identical), the first part is only printed once. Thus we can construct a simple inverted index. The same mechanism could be applied to other problems as well.
See also
[
edit
]
| This extension is included in the following wiki farms/hosts and/or packages:
This is not an authoritative list.
Some wiki farms/hosts and/or packages may contain this extension even if they are not listed here.
Always check with your wiki farms/hosts or bundle to confirm.
|