doc/sphinx/lfun/Set.rst

Set()
=====

FUNKTION
--------
::

     public mixed Set(string name, mixed Value,
                 int Type = F_VALUE, int drop_priv = extern_call())

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
     drop_priv - Interne Verwendung, wenn Aufrufer Privilegien abgibt,
                 z.B. objekt-interner Aufruf extern zaehlen soll.

BESCHREIBUNG
------------
::

     Eine der inneren Eigenschaften der Property 'name' wird veraendert.
     'Type' ist dabei einer der in /sys/thing/properties.h definierten
     F_XXX - Werte:

     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')

         SETMAPPED

           Die Set-Methode speichert den Werte nicht selber, sondern gibt
           ihn zurueck, das Property-System speichert ihn dann.
           WARNUNG: Dieses Flag nicht per Hand manipulieren.

     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. Die Closure sollte den neuen Wert der Property
       zurueckliefern. Die Propertyverwaltung aendert hierbei F_VALUE aber
       nicht, dies muss die Closure tun.

     F_SET_MAPPER
       Setzt wie F_SET_METHOD eine Set-Methode (Closure), welche aber den Wert
       der Property beim Aufruf nicht selber (durch Aufruf von Set()) setzt,
       sondern den Wert zurueckgeben muss, der gesetzt werden soll.
       Setzt eine F_SET_METHOD und das Flag SETMAPPED
       Bsp. #'copy um vor dem Speichern eine Kopie zu erstellen

     F_QUERY_METHOD
       Aendert den Eintrag fuer eine QueryMethod - eine Closure, die anstatt
       des Lesens der Property beim Aufruf von QueryProp aufgerufen wird.
       Diese bekommt den gespeicherten Wert der Property uebergeben und muss
       den an den Aufrufer von QueryProp() zurueckzugebenden Wert
       zurueckgeben.
       Bsp: #'copy, um eine Kopie des gespeicherten Wertes zurueckzugeben


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 (Umschalten) 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 Mapperfunktion , welche alle Werte mit 100 multipliziert
     int scale(int val) {return val * 100;}
     Set(P_XYZ, #'scale, F_SET_MAPPER);

     // Setzen einer QueryMethod bei einem anderen Objekt
     mixed bar(mixed f_value);
     ...
     other->Set(P_XYZ, #'bar, F_QUERY_METHOD);
     ...
     // Query-Methode, die beim Abruf eine Kopie des Werts erstellt
     Set(P_XYZ, #'copy, 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

8.9.2021, Zesstra