Benutzer:Rene/CacheArray

Beschreibung

Die Parser-Erweiterung CacheArray ermöglicht das anlegen und auslesen von Arrays. Das besondere dabei ist das diese Arrays nur einmal angelegt werden müssen und dann auch von anderen Seiten benutzt werden können. Hinweis: Natürlich bleibt das Array nicht erhalten wenn die ursprünglich angefragte Seite an den Browser ausgegeben wurde. Es kann nur während des Seitenaufbaus von aufgerufenen Seiten bzw. Vorlagen benutzt werden.

Befehle

Die Erweiterung bietet neben dem eigentlichen Array Befehl (carray) noch einige weitere Befehle die bei der Benutzung der Erweiterung hilfreich sind.

• carray

Der Befehl zum setzen, auslesen und löschen der Arrays

• trim

Leerzeichen am Anfang und Ende einer Variable entfernen

• keys

Mehrere Index-Keys zu einem einzigen Verbinden

carray

{{carray:<Name_des_Array>|<Kommando>[''Parameter''…''Array-Werte'']}}

• Name_des_Array

Die Erweiterung ist in der Lage beliebig viele Arrays zu verwalten. Zur Unterscheidung dient dabei der Array-Name.

• Kommando

Die Steuerung von carray erfolgt über die folgenden Kommandos.

• w oder write

Das Kommando write füllt das Array mit den angegebenen Werten. Ist das Array bereits angelegt wird der Befehl ignoriert. Um ein Array erneut anzulegen muss es zuerst gelöscht werden, siehe Befehl delete.

