Extension:ArrayExtension

From MediaWiki.org

Manual on MediaWiki Extensions
List of MediaWiki Extensions

ArrayExtension Release status: beta
Implementation	Parser functions
Description	Enhances parser with array functions.
Author(s)	Li Ding and Jie Bao
Last Version	1.2.2 (16 July 2009)
MediaWiki	1.13+
License	MIT License
Download	Subversion [Help] Browse source code
Example	examples
check usage (experimental)

ArrayExtension defines an additional set of parser functions that operate on arrays.

[edit] Functions

This module defines these functions:

[edit] arraydefine

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}}

Note(s):

• '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 (i) a string (the white-spaces surrounding delimiter will be trimmed) or (ii) a perl regular expression (for advanced user only), 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). new

Example(s):

{{#arraydefine:a|red}}

{{#arraydefine:b|orange,red ,yellow, yellow}}

{{#arraydefine:c}}

{{#arraydefine:d|apple, pear}}

{{#arraydefine:e|apple, pear|;}}

{{#arraydefine:f|apple, pear;  orange|/\s*[;,]\s*/}}

{{#arraydefine:b|orange,red ,yellow, yellow|,|unique,sort=desc, print=list}}

[edit] arrayprint

This function prints the values of an array in customizable format. For each value in the array, print 'subject' where all occurrences of 'search' is replaced with the value, deliminated by 'delimiter'

Syntax:

{{#arrayprint:key|delimiter|pattern|subject}}

Note(s):

• 'subject' now accept wiki link, templates and parser functions. new

Example(s):

{{#arrayprint:b}}

{{#arrayprint:b|}}

{{#arrayprint:b|<br/>}}

{{#arrayprint:b|<br/>|@@@@|[[@@@@]]}}

{{#arrayprint:b|<br/>|@@@@|[[prop1::@@@@]]}}

{{#arrayprint:b|<br/>|@@@@|length of @@@@:{{#len:@@@@}}}}

{{#arrayprint:b|<br/>|@@@@|{{f.tag{{f.print.vbar}}prop2{{f.print.vbar}}@@@@}}}}

[edit] arraysize

This function returns the size (number of elements) of an array. See: http://www.php.net/manual/en/function.count.php

Syntax:

{{#arraysize:key}}

Example(s):

{{#arraysize:b}}

[edit] arraysearch

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 '-1' when failed. when 'yes' and 'no' specified, print value of yes if found, and value of no otherwise. See: http://www.php.net/manual/en/function.array-search.php

Syntax:

{{#arraysearch:key|value|index|yes|no}}

Example(s):

{{#arraysearch:b|white}}
{{#arraysearch:b|red}}

{{#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}}

[edit] arrayindex

This function print the value of an array (identified by 'key') at position 'index'.

Syntax:

{{#arrayindex:key|index|options}}

Note(s):

• 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.
• users can specify options on default value

Example(s):

{{#arrayindex:b|2}}

{{#arrayindex:b|-2|default=bad value}}

[edit] arraysort

This function sorts an array in the following order.

• none (default) - no sort
• desc - in descending order (see: http://www.php.net/manual/en/function.sort.php)
• asce/asc - in ascending order (see: http://www.php.net/manual/en/function.rsort.php)
• random - in random order (see: http://www.php.net/manual/en/function.array-rand.php)
• reverse - in reverse order (see: http://www.php.net/manual/en/function.array-reverse.php)

Syntax:

{{#arraysort:key|order}}

Note(s):

• each array element is a string

Example(s):

{{#arraysort:x|desc}}

{{#arraysort:x|random}}

{{#arraysort:x|reverse}}

[edit] arrayunique

This function converts an array (identified by 'key') into a set (no duplicated members, no empty element). see: http://www.php.net/manual/en/function.array-unique.php

Syntax:

{{#arrayunique:key}}

Example(s):

{{#arrayunique:b}}

[edit] arrayreset

This function free-up some or all defined arrays.

Syntax:

{{#arrayreset:}}
{{#arrayreset:key1,key2,...keyn}}

[edit] arraymerge

This function merges values of two arrayes (identified by 'key1' and 'key2') into a new array (identified by 'new_key'). See: http://www.php.net/manual/en/function.array-merge.php Note: a wrong parameter will terminate this operation, and the array identified by 'new_key' will not be affected.

Syntax:

{{#arraymerge:new_key|key1|key2}}

Note(s):

• this merge is different from array_merge offered by PHP because it merges values instead of keys

Example(s):

{{#arraymerge:x|a|b}}

{{#arraymerge:x|b}}

[edit] arrayslice

This function extract a sub-array from an array (identified by 'key') into a new array (identified by 'new_key'). See: http://www.php.net/manual/en/function.array-slice.php

Syntax:

{{#arrayslice:new_key|key|offset|length}}

Note(s):

• offset indicates starting point of slice, it can be (i) non-negative number (ii) 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

Example(s):

{{#arrayslice:x|b|1|2}}

{{#arraymerge:x|b|-2|2}}

[edit] arrayintersect

This function computes the set theoretic intersection of two given arrays (identified by 'key1' and 'key2'), and the result array is identified by 'new_key'. See: http://www.php.net/manual/en/function.array-intersect.php

Syntax:

{{#arrayintersect:new_key|key1|key2}}

Note(s):

• this is a set operator, i.e., the returned array is a set without duplicated values.

Example(s):

{{#arrayintersect:x|a|b}}

[edit] arrayunion

This function computes the set theoretic union of two given arrays (identified by 'key1' and 'key2'), and the result array is identified by 'new_key'. See: http://www.php.net/manual/en/function.array-union.php

Syntax:

{{#arrayunion:new_key|key1|key2}}

Note(s):

• this is a set operator, i.e., the returned array is a set without duplicated values.
• similar to arraymerge, this union operation works on values.

Example(s):

{{#arrayunion:x|a|b}}

[edit] arraydiff

This function computes the (set theoretic) difference of two given arrays (identified by 'key1' and 'key2'), and the result array is identified by 'new_key'. The returned array (identified by 'key') is a set that contains elements in an array (identified by 'key1') but not in the other array (identified by 'key2'). See: http://www.php.net/manual/en/function.array-diff.php

Syntax:

{{#arraydiff:new_key|key1|key2}}

Note(s):

• 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

Example(s):

{{#arraydiff:x|b|a}}

{{#arraydiff:x|a|b}}

[edit] Installation

This extension has been tested on MediaWiki 1.13+ and PHP 5. But most of its functions are compatible with PHP 4, so it is reasonable to try this extension on earlier versions of MediaWiki. Please use the following instructions to install this extension.

1. Install source code

• you can copy the source code from SVN, and put them under "WIKI-PATH/extentions/ArrayExtension"
• or if you have shell access, you can install using svn

 svn co http://smwbp.googlecode.com/svn/trunk/mediawiki/extensions/ArrayExtension/

2. Append the following to LocalSettings.php (near the bottom) of your MediaWiki installation:

require_once ("$IP/extensions/ArrayExtension/ArrayExtension.php");

[edit] FAQ

[edit] work with Extension:SemanticMediaWiki

ArrayExtension allows users to populate an array using a SMW query result.

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. n-ary 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}}|;}}

Note(s)

• 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 cut of the page column

[edit] work with Extension:DynamicPageList

In a similar way as described above for SMW the ArrayExtension can be used to store results of a DPL query.

In the Example we show how 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.

[edit] iteratively access array elements

We can iteratively access elements of an array using #arrayprint with the following code:

<!--define an array-->
{{#arraydefine:colors|Red,Blue,Yellow}}

{{#arrayprint:colors||@@@@|<nowiki/>
* length of @@@@: {{#len:@@@@}}
}}

below is the expected output:

for live examples, follow this URL

[edit] work with Extension:SemanticQueryFormTool

ArrayExtension allows users to populate an array using a SemanticQueryFormTool query result.

to create a list of instances of the class 'Color'

{{#arraydefine: colors|{{#sask: ?Color | format=list | lastsep=}} }}

to deal with 2D array generated by SWM query (e.g. n-ary property)

given a 2D array "red;#da2021, yellow;#fcff00, green;#00ff00"

1. create an array 'colornames'
{{#arraydefine: colornames|{{#sask: ?Color | nary=1 | format=list | lastsep=}} }}

2. create an array 'colorcodes'
{{#arraydefine: colorcodes|{{#sask: ?Color | nary=2 | format=list | lastsep=}} }}

this can be combined with filtering

3. create an array 'none_red_colornames' but leave out any color containing 'red'
{{#arraydefine: none_red_colornames|{{#sask: ?Color | nary=1 | format=list | lastsep= | filter=!strpos:::red}} }}

source: thanks for zehetner@molgen.mpg.de

[edit] related MediaWiki extensions

• ParserFunctions
• VariablesExtension
• StringFunctions

[edit] Change Log

the latest ArrayExtension has been tested on MediaWiki versions 1.13.x. and 1.14

History:

• July 16, 2009 version 1.2.2

   - update arrayunique,  fixed bug (zero mistakenly eliminated in array after arrayunique)
   - rename key=>arrayid, should not affect any existing users
   - rename validate_array_by_name to validate_array_by_arrayid
   - add "asc" as option of arraysort

• May 03, 2009 version 1.2.1

  - update arraydefine by adding options:  "unique";  sort= ( "desc","asce", "random","reverse"), and print= ("list").   options are diliminated by comma, e.g. "unique, sort=desc,print=list". 
  - fixed bug in arrayslice (offset can be greater than array size): 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
  - update arrayindex by adding print option when (i) the array is not defined; (ii) the index is not valid in the specified array: e.g. "default=bad array"

• April 24, 2009 version 1.2

  - fixed a bug in  arrayslice,   (offset=0)
  - clean up code, added two private functions, validate_array_index, validate_array_offset, validate_array_by_name; 
    rename some parameters key=> new_key,  differentiate offset and index

• April 18, 2009 version 1.1.6

  - fixed a bug in arraymerge and arrayslice 

• Mar 17, 2009 version 1.1.5

  - update #arraysort, add "reverse" option, http://www.php.net/manual/en/function.array-reverse.php
  - update #arrayreset, add option to reset a selection of arrays

• Feb 23, 2009 version 1.1.4

  - fixed #arraysearch, better recognize perl patterns identified by starting with "/", http://www.perl.com/doc/manual/html/pod/perlre.html

• Feb 23, 2009 version 1.1.3

  - fixed #arraysearch, "Warning: Missing argument 4..."

• Feb 09, 2009 -- v1.1.2

   - update #arraysearch, now support offset and preg regular expression

• Feb 08, 2009 -- v1.1.1

   - updated #arraydefine with better support to foreach. now users can embed wiki templates, parser functions.
   - update #arraysearch, now allows customized output upon found/non-found by specifying additional parameters

• Feb 05, 2009 -- v1.1

   - update #arraydefine: replacing  'explode' by 'preg_split', 
          and we now allow delimitors to  be (i) a string; or (ii) a perl regular expressnion pattern, sourrounded by '/', e.g. '/..blah.../'
   - update #arrayprint, change parameters from "prefix","suffix" to a "template", 
          and users can replace a substring in the template with array value, similar to arraymap in semantic forms
   - update #arrayunique,  empty elements will be removed
   - update #arraysort: adding "random" option to make the array of values in random order
   - add #arrayreset to free all defined arrays for memory saving
   - add #arrayslice to return an array bounded by start_index and length.
   - add  #arraysearch. now we can return the index of the first occurence of an element, return -1 if not found
   - remove #arraymember,  obsoleted by #arraysearch
   - remove #arraypush, obsoleted by #arraydefine and #arraymerge
   - remove #arraypop, obsoleted by  #arrayslice    
   - add safty check code to avoid unset parameters

• Feb 01, 2009 -- v1.0.3 -- fixed bug on arrayunique, array_unique (PHP function) only makes values unique but does not update array index. (arraydefine is also affected)
• Jan 28, 2009 -- v1.0.2 -- fix #arraypop to support pop multiple elements; add #arrayindex
• Jan 27, 2009 -- v1.0.1 -- fix #arraydefine to support defining an empty string
• Jan 27, 2009 -- v1.0 -- First release(alpha).