MediaWiki

Extension:ArrayFunctions

(Redirected from User:Xxmarijnw/Extension:ArrayFunctions)
Translate this page
Languages:
MediaWiki extensions manual
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.11.0 (2024-12-10)
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
Download extension
Git [?]:
Hooks used
Quarterly downloads 2 (Ranked 134th)
Translate the ArrayFunctions extension if it is available at translatewiki.net
Issues Open tasks · Report a bug
Presentation at SMWCon 2022 talking about ArrayFunctions
Presentation at EMWCon 2023 talking about ArrayFunctions
Workshop given at SMWCon 2023 about making your wiki Parsoid-compatible
Presentation at SMWCon 2023 talking about Parsoid and ArrayFunctions

Documentation for other releases: 1.0 · 1.1 · 1.2 · 1.3 · 1.4 · 1.5 · 1.6 · 1.7 · 1.8 · 1.9 · 1.10 · 1.11 · unreleased

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.

Installation

edit
  • Download and move the extracted ArrayFunctions 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/ArrayFunctions
  • Add the following code at the bottom of your LocalSettings.php file: 
    wfLoadExtension( 'ArrayFunctions' );
// Increase $wgMaxArticleSize to allow for larger arrays (default: 2048)
$wgMaxArticleSize = 8192;
  •   Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

FAQ

edit

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.

Why are values not recognized as arrays?

edit

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?

edit

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 directly outputs its result.

For example with #af_map, 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 must be used to perform more complex operations. For example:

Arrays
{{#arraydefine: fruits | orange, banana, strawberry, apple }}
{{#arraysort: fruits | asc }}
{{#arrayprint: fruits }}
ArrayFunctions
{{#af_print: 
    {{#af_sort: 
        {{#af_list: orange | banana | strawberry | apple }}
    }}
}}

Why is whitespace trimmed from array values?

edit

Whitespace is inherently implicit in wikitext. In order to be consistent with this behaviour, whitespace is recursively trimmed from array values.

Functions

edit

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.

The 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 for debug purposes.
#af_search Searches an array for a value.
#af_show Show a value in a human-readable format.
mw.af.import Create a new table from an ArrayFunctions array.
Create an array from an existing array
Name Description
#af_difference Compute the difference between arrays.
#af_flatten Flatten an array.
#af_intersect Compute the intersection of arrays.
#af_keysort Sort a list of objects based on the values of a key.
#af_ksort Sort an array by key.
#af_merge Compute the union of arrays.
#af_push Add a value to the end of a list.
#af_reverse Reverse an array.
#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.
#af_wildcard Compute an array that when indexed yields all elements of a key from all subarrays.
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_stringmap Apply a callback to each value in a delimited string.
#af_template Invoke a template with the values in an array.
#af_trim Trim characters at the start and end of a string.
Notes
  • All keyword argument names are case-sensitive.
  • All string arguments support the following escape sequences:
\s for spaces
\n for newlines
\\ for backslashes

af_bool

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_bool: value }}

Parameters

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

Return values

edit

Returns the casted boolean.

Examples

edit
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}} }} }}
  • 0: true

af_count

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_count: array | recursive=recursive }}

Parameters

edit
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

edit

The number of items in the array.

Examples

edit
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_difference

edit
ArrayFunctions version
≥ 1.5
 
The difference between three arrays

This parser function computes the difference between arrays. This function preserves keys. Two values are considered equal if their string representation is the same (see array_diff on PHP.net).

Description