Die Definition der Array-Werte erfolgt analog zur {{#switch:}} Definition. Ein Beispiel:

{{carray:EpName|w
| #default = <span class="error">Episodencode ungültig</span>
| SGA_1x01/02 = Aufbruch in eine neue Welt
| SGA_1x01 = Aufbruch in eine neue Welt, Teil 1
| SGA_1x02 = Aufbruch in eine neue Welt, Teil 2
| SGA_1x03 = Dunkle Schatten
| SGA_1x04 = 38 Minuten
}}

Das Array-Element #default wird immer dann ausgegeben wenn die Anfrage nach einem nicht definierten Wert gestellt wird, siehe Befehl read.

• r oder read

Mit dem Kommando read erfolgt die Abfrage des Arrays. Das folgende Beispiel

{{carray:EpName|r|SGA_1x01}}

würde nach der oben angegebenen Definition den Wert

Aufbruch in eine neue Welt, Teil 1

zurück liefern. Ist kein Wert definiert wird entweder nichts oder, wenn definiert, der Inhalt der Zeile #default ausgegeben.

• rw oder readwrite

Mit der Kombination der Kommandos read und write wird das Array zuerst gefüllt und dann die entsprechende Zelle ausgelesen. Der Aufruf muss daher lauten:

{{carray:EpName|rw|SGA_1x01
| #default = <span class="error">Episodencode ungültig</span>
| SGA_1x01/02 = Aufbruch in eine neue Welt
| SGA_1x01 = Aufbruch in eine neue Welt, Teil 1
| SGA_1x02 = Aufbruch in eine neue Welt, Teil 2
| SGA_1x03 = Dunkle Schatten
| SGA_1x04 = 38 Minuten
}}

• f oder file - Ab Version 0.7 verfügbar -

Das Kommando entspricht write und erzeugt ebenfalls ein Array. Der Unterschied ist das die Daten aus einer anderen Seite gelesen werden. Es wird vor dem erzeugen geprüft ob das Array schon vorhanden ist und nur wenn dies nicht der Fall ist wird die Datei geladen. Siehe auch #Hinweise zum Einsatz.

{{carray|EpName|f|Vorlage:EpName/Fill}}

• fr oder fileread - Ab Version 0.7 verfügbar -

Das Kommando ist eine Kombination aus file und read

{{carray|EpName|fr|Vorlage:EpName/Fill|SG1_1x10}}

• u oder used

Um zu prüfen ob ein Array bereits angelegt ist sollte das Kommando used benutzt werden. Ist das Array bereits vorhanden liefert die Anfrage die Anzahl der definierten Array-Elemente, ansonsten wird nichts zurück geliefert.

{{carray:EpName|u}}

• c oder count

Das Kommando gibt die Anzahl der definierten Array-Elemente zurück. Ist das Array noch nicht definiert ist das Ergebnis 0.

{{carray:EpName|c}}

• d oder delete

Mit dem Kommando delete wird das Array gelöscht. Dies ist immer dann nötig wenn das Array neu geschrieben werden soll, da das Überschreiben nicht möglich ist.

{{carray:EpName|d}}

trim

{{trim|<Parameter>}}}

• Parameter

Der Parameter kann ein Text oder sinnvoller eine Variable sein.

Als Rückgabe erhält man den angegebenen Wert ohne führende oder nachfolgende Leerzeichen. Der Einsatz der Funktion ist bei der Übergabe des Arraykeys sinnvoll da es vorkommen kann das der Wert einer Variablen ein führendes Leerzeichen enthält.

keys

{{keys:[<Mod>:]<Key>[|[<Mod>:]<Key>…]}}

• Key

Der Key ist entweder direkt ein Text oder eine Variable. Vor dem Key kann ein Modifierer (Mod) angegeben werden.

• Mod

Mit dem Modifier kann der Key verändert werden. Definiert sind die Modifier l zum umwandeln des Keys in Kleinbuchstaben und u zum umwandeln in Großbuchstaben.

Das Kommando wandelt die Keys entsprechend der Modifier um, entfernt Leerzeichen und fügt zwischen den einzelnen Keys einen Unterstrich _ ein. Das Ergebnis wird dann zurückgeliefert.

{{keys:u: sg1 | 1x01 }}

Ergibt: SG1_1x01 Hinweis Damit nicht definierte Variablen als soclhe auch erkannt werden müssen diese nach dem folgenden Muster eingesetzt werden. Nicht {{{1}}} sondern {{{1|}}}.

Hinweise zum Einsatz

Die Erweiterung kann, richtig eingesetzt, den Aufbau von Seiten beschleunigen die häufig eine Vorlage aufrufen die aus einer großen Anzahl an Werten einen Wert liefert. Dazu sollte eine eigene Seite angelegt werden die nur das Array füllt. Auf der eigentlichen Vorlagenseite sollte mit dem Befehl used geprüft werden ob das Array bereits gesetzt wurde. Wenn nicht kann die "Full"-Vorlage aufgerufen werden. Sonst sollte immer nur das Array ausgelesen werden.

Durch diese Konstruktion erreicht man das die große, daher langsame, 'Füll'-Vorlage nur einmal abgearbeitet werden muss und alle weiteren Zugriffe auf das Cache-Array erfolgen.

Die entsprechende Anweisung sollte wie folgt aussehen, definiert in Vorlage:EpName

{{#if: {{carray:EpName|u}} || {{EpName/Fill}} }}{{carray:EpName|r|{{{1}}}}}

Die Vorlage EpName/Fill füllt das Array EpName mit Werten die dann von der Vorlage EpName ausgelesen wird.

Code

<?php
if(!defined('MEDIAWIKI')) {
    die('This filse is a MediaWIki extension, it is not a valid entry point');
}
// About
$wgExtensionCredits['parserhook'][] = array(
    'name' => 'CacheArray',
    'version' => '0.6.0',
    'url' => 'http://www.stargate-wiki.de/index.php/Benutzer:Rene/CacheArray',
    'author' => 'René Raule',
    'description' => 'Cached Array for templates',
);
// Define a setup function
$wgExtensionFunctions[] = 'efCacheArray_Setup';
// Add a hook to initialise the magic word
$wgHooks['LanguageGetMagic'][]       = 'efCacheArray_Magic';
// Cache
$efCacheArray_cache = array();

// Register extension 
function efCacheArray_Setup() {
    global $wgParser;

    $wgParser->setFunctionHook( 'carray', 'efCacheArray_carray', SFH_NO_HASH );
    $wgParser->setFunctionHook( 'trim'  , 'efCacheArray_trim'  , SFH_NO_HASH );
    $wgParser->setFunctionHook( 'keys'  , 'efCacheArray_keys'  , SFH_NO_HASH );
}

// Define magic word(s) 
function efCacheArray_Magic( &$magicWords, $langCode ) {
    $magicWords['carray'] = array( 0, 'carray' );
    $magicWords['trim']   = array( 0, 'trim' );
    $magicWords['keys']   = array( 0, 'keys' );
    return true;
}

// trim
function efCacheArray_trim( &$parser, $inStr='') {
    return array(trim($inStr),'noparse'=>true);    
}

// combinate keys 
function efCacheArray_keys() {
    // get the parser parameter 
    $param = func_get_args();
    $parser = current($param);
    // get the parts for the key 
    $key = '';
    while($value = next($param)) {
        // get key-parameter(s) p:key
        list($mod,$value) = explode(':',$value,2);
        // if modifier (mod) is given (then value is set)
        if(isset($value)) {
            if(strpos($mod,'u')!==false) {
                $value = strtoupper($value);
            }
            if(strpos($mod,'l')!==false) {
                $value = strtolower($value);
            }
        } else {
            $value = $mod;
        }
        $value = trim($value);
        if(!empty($value)) {
            if(!empty($key)) {
                $key .= '_';
            }
            $key .= $value;
        }
    }
    return $key;
}

// carray main part
function efCacheArray_carray() {
    global $efCacheArray_cache;

    // minimum parser, cachenumber and action are needed    
    if(func_num_args() < 3) {
	return array('','noparse'=>true);
    }
    // get the parser parameter 
    $param = func_get_args();
    $parser = current($param);
    // get the first two wiki-parameters (chachenumber, action) 
    $cnumber = trim(next($param));
    $action = strtolower(trim(next($param)));
    // default output is empty
    $output = '';
    // action
    switch($action) {
    case 'w' :  // only create new carray
    case 'write' :
    case 'rw' :	// write new carray and read one value
    case 'readwrite' :
	// read key (only if readwrite)
	if(($action == 'rw') or ($action == 'readwrite')) {
	    $key = trim(next($param));
	}
	// if carray is already set do not read it again (cache!)
	if(!isset($efCacheArray_cache[$cnumber])) {
	    // read the keys and values and save in carray
	    while($values = next($param)) {
	        list($index,$value) = explode('=',$values,2);
	        $efCacheArray_cache[$cnumber][trim($index)] = trim($value);
	    }
	}
	// leave switch (only if write)
	if(($action == 'w') or ($action == 'write')) {
	    break;
	}
    case 'r' :	// read value out of carray
    case 'read' :
	// read key, if not already set by action readwrite
	if(!isset($key)) {
	    $key = trim(next($param));
	}
	// read cache
	$value = $efCacheArray_cache[$cnumber][$key];
	// if no value, look for default
	if(isset($value)) {
	    $output = $value;
	} else {
	    if(isset($efCacheArray_cache[$cnumber]['#default'])) {
		$output = $efCacheArray_cache[$cnumber]['#default'];
	    }
	}    
	break;
    // delete carray
    case 'd' : 
    case 'delete' :
	unset($efCacheArray_cache[$cnumber]);
	break;
    case 'c' :	// count elements in carray
    case 'count' :
	$output = count($efCacheArray_cache[$cnumber]);
	break;
    case 'u' :	// test if cache is used
    case 'used' :
	// if carray is used give size 
	if(isset($efCacheArray_cache[$cnumber])) {
	    $output = count($efCacheArray_cache[$cnumber]);
	}
	break;
    }
    return array($output,'noparse'=>true);
}