Extension:HashTables

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manualManual:Extensions
Crystal Clear action run.png
HashTables

Release status:Extension status stable

ImplementationTemplate:Extension#type Parser function
DescriptionTemplate:Extension#description Enhances the parser with hash table functions and a function to store all parameters given to a template.
Author(s)Template:Extension#username Daniel Werner (Danwetalk)
Latest versionTemplate:Extension#version 1.2.0 (2017-07-17)
MediaWikiTemplate:Extension#mediawiki 1.23+
Database changesTemplate:Extension#needs-updatephp No
LicenseTemplate:Extension#license ISC License
Download
README
RELEASE-NOTES
Hooks usedTemplate:Extension#hook
ParserFirstCallInitManual:Hooks/ParserFirstCallInit
ParserClearStateManual:Hooks/ParserClearState

Translate the HashTables extension if it is available at translatewiki.net

Check usage and version matrix.

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[edit]

This 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[edit]

hashdefine[edit]

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:

{{#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[edit]

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:

{{#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[edit]

hashprint[edit]

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:

{{#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[edit]

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:

{{#hashvalue:hashID |itemKey |default}}


hashsize[edit]

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 0.

Syntax:

{{#hashsize:hashID}}


hashkeyexists[edit]

This 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[edit]

hashinclude[edit]

This 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[edit]

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

Syntax:

{{#hashexclude:hashID |key1 |key2 |... |key n}}


hashreset[edit]

This 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[edit]

hashmerge[edit]

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. If only one hash is given, this will just re-assign its numeric keys.

Syntax:

{{#hashmerge:hashID |hash1 |hash2 |... |hash n}}

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


hashmix[edit]

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:

{{#hashmix:hashID |hash1 |hash2 |... |hash n}}


hashdiff[edit]

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:

{{#hashdiff:hashID |hash1 |hash2 |... |hash n}}

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


hashintersect[edit]

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:

{{#hashintersect:hashID |hash1 |hash2 |... |hash n}}

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


Interaction with Arrays extension[edit]

hashtoarray[edit]

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:

{{#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[edit]

Create 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[edit]

hashtotemplate[edit]

Call 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 &#123;, &#124; and &#125;. 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 place the file(s) in a directory called HashTables in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    require_once "$IP/extensions/HashTables/HashTables.php";
    
  • YesY Done - Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Important Notes[edit]

When 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[edit]

The full version history can be found within the RELEASE-NOTES.

See also[edit]

Language:Project:Language policy English  • 日本語