[TF-macros-devel] configure-howto

[Michael H. <mh...@in...>]

Hier kommt ein kleines Howto fuer die Nutzung und Wartung der /configure
Moeglichkeiten von TinyMacros:

Nutzung:
--------
* per /configure wird ein Menue angezeigt, in dem man mit Ziffern Menuepunkte auswaehlen kann

z.B:
-----------------------------------------------------------------------
Konfiguration:  (<RETURN> wechselt hoch, "q" beendet)
1) Generelles     2) Paketauswahl   3) Oberflaeche
4) Mudspezifizisches                5) Hilfe          6) Connection
7) Textumleitung  8) Funktionstastenebenen            9) Statuszeile
10) Wegesystem
Eingabe Menu:
-----------------------------------------------------------------------

* mit "q" wird das Menue verlassen
* mit allem ausser den Ziffern der Menuepunkte wird eine Menueebene hoeher gesprungen und ggf. das /configure verlassen

* die Menues sollen die zu konfigurierenden Informationen etwas strukturieren
* am Ende der Menues stehen Menuepunkte die direkt auf zu konfigurierende Variablen/Variablenmengen oder Listen verweisen.
* sofern ein solcher Menuepunkt ausgewaehlt wird, bekommt man sofern vorhanden eine Hilfe zu der Variablen und den aktuellen Wert als Vorgabe in der Eingabezeile
* bei Variablenmengen und Listen wird wieder eine Menueebene geoeffnet in der die Einzelvariablen bzw. Listenschluessel angezeigt werden, durch Auswahl eines Menuepunktes wird fuer diesen der Wert wie bei einer einzelnen Variablen geaendert
* wenn der Wert nicht geaendert wurde, passiert nix
* wenn ja:
* nach dem Aendern der Variablen wird ein kleiner Korrektheitscheck (fuer Farben und Zahlen) durchgefuehrt
* danach wird geschaut in welches Config-File (user_config.cfg; mud_domain/user_config.cfg oder mud_domain/character/user_config.cfg) die Variable gehoert und in diesem werden dann vorhandene Eintraege ersetzt bzw. wenn noch nicht vorhanden wird der Eintrag angehaengt
* der Rest des Files (z.B. Kommentare bleibt unberuehrt)

das wars eigentlich schon fuer den Endnutzer

Entwickler:
-----------

Die Informationen zur Konfiguration werden beim Laden der Files sukzessive aufgebaut.
Fuer das Konfigurationssystem wurden folgende Aenderungen vorgenommen:
WICHTIG: Ladereihenfolge (spezifischste Config zuerst):
1. user_config.cfg
2. user_config.def
x.1) file.cfg
x.2) file.def
x.3) file.tf
....
mud_domain/user_config.cfg
mud_domain/user_config.def

Damit koennen in den *.cfg Werte gesetzt werden, die dann schon direkt in den *.tf benutzt/beachtet werden koennen.

Deshalb muessen zu konfigurierende Variablen in den *.def, *.tf entweder mit /set_var oder /cfg_set gesetzt werden, dann ueberschreiben sie schon gesetzte Werte nicht.

Die konfigurierten Werte koennen auf vielfaeltige Weise beachtet/benutzt werden:
* Zum einen mit bedingten Kommandos wie:
/ifdef, /ifdo, /ifecho, /cfg_echo,/mload -E,
die jeweils als 1. Parameter einen TF-Ausdruck erwarten und die ihre Funktion nur ausfuehren wenn dieser Ausdruck wahr ist

* Zum anderen direkt als Werte z.B. fuer Texte,Farben,/if Abfragen usw.

Die Information an welcher Stelle im Konfigurationsbaum eine Variable abgelegt wird, soll durch /cfg_info zur Verfuegung gestellt werden.
dabei wird jeweils ein Knoten spezifiziert, der entweder auf ein weiteres Menue zeigt (vorletzter Parameter kleingeschrieben) oder auf einen Knoten der einer Variablen/-menge oder Liste zugeordnet ist.

Bsp:
/cfg_info all  Generelles
/cfg_info use Paketauswahl
/cfg_info gui Oberflaeche
/cfg_info mud  Mudspezifizisches

/cfg_info mud commands Kommandos

/cfg_info mud comm Kommunikation
/cfg_info mud comm EBENEN Ebenenfarben:comm_ebenen_list

/cfg_info gui MORE    More:more
/cfg_info gui HISTSIZE History:histsize
/cfg_info gui COLORS Farbliste
/cfg_info gui VISUAL Visual-Mode:visual

usw.

Der letzte Parameter ist das was im Menue erscheinen soll (Spaces als "_"), durch einen Doppelpunkt abgetrennt kann der Variablenname stehen, sofern er sich nicht aus den Hierarchiebezeichnern (z.b. CFG_GUI_COLORS) ergibt. Ausserdem koennen dort durch Doppelpunkte getrennte Zahlen die Teile der Hierarchie benenenn, die bei der Namensbildung ignoriert werden sollen.
z.B:
/cfg_info status mg tanjian Tanjian:2
-> anderer Varname (CFG_STATUS_TANJIAN, 2==MG faellt weg)

