Extension:HashTables
This extension is currently not actively maintained! Although it may still work, any bug reports or feature requests will more than likely be ignored. If you are interested in taking on the task of developing and maintaining this extension, you can request repository ownership. As a courtesy, you may want to contact the author. You should also remove this template and list yourself as maintaining the extension in the page's {{Extension }} infobox. |
HashTables Release status: unmaintained |
|
---|---|
Implementation | Parser function |
Description | Enhances the parser with hash table functions and a function to store all parameters given to a template. |
Author(s) | Daniel Werner (Danwetalk) |
Latest version | 1.2.0 (2017-07-17) |
MediaWiki | 1.23+ |
Database changes | No |
License | ISC License |
Download | README RELEASE-NOTES |
Quarterly downloads | 1 (Ranked 136th) |
Translate the HashTables extension if it is available at translatewiki.net | |
The HashTables extension provides several new parser functions for creating and operating on hash tables. Hash tables are very similar to arrays which can be used with Extension:Arrays. HashTables features the function parameterstohash which can store all parameters given to a template and then use those parameters in other templates because all of the hash tables are global.
Functions
editThis module defines the following functions:
group | functions |
---|---|
construct a hash table | #hashdefine , #parameterstohash
|
print hash table | #hashprint , #hashvalue , #hashsize , #hashkeyexists
|
alter a hash table | #hashreset , #hashinclude , #hashexclude
|
interaction between multiple hash tables | #hashmerge , #hashmix , #hashdiff , #hashintersect
|
interaction between arrays and hash tables | #hashtoarray , #arraytohash
|
Construction
edithashdefine
editThis 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:
{{#hashdefine:hashID |values |itemsDelimiter |innerDelimiter}}
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 of course can be empty strings as well.
- If values is set but an empty string, one might expect this would create a hash table with one empty key. Actually, this is not the case out of compatibility reasons and for allowing something like
{{#hashdefine:a|{{{a|}}} }}{{#ifexpr:{{#hashsize:a}} > 0|...}}
. You can create an empty key with#hashinsert
or{{#hashdefine:a| ; }}
though.
parameterstohash
editThis 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:
{{#parameterstohash:hashID}}
This can for example be useful if you wish to define a generic template which should be configurable by other templates which should be aware of the parameters given to the main template.
Output
edithashprint
editThis 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:
{{#hashprint:hashID |delimiter |keyPattern |valuePattern |subject |orderByArray}}
Example:
{{#hashprint:hashID |<br/> |%%%% |@@@@ |'''%%%%:''' @@@@}}
Advanced: The parameter orderByArray allows to specify a name of an existing array (created with Extension:Arrays). 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:
{{#hashinclude:hashID |mr1=Tom |mr2=Dan |mr3=Ken |clown=Felix |director=Eric |chef=Helen}} {{#arraydefine:arrOrder |chef, mr2, mr1, clown, director}} {{#hashprint:hashID |, | |@@@@ |@@@@ |arrOrder}}
hashvalue
editThis 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:
{{#hashvalue:hashID |itemKey |default}}
hashsize
editThis 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 0
.
Syntax:
{{#hashsize:hashID}}
hashkeyexists
editThis function returns 1
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:
{{#hashkeyexists:hashID |key |yes |no}}
Alteration
edithashinclude
editThis function will add new hash table keys and values to a hash table identified by hashID.
Syntax:
{{#hashinclude:hashID |key1=val1 |key2=val2 |... |key n=val n}}
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
editThis function will remove keys and their associated values from a hash table identified by hashID.
Syntax:
{{#hashexclude:hashID |key1 |key2 |... |key n}}
hashreset
editThis function delets all or some defined hash tables. This is good to free up some memory when a hash table is obsolete.
Syntax:
{{#hashreset:}} {{#hashreset:table 1 |table 2 |... |table n}}
Note: The syntax of this function is different from the Arrays extension arrayreset function.
Interaction between hash tables
edithashmerge
editThis 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. If only one hash is given, this will just re-assign its numeric keys.
Syntax:
{{#hashmerge:hashID |hash1 |hash2 |... |hash n}}
Details: https://php.net/function.array-merge
hashmix
editThis 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:
{{#hashmix:hashID |hash1 |hash2 |... |hash n}}
hashdiff
editThis 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:
{{#hashdiff:hashID |hash1 |hash2 |... |hash n}}
Details: https://php.net/function.array-diff-key
hashintersect
editThis 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:
{{#hashintersect:hashID |hash1 |hash2 |... |hash n}}
Details: https://php.net/function.array-intersect-key
Interaction with Arrays extension
edithashtoarray
editCreate 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:
{{#hashtoarray:valArrayID |hashID |keyArrayID}}
Notes:
- This function is only available when the extension Arrays is activated in the wiki.
- In case 'valArrayID and keyArrayID are the same, the array will contain the names of the keys only.
arraytohash
editCreate a 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:
{{#arraytohash:hashID |arrayID |keyArrayID}}
Notes:
- This function is only available when the extension Arrays 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.
Experimental
edithashtotemplate
editCall a 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:
{{#hashtotemplate:template |hashID |pipeRelace}}
Notes:
{
,|
and}
within hash values and keys will be replaced with{
,|
and}
. This is preventing irritation of the template call.- To prevent further problems you can also define an alternative string for the pipe
|
replacement with the third parameter. E.g. you have Template:!, Template:(( and Template:)) for!
,{{
and}}
, you can call{{#hashtotemplate:template |hashID | {{((}}!{{))}} }}
and passing links for example shouldn't be much of a problem anymore.
Installation
edit- Download and move the extracted
HashTables
folder to yourextensions/
directory.
Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/HashTables - Add the following code at the bottom of your LocalSettings.php file:
require_once "$IP/extensions/HashTables/HashTables.php";
- Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Important Notes
editWhen using hash tables realize that:
- 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
{{Z}}
without any parameters and the template is using hash tables which should change on every call of the template, this probably 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{{Z|}}
(void parameter 1) and the cache will be disabled.
Change Log
editThe full version history can be found within the RELEASE-NOTES.
See also
edit- Extension:PhpTags Functions/Functions/Array, includes more than fifty functions for working with arrays using the PHP syntax.