Automatisch erzeugte Manpages.
Damit nicht jeder sphinx auf dem Rechner haben muss,
behalten wir bis auf weiteres die aus den .rst
erzeugten Manpoages auch im Repo.
Change-Id: Id556c0d11cf5f79659d8350952ce1c014d81ea44
diff --git a/doc/lfun/Set b/doc/lfun/Set
index 42e6930..d654027 100644
--- a/doc/lfun/Set
+++ b/doc/lfun/Set
@@ -1,137 +1,174 @@
+
Set()
-FUNKTION:
- public varargs mixed Set(string name, mixed Value, int Type, int extern);
+*****
-DEFINIERT IN:
- /std/thing/properties.c
- /sys/thing/properties.h (Prototyp)
-ARGUMENTE:
- name - Property, die manipuliert werden soll
- Value - der zu setzende/aendernde Wert
- Type - die Eigenschaft der Property, die manipuliert werden soll
- extern - Interne Verwendung:
- Wurde Set ueber SetProp von aussen gerufen.
+FUNKTION
+========
-BESCHREIBUNG:
- Eine der inneren Eigenschaften der Property 'name' wird veraendert.
- 'Type' ist dabei einer der in /sys/thing/properties.h definierten
- F_XXX - Werte:
+ public varargs mixed Set(string name, mixed Value, int Type, int extern);
- F_VALUE (==0, default)
- Setzt den Inhalt der Property auf 'Value'. Aehnlich "SetProp",
- umgeht jedoch eine etwaige F_SET_METHOD oder _set_'name'()-Methode.
- F_MODE
- F_MODE_AS
- F_MODE_AD
- Aendert eines der internen Flags der Property. F_MODE negiert den
- vorherigen Wert vom Flag 'Value', F_MODE_AS setzt und F_MODE_AD
- loescht ihn.
- Verfuegbare interne Flags:
- SAVE
- Property wird bei save_object() gespeichert
- PROTECTED
- Flag setzbar durch: beliebiges Objekt
- Flag loeschbar durch: this_object(), ROOT, EM+
- Inhalt der Property veraendern sowie Set- und Query-Methoden
- setzen oder loeschen duerfen nur noch this_object(), ROOT, EM+
- WARNUNG: Dieses Flag nicht leichtfertig bei Spielern setzen!
- SECURED
- Flag setzbar durch: this_object(), ROOT, EM+
- Flag loeschbar durch: Niemanden!
- Inhalt der Property veraendern sowie Set- und Query-Methoden
- setzen oder loeschen duerfen nur noch this_object(), ROOT, EM+
- NOSETMETHOD
- Property nicht mehr ueber SetProp() aenderbar
- (damit entfallen auch SET_METHOD, _set_'name')
- F_SET_METHOD
- Aendert den Eintrag fuer eine SetMethod - eine Closure, die anstatt
- des Setzens der Property beim Aufruf von SetProp mit 'Value'
- aufgerufen wird.
- F_QUERY_METHOD
- Aendert den Eintrag fuer eine QueryMethod - eine Closure, die anstatt
- des Lesens der Property beim Aufruf von QueryProp aufgerufen wird.
-RUeCKGABEWERT:
- Das Ergebnis der Manipulation bzw. einer der definierten
- Fehlercodes.
+DEFINIERT IN
+============
-BEMERKUNGEN:
- - Set() sollte nicht zum regulaeren Manipulieren des Inhalts einer
- Property verwendet werden, da sowohl F_SET_METHOD als auch libinterne
- _set_'name'()-Methoden umgangen werden und das Ergebnis fuer so
- veraenderte Properties undefiniert ist.
- - eine gesetzte F_SET/F_QUERY_METHOD hat bei SetProp/QueryProp Vorrang
- vor einer _set/_query_method
- -> _set/_query wird nach erfolgreichem Ruf von F_XXX_METHOD ignoriert
- - F_SET/F_QUERY_METHOD sollte normalerweise Vorzug vor einer
- _set_/_query_* gegeben werden.
+ /std/thing/properties.c
+ /sys/thing/properties.h (Prototyp)
- SetMethods/QueryMethods:
- - falls ihr Query/SetMethods an oeffentlichen Properties setzen
- wollt, prueft bitte vorher, ob dort nicht schon eine (fremde) gesetzt
- ist und brecht ggf. euer Set() ab, um nicht die Arbeit anderer
- Mitmagier zu sabotieren (z.B. P_HANDS)
- - Properties sollten mit Query- oder SetMethoden nur so lange wie
- noetig belegt werden
- -> manche Properties sollte man als Wert setzen, _auch wenn_ die
- Spieler sie zuruecksetzen koennten (zB P_MSGIN/P_MSGOUT)
- - auf keinen Fall den Wert speichern, ueberschreiben, rueckschreiben,
- das fuehrt fast immer zu Problemen.
- - Set/QueryMethoden sollten nicht als Trigger/Listener fuer ein
- Ereignis (z.B. P_DIE_MSG fuer das Ereignis "Tod des Spielers")
- missbraucht werden
- -> es gibt sichere und saubere Moeglichkeiten (NotifyPlayerDeath),
- und wenn nicht, wendet euch an den EM eures Vertrauens
- - F_SET/F_QUERY_METHODs koennen 'protected' (empfohlen) oder 'static'
- sein. _set_/_query_ duerfen momentan _nicht_ 'protected' sein, fuer
- geht nur 'static' (in diesem Fall empfohlen).
-BEISPIELE:
- ### Aendern von Eigenschaften einer Property ###
- // Setzen des SAVE-Flags (bei save_object() mitzuspeichern)
- Set(P_XYZ, SAVE, F_MODE_AS);
+ARGUMENTE
+=========
- // Loeschen des SAVE-Flags
- Set(P_XYZ, SAVE, F_MODE_AD);
-
- // Negieren des bisherigen SAVE-Flags
- Set(P_XYZ, SAVE, F_MODE);
- // Hinweis: das Setzen des Flags funktioniert mittels F_MODE nur dann,
- // wenn sichergestellt ist, dass es vorher nicht gesetzt war. Die
- // sichere Variante ist daher, F_MODE_AS zu verwenden.
+ name - Property, die manipuliert werden soll
+ Value - der zu setzende/aendernde Wert
+ Type - die Eigenschaft der Property, die manipuliert werden soll
+ extern - Interne Verwendung:
+ Wurde Set ueber SetProp von aussen gerufen.
- // Sperren des SetProp/SET_METHOD-Zugriffs:
- Set(P_XYZ, NOSETMETHOD, F_MODE_AS);
- // Vorlaeufiger Zugriffsschutz fuer eine Property:
- Set(P_XYZ, PROTECTED, F_MODE_AS);
+BESCHREIBUNG
+============
- // Permanenter Zugriffsschutz fuer eine Property:
- Set(P_XYZ, SECURED, F_MODE_AS);
+ Eine der inneren Eigenschaften der Property 'name' wird veraendert.
+ 'Type' ist dabei einer der in /sys/thing/properties.h definierten
+ F_XXX - Werte:
- ### Setzen einer SetMethod/QueryMethod ###
- // Setzen einer internen SetMethod
- mixed foo(mixed val);
- ...
- Set(P_XYZ, #'foo, F_SET_METHOD);
- ...
+ F_VALUE (==0, default)
+ Setzt den Inhalt der Property auf 'Value'. Aehnlich "SetProp",
+ umgeht jedoch eine etwaige F_SET_METHOD oder _set_'name'()-Methode.
+ F_MODE
+ F_MODE_AS
+ F_MODE_AD
+ Aendert eines der internen Flags der Property. F_MODE negiert den
+ vorherigen Wert vom Flag 'Value', F_MODE_AS setzt und F_MODE_AD
+ loescht ihn.
+ Verfuegbare interne Flags:
- // Setzen einer QueryMethod bei einem anderen Objekt
- mixed bar();
- ...
- other->Set(P_XYZ, #'bar, F_QUERY_METHOD);
- ...
+ SAVE
- // Der Vollstaendigkeit halber sei das Aendern einer Property unter
- // Umgehung von Set-Methoden angegeben. Es ist aber aus o.g. Gruenden
- // zu empfehlen, diese Variante nicht zu verwenden.
- Set(P_XYZ, "bla", F_VALUE);
+ Property wird bei save_object() gespeichert
-SIEHE AUCH:
- Aehnliches: SetProp(L), QueryProp(L), Query(L)
- Generell: SetProperties(L), QueryProperties(L)
- Konzept: properties, /std/thing/properties.c
- Sonstiges: P_AUTOLOADOBJ
+ PROTECTED
-06. Jan 2008 Arathorn
+ Flag setzbar durch: beliebiges Objekt
+ Flag loeschbar durch: this_object(), ROOT, EM+
+ Inhalt der Property veraendern sowie Set- und Query-Methoden
+ setzen oder loeschen duerfen nur noch this_object(), ROOT, EM+
+ WARNUNG: Dieses Flag nicht leichtfertig bei Spielern setzen!
+
+ SECURED
+
+ Flag setzbar durch: this_object(), ROOT, EM+
+ Flag loeschbar durch: Niemanden!
+ Inhalt der Property veraendern sowie Set- und Query-Methoden
+ setzen oder loeschen duerfen nur noch this_object(), ROOT, EM+
+
+ NOSETMETHOD
+
+ Property nicht mehr ueber SetProp() aenderbar
+ (damit entfallen auch SET_METHOD, _set_'name')
+ F_SET_METHOD
+ Aendert den Eintrag fuer eine SetMethod - eine Closure, die anstatt
+ des Setzens der Property beim Aufruf von SetProp mit 'Value'
+ aufgerufen wird.
+ F_QUERY_METHOD
+ Aendert den Eintrag fuer eine QueryMethod - eine Closure, die anstatt
+ des Lesens der Property beim Aufruf von QueryProp aufgerufen wird.
+
+
+RUeCKGABEWERT
+=============
+
+ Das Ergebnis der Manipulation bzw. einer der definierten
+ Fehlercodes.
+
+
+BEMERKUNGEN
+===========
+
+ - Set() sollte nicht zum regulaeren Manipulieren des Inhalts einer
+ Property verwendet werden, da sowohl F_SET_METHOD als auch libinterne
+ _set_'name'()-Methoden umgangen werden und das Ergebnis fuer so
+ veraenderte Properties undefiniert ist.
+ - eine gesetzte F_SET/F_QUERY_METHOD hat bei SetProp/QueryProp Vorrang
+ vor einer _set/_query_method
+ -> _set/_query wird nach erfolgreichem Ruf von F_XXX_METHOD ignoriert
+ - F_SET/F_QUERY_METHOD sollte normalerweise Vorzug vor einer
+ _set_/_query_* gegeben werden.
+
+ SetMethods/QueryMethods:
+ - falls ihr Query/SetMethods an oeffentlichen Properties setzen
+ wollt, prueft bitte vorher, ob dort nicht schon eine (fremde) gesetzt
+ ist und brecht ggf. euer Set() ab, um nicht die Arbeit anderer
+ Mitmagier zu sabotieren (z.B. P_HANDS)
+ - Properties sollten mit Query- oder SetMethoden nur so lange wie
+ noetig belegt werden
+ -> manche Properties sollte man als Wert setzen, _auch wenn_ die
+ Spieler sie zuruecksetzen koennten (zB P_MSGIN/P_MSGOUT)
+ - auf keinen Fall den Wert speichern, ueberschreiben, rueckschreiben,
+ das fuehrt fast immer zu Problemen.
+ - Set/QueryMethoden sollten nicht als Trigger/Listener fuer ein
+ Ereignis (z.B. P_DIE_MSG fuer das Ereignis "Tod des Spielers")
+ missbraucht werden
+ -> es gibt sichere und saubere Moeglichkeiten (NotifyPlayerDeath),
+ und wenn nicht, wendet euch an den EM eures Vertrauens
+ - F_SET/F_QUERY_METHODs koennen 'protected' (empfohlen) oder 'static'
+ sein. _set_/_query_ duerfen momentan _nicht_ 'protected' sein, fuer
+ geht nur 'static' (in diesem Fall empfohlen).
+
+
+BEISPIELE
+=========
+
+ ### Aendern von Eigenschaften einer Property ###
+ // Setzen des SAVE-Flags (bei save_object() mitzuspeichern)
+ Set(P_XYZ, SAVE, F_MODE_AS);
+
+ // Loeschen des SAVE-Flags
+ Set(P_XYZ, SAVE, F_MODE_AD);
+
+
+
+ // Negieren des bisherigen SAVE-Flags
+ Set(P_XYZ, SAVE, F_MODE);
+ // Hinweis: das Setzen des Flags funktioniert mittels F_MODE nur dann,
+ // wenn sichergestellt ist, dass es vorher nicht gesetzt war. Die
+ // sichere Variante ist daher, F_MODE_AS zu verwenden.
+
+ // Sperren des SetProp/SET_METHOD-Zugriffs:
+ Set(P_XYZ, NOSETMETHOD, F_MODE_AS);
+
+ // Vorlaeufiger Zugriffsschutz fuer eine Property:
+ Set(P_XYZ, PROTECTED, F_MODE_AS);
+
+ // Permanenter Zugriffsschutz fuer eine Property:
+ Set(P_XYZ, SECURED, F_MODE_AS);
+
+ ### Setzen einer SetMethod/QueryMethod ###
+ // Setzen einer internen SetMethod
+ mixed foo(mixed val);
+ ...
+ Set(P_XYZ, #'foo, F_SET_METHOD);
+ ...
+
+ // Setzen einer QueryMethod bei einem anderen Objekt
+ mixed bar();
+ ...
+ other->Set(P_XYZ, #'bar, F_QUERY_METHOD);
+ ...
+
+ // Der Vollstaendigkeit halber sei das Aendern einer Property unter
+ // Umgehung von Set-Methoden angegeben. Es ist aber aus o.g. Gruenden
+ // zu empfehlen, diese Variante nicht zu verwenden.
+ Set(P_XYZ, "bla", F_VALUE);
+
+
+SIEHE AUCH
+==========
+
+ Aehnliches: SetProp(L), QueryProp(L), Query(L)
+ Generell: SetProperties(L), QueryProperties(L)
+ Konzept: properties, /std/thing/properties.c
+ Sonstiges: P_AUTOLOADOBJ
+
+6. Jan 2008 Arathorn