Extension:HashTables

HashTables provides mediawiki with several new parser functions for creating and operating on hash tables. Hash tables are very similar to arrays which can be used via Extension:ArrayExtension. HashTables features the function parameterstohash which allows to store all parameters given to a template and to use those parameters in other templates due to the fact that all hash tables are global.

Functions
This module defines the following functions:

hashdefine
This function defines a new hash table identified by hashID using a list of values separated by a itemsDelimiter (default ). All items of the hash table have an item key to identify a value. This item key and its value must be separated by the innerDelimiter (default ). In case the values parameter is empty a void hash table will be created.

Syntax:

Notes:
 * Hash table items must be unique. In case a item key appears more than once in the values list only the last item will end up in the hash table.
 * A empty string as item key is technically possible. Item values can be empty strings as well.

parameterstohash
This function will create a new hash table identified by hashID. The items will be all the template parameters delivered to the current template which is calling the function.

Syntax:

This can be very useful if you with to define a generic template which should be configurable by other templates which should be aware of the parameters given to the main template.

hashprint
This function prints all the values of a hash table identified by hashID separated by a delimiter. It is possible to control the output by defining a subject where all appearances of a keyPattern for the hash table keys and a valuePattern for their values will be replaced with either the key or the value of the current hash table item.

Syntax:

Example:

Advanced: The parameter orderByArray allows to specify a name of an existing array (created with Extension:ArrayExtension). The items of this array should also be keys inside the hashID hash table. The function will print only the items of hashID specified in the orderByArray array in the exact order of the array items. It is also possible to have one item more than one times in the array to print it multiple times.

Example:

hashvalue
This function prints the hash table item value of a given hash table itemKey. In case the key doesn't exist or the value of the item is a void string the default value will be returned.

Syntax:

hashsize
This function returns the number of items of a hash table identified by hashID. In case the table doesn't exist the function will return a void string. The return value for existing but void hash tables is.

Syntax:

hashkeyexists
This function returns  or yes (if set) when a key key exists within a hash table identified by hashID. In case the key doesn't exist the function will return a void string or the no-value if set.

Syntax:

hashinclude
This function will add new hash table keys and values to a hash table identified by hashID.

Syntax:

This function can also be used as an alternative way to hashdefine in defining a new hash table. If the intention of using this function is to define a new hash table, it should be considered that another hash table with the same name could already exist. In this case the existing table would be extended.

hashexclude
This function will remove keys and their associated values from a hash table identified by hashID.

Syntax:

hashreset
This function delets all or some defined hash tables. This is good to free up some memory when a hash table is obsolete.

Syntax:

Note: The syntax of this function is different from the ArrayExtensions arrayreset function.

hashmerge
This function merges two or more hash tables into a new hash table identified by hashID like the php function array_merge would merge them. All string keys in the first hash table which also appear in the following hash table will be replaced by them. All numeric keys will be added starting from 0 without any replacements.

Syntax:

Details: http://www.php.net/manual/en/function.array-merge.php

hashmix
This function mixes two or more hash tables into a new hash table identified by hashID. For the most part this function works like hashmerge with one exception: Numeric hash table keys will be treated like string keys.

Syntax:

hashdiff
This function compares two or more hash tables like the php function array_diff_key would compare them. All items contained in the first array but in none of the other ones will end up in a new hash identified by hashID.

Syntax:

Details: http://th2.php.net/manual/en/function.array-diff-key.php

hashintersect
This function compares two or more hash tables like the php function array_intersect_key would compare them. Creates a new hash table identified by hashID containing all entries of hash1 which are present in the other hash tables given in parameters 3 to n.

Syntax:

Details: http://th2.php.net/manual/en/function.array-intersect-key.php

hashtoarray
Create an array identified by 'valArrayID from a hash table hashID. All hash table item values will be taken over to the array, the item keys will be lost but the order of the items in the array will be the same as in the hash table. Optionally the function creates a second array identified by keyArrayID which will contain all the key names of the hash table.

Syntax:

Notes:
 * This function is only available when the extension ArrayExtension is activated in the wiki.
 * In case 'valArrayID and keyArrayID are the same, the array will contain the names of the keys only.

arraytohash
Create an hash table identified by hashID from an array arrayID. By default the indexes from the array will be used as hash table item keys in the hash table. It is also possible to name a keyArrayID which should be the name of an array which will deliver the names of the keys for the new hash table.

Syntax:

Notes:
 * This function is only available when the extension ArrayExtension is activated in the wiki.
 * If the arrayID-Array has more entries than the keyArrayID, the entries will be ignored. Has the keyArrayID more entries, the keys will end up in the hash table with void strings as value.

hashtotemplate
Call an template within the wiki and pass parameters and their values from an hash table hashID. The keys of the hash table are the parameter names passed to the template, their values are the parameters values.

Syntax:

Note:  and   within hash values and keys will be replaced agains   and. This is preventing irritation of the template call.

Important Notes
When using hash tables, you should be aware of the following points:
 * Hash tables are always global. If you create a hash table abc in template X the hash table abc will be available in all other templates which are called after this event. Hash tables, Arrays and Variables all have a global scope for their values.
 * When you call a template Z like  without any parameters and the template is using hash tables which should change on every call of the template, this propably won't work. MediaWiki uses a cache for templates called without parameters so the code will be executed only once. MW assumes that those templates are not dynamic. To avoid this cache you can simply call  (void parameter 1) and the cache will be disabled.

Change Log
the latest HashTables extension has been tested on MediaWiki version 1.16

 History: 
 * January 24, 2011 version 0.6.1
 * Constant VERSION and function getHash added to class ExtHashTables.
 * January 19, 2011 version 0.6
 * New public class methods for creating and removing hash tables. Good for use by other extensions.
 * New experimental function hashtotemplate.


 * August 3, 2010 version 0.5.1
 * hashinclude didn't trim key and value so keys with ending space ' ' and values with leading space were possible when defining something like


 * August 1, 2010 -- version 0.5:
 * New parameter for function hashtoarray which allows to specify the name of a second array which will contain the key names.
 * Function arraytohash doesn't mind non existent arrays in parameter 2 anymore. This allows to create an hash table with keys only (empty strings as values).
 * Extension status changed to stable.


 * July 20, 2010 -- version 0.4:
 * Critical bug solved. Some kind of "Superglobal" HashTables on page imports and job queue jobs. Values were passed from one page to another page. Extension:Variables and Extension:ArrayExtension have the same bug. Make sure to update them as well.


 * June 11, 2010 -- version 0.3:
 * Third parameter for arraytohash allows to set a key array.
 * New function hashkeyexists.


 * June 6, 2010 -- version 0.2:
 * New functions hashmerge, hashmix, hashdiff, hashinclude and hashexclude.
 * New functions if Extension:ArrayExtension is available in the wiki: hashtoarray and arraytohash.
 * New parameter for hashprint which allows to define the print order thru an array.


 * May 30, 2010 -- version 0.1: First version of HashTables featuring the functions hashdefine, hashvalue, hashsize, hashprint, hashreset and parameterstohash.