edit 
{{#af_difference: array | *arrays }}

Parameters

edit
array : array
The first array.
*arrays : array
The other arrays.

Return values

edit

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

Examples

edit
Compute the difference of three arrays 
{{#af_print: {{#af_difference: {{#af_list: a | b | c }} | {{#af_list: a }} | {{#af_list: b}} }} }}
  • 2: c

af_exists

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_exists: array | key }}

Parameters

edit
array : array
The array to check.
key : string or int
The key to check.

Return values

edit

Returns true if array contains key, false otherwise.

Examples

edit
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_flatten

edit
ArrayFunctions version
≥ 1.11

This parser function creates a new array with all sub-array elements concatenated into it recursively up to the specified depth, or until it is completely flattened if no depth is specified.

Description

edit 
{{#af_flatten: array | depth }}

Parameters

edit
array : array
The array to flatten.
depth : integer, default=null
The depth to flatten to, or nothing to flatten until the array is completely flat.

Return values

edit

Returns an array with all sub-array elements concatenated into it recursively up to the specified depth, or a completely flattened array if no depth is specified.

Examples

edit
Flatten an array one level deep 
{{#af_print: {{#af_flatten: {{#af_list: {{#af_list: a | b | c }} | {{#af_list: d | e | f }} }} }} }}
  • 0: a
  • 1: b
  • 2: c
  • 3: d
  • 4: e
  • 5: f

af_float

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_float: value }}

Parameters

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

Return values

edit

Returns the casted float.

Examples

edit
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 }} }} }}
  • 0: 1.298

af_foreach

edit
ArrayFunctions version
≥ 1.0

This parser function provides a way to iterate over arrays.

Description

edit 
{{#af_foreach: array | key_name | value_name | body | delimiter=delimiter }}

Parameters

edit
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.
delimiter : string, default=""
The delimiter to put between results (available since version 1.9.0).

Return values

edit

Returns the resulting wikitext.

Examples

edit
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!
Iterate over a list and add a delimiter 
{{#af_foreach: {{#af_list: John | Steve | Harry }} | | name | Hello, {{{name}}}! | delimiter=<br/> }}
 Hello, John!
Hello, Steve!
Hello, Harry!

af_get

edit
ArrayFunctions version
≥ 1.0

This parser function retrieves the element with the given index from the given array, or performs some operation if the index is overloaded. If the index does not exist and it is not an overloaded index, the empty string is returned. An overloaded index allows the user to succinctly perform certain simple operations on arrays during indexing. Using an overloaded index is identical to first performing an #af_get with all indices before the overloaded index, then performing the function specified by the overloaded index, and then performing another #af_get with the remaining indices. For example, {{#af_get: {{{1}}} | a | * | b }} is equivalent to {{#af_get: {{#af_wildcard: {{#af_get: {{{1}}} | a }} }} | b }}.

Description

edit 
{{#af_get: array | *indices }}

Parameters

edit
array : array
The array in which to index.
*indices : string
The index. Multiple indices can be given to index nested arrays.
Overloaded indices (available since version 1.11.0)
edit
Syntax Equivalent function Description
* #af_wildcard Compute the wildcard array.
<- #af_reverse Reverse the array.
>< #af_flatten Flatten the array once.
>><< #af_flatten Flatten the array until it is completely flat.
# #af_unique Remove duplicates from the array.
n..m #af_slice Retrieve a slice of the array.

Return values

edit

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

Examples

edit
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 }} }}
  • 0: b
  • 1: c
Get a nested element 
{{#af_get: {{#af_list: a | {{#af_object: hello=world }} }} | 1 | hello }}
world
Reverse the array 
{{#af_print: {{#af_get: {{#af_list: a | b | c }} | <- }} }}
  • 0: c
  • 1: b
  • 2: a

af_if

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_if: predicate | consequent | alternative }}

Parameters

edit
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

edit

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

Examples

edit
Check if a value is an array 
{{#af_if: {{#af_isarray: not an array }} | A beautiful array! | Not an array! }}
 Not an array!

af_int

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_int: value }}

Parameters

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

Return values

edit

Returns the casted integer.

Examples

edit
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}} }} }}
  • 0: -129

af_intersect

edit
ArrayFunctions version
≥ 1.2
 
The intersection of three arrays

This parser function computes the intersection of arrays. This function preserves keys. Two values are considered equal if their string representation is the same (see array_intersect on PHP.net).

Description

edit 
{{#af_intersect: array | *arrays }}

Parameters

edit
array : array
The first array.
*arrays : array
The other arrays.

Return values

edit

Returns the intersection of the given arrays.

Examples

edit
Compute the intersection of two identical arrays 
{{#af_print: {{#af_intersect: {{#af_list: a | b | c }} | {{#af_list: a | b | c }} }} }}
  • 0: a
  • 1: b
  • 2: c
Compute the intersection of two partially overlapping arrays 
{{#af_print: {{#af_intersect: {{#af_list: a | b | c }} | {{#af_list: c | d | e }} }} }}
  • 2: c

af_isarray

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_isarray: value }}

Parameters

edit
value : mixed
The value to check.

Return values

edit

Returns true if value is an array, false otherwise.

Examples

edit
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_join

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_join: array | glue }}

Parameters

edit
array : array
The array to join.
glue : string, default=""
The string used to join each item.

Return values

edit

Returns the joined array.

Examples

edit
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_keysort

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_keysort: array | key | descending=descending | caseinsensitive=caseinsensitive }}