Zum Check (/cfg_check):
Zur Zeit wird nur eine Ueberpruefung auf die Farbnamen und auf Zahlen gemacht. Der Datentyp sollte als dtype (color,attr,number,text) bei der Hilfedefinition der Variablen angegeben werden. Wenn dort nichts gefunden wird, wird nur fuer die Variablen deren Name "color" oder "attr" enthaelt ein Farbencheck gemacht.

Zum Abspeichern (/cfg_save):
wenn in den Hierarchienamen das Word MUD oder der Hostname der aktuellen Welt vorkommen wird es in mud_domain/user_config.cfg (-c) geschrieben.
Wenn zusaetzlich PLAYER oder ${WORLD_CHARACHTER} drin vorkommt dann nach mud_domain/char/user_config.cfg (-c -p)
Wenn nix dann ins user_config.cfg im Hauptverzeichnis der TinyMacros Installation.

Hilfe:
-----------------------------------------------------------------------
Makros: cfg_set
Info: Wenn die ueber die Config-Hierarchie-Namen bestimmte Variable noch nicht
gsetzt ist, wird sie auf den Wert des letzten Parameters gesetzt
Syntax: /cfg_set Config-Hierarchie-Namen Wert
Beispiel: /cfg_set USE LOADING 1
Rueckgabewert: Variablenname
Datei: config.tf
-----------------------------------------------------------------------
Makros: set_var
Info: Setzt die Variable auf den angegeben Wert, falls sie noch nicht gesetzt
war
Syntax: /set_var varname value
Beispiel: /set_var a bac
Datei: util.vfunc.tf
-----------------------------------------------------------------------
Makros: ifdo
Info: Conditional def, nur wenn der Ausdruck, der als 1. Parameter uebergeben
wird 1 ist, wird der rest ausgefuehrt
Syntax: /ifdo expr tf-code
Beispiel: /ifdo !islist(comm_ebenen_list)\
/createlist comm_ebenen_list
/addtolist comm_ebenen_list team Cblue Cyellow
Datei: util.tf
-----------------------------------------------------------------------
Makros: ifdef
Info: Conditional def, nur wenn der Ausdruck, der als 1. Parameter uebergeben
wird 1 ist wird das /def gemacht
Syntax: /ifdef expr normal def parameters
Beispiel: /ifdef is_file_loaded("status.tf") sl_lp = /initvar p_lp%; ....
/ifdef p_guild=~"zauberer" -t"bla Hand Eis" zaubi_hand_eis = ....
Datei: util.tf
-----------------------------------------------------------------------
Makros: cfg_echo
Info: ein Echo Makro, dass schaut, ob fuer den uebergebenen Makronamen eine
Config von Farbe und/oder Text existiert. Wenn ja gibt es die Config aus,
ansonsten den Originaltext.
Die Variablen heissen: CFG_ECHO_*_TEXT und CFG_ECHO_*_ATTR, das * steht fuer
den als ersten uebergebenen Parameter.
Dabei wird noch CFG_ECHO_GAG_LEVEL beachtet: bei 0 oder nicht gesetzt wird die
Originalmeldung ausgegeben, bei 1 wird nur die Farbe beruecksichtigt, bei 2
wird Farbe und Alternativtext beruecksichtigt
Syntax: /cfg_echo configname %*
Beispiel: /set CFG_ECHO_MG_ZAUBERER_ZSCHILD_TEXT=ZSchild aus.
/set CFG_ECHO_MG_ZAUBERER_ZSCHILD_ATTR=Cblue
/cfg_info MG_ZAUBERER_ZSCHILD %*
Datei: config.tf
-----------------------------------------------------------------------
Makros: cfg_info
Info: Fuegt in die Configurations-Hierarchie eine neue Variable ein. Dabei
wird ueber die Config-Hierarchie-Namen der Platz im Baum angegeben.
Der letzte Parameter ist eine Kurzbeschreibung fuer das Menue (Leerzeichen
durch _ ersetzen).
Wenn der vorletzte Parameter grossgeschrieben ist, weist er direkt auf eine zu
konfigurierende Variable, sonst auf eine weitere Menuebene
Wenn hinter der Beschreibung ein : (Doppelpunkt) folgt, kann dahinter ein
abweichender Variablenname (sonst wird er aus den Config-Hierarchie-Namen
gebildet) angegeben werden, auch koennen durch Doppelpunkt getrennte Zahlen
folgen, die anzeigen, welche Config-Hierarchie-Namen bei der
Variablennamensbildung ignoriert werden sollen.
Syntax: /cfg_info Config-Hierarchie-Namen [name|NAME]
Menue_Text:[varname|ignoriere_hierarchieX[:ignoriere_hierarchieY]
Beispiel: /cfg_info use Paketverwaltung
/cfg_info use LOADING Laden_von_Files
/cfg_info all loading SUFFIX Dateiendungen:file_suffixes -> anderer Varname
/cfg_info status mg tanjian Tanjian:2 -> anderer Varname (CFG_STATUS_TANJIAN,
2==MG faellt weg)
Datei: config.tf