Einsatz:
Script zur Generierung einer PHPDOC basierten Funktionsreferenz für alle geladenen Module und interne Funktionen von IP-Symcon
Download:
Script (IPSfunktionsliste.phps)
Funktion:
IPS bietet in seinem internen Editor die Möglichkeit, mittels "CTRL-SPACE" eine Auflistung der enthaltenen Funktionen zur Auswahl zu bekommen. Anschliessend werden über Tooltips die Parameter eingeblendet. Dieser Editor bietet aber ansonsten nur einen begrenzten Komfort und jeder Entwickler
bevorzugt sowieso seinen persönlichen Lieblingseditor. Dort fehlt dann aber wieder die Möglichkeit die Funktionsreferenz zu erhalten.
Zudem ist die offizielle IP-Symcon Dokumentation stellenweise lückenhaft, so das der Wunsch entstand, eine selbstgenerierende Functionsreferenz zu erstellen.
Für PHP hat sich mit dem PHPDocumentor (PHPDOC) ein "Quasistandard" für Inline-Dokumentation entwickelt.
Mein Script verwendet eine interne IPS-Funktion zur Generierung eines PHP-Scriptes mit den Funktionsprotypen und legt sie,
zusammen mit den enthaltenen Zusatzinformationen als PHPDOC-Blöcke, in dieser Datei ab. Diese Datei kann jetzt von PHPDOC analysiert und in eine der vielen Ausgabeformate gewandelt
und außerdem im Lieblingseditor als Funktionsreferenz geladen werden.
Der Editor muss Syntaxhighlighting und Intellitipps auf Sourcecode-Basis unterstützen, wie z.B. Ultraedit, oder es müssen die entsprechenden Wortlisten aus der Datei extrahiert werden.
Installation
In der IPS-Konsole muss ein neues Script mit dem Inhalt von IPSfunktionsliste.phps angelegt und gestartet werden. Im IPS Hauptverzeichnis wird dadurch eine neue Datei mit dem Namen "ipsfunctions.php" erzeugt, eine evtl. existierende Datei wird überschrieben. Diese Datei kann dann mit Hilfe PHPDocumentor in verschiedene Formate (HTML,CHM,PDF usw.) erzeugt werden. Für die Konfiguration des PHPDocumentors verweise ich auf dessen eigene Dokumentation, ein Quickstart-Dokument befindet sich hier.
Ergebnis: (Stand:10.10.2010 IPS V2.3 #1707 mit eigenen Modulen)
Sourcecode IPSfunktionsliste.php
<?php /** * IPS Functionslister * Exportiert alle IP-Symcon Funktionen mit einer Parameterliste * basiert auf IP-Symcon Dokumentation * (http://www.ip-symcon.de/service/dokumentation/befehlsreferenz/programminformationen/ips-getfunctionlist/) * * @package IPS * @subpackage AllFunctions * @copyright (C) Thomas Dreßler * @version V0.2 08.10.2010 */ $instanceid = 0; //0 = Alle Funktionen, sonst Filter auf InstanzID $fs = IPS_GetFunctionList($instanceid); asort($fs); $typestr = Array("boolean", "integer", "float", "string", "variant", "array"); $logfile="../ipsfunctions.php"; $log=fopen($logfile,"w"); $header=' /** * IPS Functionsliste * @author www.ipsymcon.de * @package IPS * @subpackage AllFunctions */ '; if ($log) { fwrite ($log,"<?php\r\n"); fwrite ($log,$header."\r\n"); foreach($fs as $f) { fwrite ($log,"\r\n/**\r\n"); fwrite ($log,"* ".$f['FunctionName']."\r\n"); fwrite ($log,"* \r\n"); fwrite ($log,"* @returns ".$typestr[$f['Result']['Type_']]. "\r\n"); $proto="function ".$f['FunctionName']."( "; $a = Array(); foreach($f['Parameters'] as $p) { $enum=null; if(isset($p['Enumeration']) && sizeof($p['Enumeration']) > 0) { $b=Array(); foreach($p['Enumeration'] as $k => $v) { $b[] = $k."=".$v; } $type = "integer"; $enum= "enum[".implode(", ", $b)."]"; } else { $type = $typestr[$p['Type_']]; } $pname=$p['Description']; $pname=preg_replace("/[\(\)]+/","",$pname); $proto.="$".$pname.","; fwrite ($log,"* @param ". $type. ' $'.$pname. "\r\n"); if ($enum) fwrite ($log,"* ".$enum."\r\n"); } fwrite ($log,"*/\r\n\r\n"); $proto=substr($proto,0,strlen($proto)-1); $proto.=" ) {\r\n\r\n}\r\n"; fwrite ($log,$proto); } fwrite ($log, "?>\r\n"); fflush($log); fclose($log); } $all=file_get_contents($logfile); echo htmlentities($all); ?>