Parameters

edit
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 (available since version 1.7.0).

Return values

edit

Returns the sorted array.

Examples

edit
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 }} }}
  • 0
    • name: Harry
    • age: 12
  • 1
    • name: Bob
    • age: 24
  • 2
    • name: John
    • age: 56
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 }} }}
  • 0
    • name: John
    • age: 56
  • 1
    • name: Bob
    • age: 24
  • 2
    • name: Harry
    • age: 12

af_ksort

edit
ArrayFunctions version
≥ 1.7

This parser function sorts an array by key.

Description

edit 
{{#af_ksort: array | descending=descending | caseinsensitive=caseinsensitive }}

Parameters

edit
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 (available since version 1.7.0).

Return values

edit

Returns the sorted array.

Examples

edit
Sort by key 
{{#af_print: {{#af_ksort: {{#af_object: c=banana | a=orange | b=apple }} }} }}
  • a: orange
  • b: apple
  • c: banana

af_list

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_list: *values }}

Parameters

edit
*values : mixed
The values for the list.

Return values

edit

Returns the resulting list.

Examples

edit
Create a simple one-dimensional list 
{{#af_print: {{#af_list: a | b | c }} }}
  • 0: a
  • 1: b
  • 2: c
Create a multi-dimensional list 
{{#af_print: {{#af_list: {{#af_list: a | b }} | {{#af_list: c | d }} }} }}
  • 0
    • 0: a
    • 1: b
  • 1
    • 0: c
    • 1: d
Create a list of objects 
{{#af_print: {{#af_list:
    {{#af_object: name=Harry | age=22 }} |
    {{#af_object: name=Bobby | age=29 }}
}} }}
  • 0
    • name: Harry
    • age: 22
  • 1
    • name: Bobby
    • age: 29

af_map

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_map: array | value_name | callback }}

Parameters

edit
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

edit

Returns the resulting mapped array.

Examples

edit
Appending a string to each element 
{{#af_print: {{#af_map: {{#af_list: a | b | c }} | v | {{{v}}}-appended }} }}
  • 0: a-appended
  • 1: b-appended
  • 2: c-appended
Altering list elements 
{{#af_print: {{#af_map: {{#af_list: {{#af_list: a }} | {{#af_list: b }} }} | v | {{#af_push: {{{v}}} | c }} }} }}
  • 0
    • 0: a
    • 1: c
  • 1
    • 0: b
    • 1: c

af_merge

edit
ArrayFunctions version
≥ 1.2
 
The union of three arrays

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.

Description

edit 
{{#af_merge: array | *arrays }}

Parameters

edit
array : array
The first array.
*arrays : array
The other arrays.

Return values

edit

Returns the union of the given arrays.

Examples

edit
Appending a string to each element 
{{#af_print: {{#af_merge: {{#af_list: a | b | c }} | {{#af_list: d | e | f }} }} }}
  • 0: a
  • 1: b
  • 2: c
  • 3: d
  • 4: e
  • 5: f

af_object

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_object: **values }}

Parameters

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

Return values

edit

Returns the resulting object.

Examples

edit
Create a simple one-dimensional object 
{{#af_print: {{#af_object: a=b | b=c | c=d }} }}
  • 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 }} }} }} }} }}
  • head
    • title: MediaWiki
    • meta
      • 0
        • charset: UTF-8

af_print

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_print: *values | end=end }}

Parameters

edit
*values : mixed
The values to print.
end : string, default=""
The string to append to the end of each printed value.

Return values

edit

Returns the value in human-readable form.

Examples

edit
Print a boolean 
{{#af_print: {{#af_bool: yes }} }}
 true
Print a list 
{{#af_print: {{#af_list: a | b | c }} }}
  • 0: a
  • 1: b
  • 2: c

af_push

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_push: array | value }}

Parameters

edit
array : array
The array to append the value to.
value : mixed
The value to add.

Return values

edit

Returns the array with the value appended.

Examples

edit
Push a value 
{{#af_print: {{#af_push: {{#af_list: a | b }} | c }} }}
  • 0: a
  • 1: b
  • 2: c

af_reduce

edit
ArrayFunctions version
≥ 1.2

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.

Description

edit 
{{#af_reduce: array | carry_name | value_name | callable | initial }}

Parameters

edit
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

edit

Returns the resulting value.

Examples

edit
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_reverse

edit
ArrayFunctions version
≥ 1.11

This parser function reverses the given array.

Description

edit 
{{#af_reverse: array }}

Parameters

edit
array : array
The array to reverse.

Return values

edit

Returns the original array reversed.

Examples

edit
Reverse a list 
{{#af_print: {{#af_reverse: {{#af_list: a | b | c}} }} }}
  • 0: c
  • 1: b
  • 2: a
edit
ArrayFunctions version
≥ 1.3

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

Description

edit 
{{#af_search: array | value }}

Parameters

edit
array : array
The array to search in.
value : mixed
The value to search for.

Return values

edit

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

Examples

edit
Search for a value in an array 
{{#af_print: {{#af_search: {{#af_list: a | b | c }} | b }} }}
 1

af_set

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_set: value | array | *indices }}

Parameters

edit
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

edit

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

Examples

edit
Replace an existing value 
{{#af_print: {{#af_set: d | {{#af_list: a | b | c }} | 2 }} }}
  • 0: a
  • 1: b
  • 2: d
Create a new index 
{{#af_print: {{#af_set: far | {{#af_object: foo=bar }} | boo }} }}
  • foo: bar
  • boo: far
Create a new subarray 
{{#af_print: {{#af_set: far | {{#af_object: foo=bar }} | boo | far }} }}
  • foo: bar
  • boo
    • far: far

af_show

edit
ArrayFunctions version
≥ 1.4

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

Description

edit 
{{#af_show: value }}

Parameters

edit
value : mixed
The value to show.

Return values

edit

Returns the value in human-readable form.

Examples

edit
Show a value 
{{#af_show: Hello World! }}
 Hello World!

af_slice

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_slice: array | offset | length }}

Parameters

edit
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

edit

The slice.

Examples

edit
Get the first two elements 
{{#af_print: {{#af_slice: {{#af_list: a | b | c }} | 0 | 2 }} }}
  • 0: a
  • 1: b
Get the last element 
{{#af_print: {{#af_slice: {{#af_list: a | b | c }} | -1 }} }}
  • 0: c

af_sort

edit
ArrayFunctions version
≥ 1.0

This parser function sorts the given list.

Description

edit 
{{#af_sort: array | descending=descending | caseinsensitive=caseinsensitive }}

Parameters

edit
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

edit

Returns the sorted list.

Examples

edit
Sort a list in ascending order 
{{#af_print: {{#af_sort: {{#af_list: b | c | a }} }} }}
  • 0: a
  • 1: b
  • 2: c
Sort a list in descending order 
{{#af_print: {{#af_sort: {{#af_list: b | c | a }} | descending=true }} }}
  • 0: c
  • 1: b
  • 2: a

af_split

edit
ArrayFunctions version
≥ 1.1

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

Description

edit 
{{#af_split: string | delimiter }}

Parameters

edit
string : string
The string to split.
delimiter : string, default=","
The delimiter to use.

Return values

edit

Returns the resulting list.

Examples

edit
Split a string based on commas 
{{#af_print: {{#af_split: a, b, c }} }}
  • 0: a
  • 1: b
  • 2: c
Split a sentence into words 
{{#af_print: {{#af_split: Lorem ipsum dolor et | \s }} }}
  • 0: Lorem
  • 1: ipsum
  • 2: dolor
  • 3: et

af_stringmap

edit
ArrayFunctions version
≥ 1.6

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.

Description

edit 
{{#af_stringmap: value | delimiter | value_name | callback | new_delimiter | conjunction }}

Parameters

edit
value : string
The delimited string.
delimiter : string
The delimiter to split value on. If the empty string is given, "," is used.
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.
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 new_delimiter is used.

Return values

edit

Returns the resulting delimited string.

Examples

edit
Turn each item into a link 
{{#af_stringmap: William Shakespeare, Stephen King, Mark Twain | , | x | [[{{{x}}}]] }}
 William Shakespeare, Stephen King, Mark Twain
Turn a comma-separated list into a human-readable list 
{{#af_stringmap: William Shakespeare, Stephen King, Mark Twain | , | x | {{{x}}} | ,\s | and }}
 William Shakespeare, Stephen King and Mark Twain

af_template

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_template: name | data }}

Parameters

edit
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

edit

The expanded template.

Examples

edit
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_trim

edit
ArrayFunctions version
≥ 1.8

This parser function will trim the given character from the beginning and the end of the given string.

Description

edit 
{{#af_trim: string | characters }}

Parameters

edit
string : string
The string that will be trimmed.
characters : string
The characters to trim.

Return values

edit

The trimmed string.

Examples

edit
Trimming a string 
{{#af_trim: !a! | ! }}
 
a
Trimming every string in a list 
{{#af_print: {{#af_map: {{#af_list: !a! | !b! | !c! }} | v | {{#af_trim: {{{v}}} | ! }} }} }}
  • 0: a
  • 1: b
  • 2: c

af_unique

edit
ArrayFunctions version
≥ 1.0

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

Description

edit 
{{#af_unique: array }}

Parameters

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

Return values

edit

Returns the array with duplicates removed.

Examples

edit
Remove duplicates from an array 
{{#af_print: {{#af_unique: {{#af_list: a | a | b | c | b }} }} }}
  • 0: a
  • 2: b
  • 3: c

af_unset

edit
ArrayFunctions version
≥ 1.0

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.

Description

edit 
{{#af_unset: array | *indices }}

Parameters

edit
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

edit

Returns the array with the given index removed.

Examples

edit
Remove a top-level index 
{{#af_print: {{#af_unset: {{#af_list: a | b | c }} | 2 }} }}
  • 0: a
  • 1: b
Remove a top-level index, keys not reset 
{{#af_print: {{#af_unset: {{#af_list: a | b | c }} | 1 }} }}
  • 0: a
  • 2: c
Remove a nested index 
{{#af_print: {{#af_unset: {{#af_object: foo={{#af_object: bar=quz | far=buz }} }} | foo | bar }} }}
  • foo
    • far: buz

af_wildcard

edit
ArrayFunctions version
≥ 1.11

This parser function computes an array where subarrays are recursively grouped together by key. It is called af_wildcard, because it behaves similarly to indexing all keys (like a wildcard) and collecting the results.

Description

edit 
{{#af_wildcard: array }}

Parameters

edit
array : array
The array for which to group subarrays together.

Return values

edit

Returns an array where subarrays are recursively grouped together by key.

Examples

edit
Compute a wildcard array 
{{#af_print: {{#af_wildcard: {{#af_list: {{#af_object: a=1 | b=2 }} | {{#af_object: a=3 | b=4 }} | {{#af_object: a=5 | b=5 }} }} }} }}
  • a
    • 0: 1
    • 1: 3
    • 2: 5
  • b
    • 0: 2
    • 1: 4
    • 2: 5

Scribunto

edit
It is recommended to use LuaSandbox, because the order of arrays is not preserved when using LuaStandalone (see task T349590).

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 }} }}
  • Hello: World

mw.af.export

edit
ArrayFunctions version
≥ 1.0

This Lua function exports a Lua table as an ArrayFunctions array.

Description

edit 
mw.af.export( table )

Parameters

edit
table : array
The array to export.

Return values

edit

Returns the table as an ArrayFunctions array.

mw.af.import

edit
ArrayFunctions version
≥ 1.6

This Lua function imports an ArrayFunctions array as a Lua table.

Description

edit 
mw.af.import( array )

Parameters

edit
array : array
The array to import.

Return values

edit

Returns the array as a Lua table.

Magic words

edit

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

AF_EMPTY

edit
ArrayFunctions version
≥ 1.0

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.

Description

edit 
{{AF_EMPTY}}

Return values

edit

Returns the empty array.

Changelog

edit

All notable changes to ArrayFunctions will be documented here.

The format is based on Keep a Changelog, and this extension adheres to Semantic Versioning.

unreleased

edit

v1.11.0 - 2024-12-10

edit

Added

edit
  • Add the #af_flatten parser function.
  • Add the #af_wildcard parser function.
  • Add the #af_reverse parser function.
  • Overload #af_get with special indices to perform certain operations on the array instead of retrieving a key.

Changed

edit
  • The #af_unique parser function now compares items normally instead of as strings.

v1.10.0 - 2024-11-26

edit

Added

edit
  • Add ZLIB compression using gzdeflate and gzinflate.

Changed

edit

v1.9.0 - 2024-05-02

edit

Added

edit
  • Add delimiter option to the #af_foreach parser function.

Changed

edit
  • All string parameters now support escape sequences.

v1.8.0 - 2024-04-04

edit

Changed

edit
  • Whitespace is now trimmed from the beginning and the end of array values to be consistent with the behaviour of other parameters in MediaWiki.
  • Localisation updates courtesy of translatewiki.net.

v1.7.0 - 2023-10-24

edit

Added

edit
  • Add the #af_ksort parser function.
  • Add caseinsensitive option to the #af_keysort parser function.
  • Add caseinsensitive option to the #af_sort parser function.

Changed

edit

v1.6.0 - 2023-09-12

edit

Added

edit
  • Add the #af_stringmap parser function.
  • Add the mw.af.import Lua function to import ArrayFunctions arrays into Lua.

Changed

edit

v1.5.0 - 2023-09-07

edit

Added

edit
  • Add the #af_difference parser function.

Changed

edit

v1.4.4 - 2023-06-30

edit

Changed

edit

Fixed

edit
  • Fix #af_template parser function to no longer check a user their read permissions explicitly, as regular template transclusion also does not do this. Previously, an error would be outputted.

v1.4.3 - 2023-05-26

edit

Changed

edit
  • Exporting a NULL value (e.g. through the mw.af.export Lua function) will now result in the empty string. Previously, the NULL would be returned unaltered.

v1.4.2 - 2023-05-26

edit

Changed

edit
  • The #af_template parser function now shows non-existent templates as a broken link. Previously, an error would be outputted.
  • Localisation updates courtesy of translatewiki.net.

v1.4.1 - 2023-05-05

edit

Changed

edit
  • The #af_split parser function now allows the empty string as its first parameter. Previously, an error would be outputted.
  • Localisation updates courtesy of translatewiki.net.

v1.4.0 - 2023-04-26

edit

Added

edit
  • Add the #af_show parser function.

v1.3.0 - 2023-03-27

edit

Added

edit
  • Add the #af_search parser function.

v1.2.0 - 2023-03-03

edit

Added

edit
  • Add the #af_intersect parser function.
  • Add the #af_merge parser function.
  • Add the #af_reduce parser function.

v1.1.0 - 2023-02-03

edit

Added

edit
  • Add the #af_split parser function.

v1.0.1 - 2023-01-09

edit

Changed

edit
  • The mw.af.export Lua function now supports parameters of all types. Previously, it only supported arrays.

Fixed

edit
  • Fix issue where an exception was thrown when a parameter with an incorrect type was passed to mw.af.export.

v1.0.0 - 2023-01-07

edit

Added

edit
  • Add the #af_bool parser function.
  • Add the #af_count parser function.
  • Add the #af_exists parser function.
  • Add the #af_float parser function.
  • Add the #af_foreach parser function.
  • Add the #af_get parser function.
  • Add the #af_if parser function.
  • Add the #af_int parser function.
  • Add the #af_isarray parser function.
  • Add the #af_join parser function.
  • Add the #af_keysort parser function.
  • Add the #af_list parser function.
  • Add the #af_map parser function.
  • Add the #af_object parser function.
  • Add the #af_print parser function.
  • Add the #af_push parser function.
  • Add the #af_set parser function.
  • Add the #af_slice parser function.
  • Add the #af_sort parser function.
  • Add the #af_template parser function.
  • Add the #af_unique parser function.
  • Add the #af_unset parser function.

See also

edit
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:ArrayFunctions&oldid=6897762"