Update doc/efun/ aus Driversourcen.
Manpages der efuns aktualisiert, neue Manpages hinzugefuegt.
Change-Id: I7cc91684269ff56d1aef47d5c5e7c87f7fd531dc
diff --git a/doc/efun/call_other b/doc/efun/call_other
index ee6ebdd..4cfaddd 100644
--- a/doc/efun/call_other
+++ b/doc/efun/call_other
@@ -2,93 +2,95 @@
unknown call_other(object ob, string fun, mixed arg, ...)
unknown call_other(object *ob, string fun, mixed arg, ...)
- ob->fun(mixed arg, ...)
- ob->"fun"(mixed arg, ...)
- ob->(fun)(mixed arg, ...)
+ ob->fun (mixed arg, ...)
+ ob->"fun" (mixed arg, ...)
+ ob->(fun) (mixed arg, ...)
-BESCHREIBUNG
- Ruft die in einem anderen Objekt <ob> die Funktion <fun> mit den
- Argumenten <arg...> auf und gibt den Wert zurueck, der von der
- Funktion <fun> geliefert wird (oder 0 fuer nicht existierende oder
- als void deklarierte Funktionen).
+DESCRIPTION
+ Call a member function <fun> in another object <ob> with an
+ the argument(s) <arg...>. Result is the value returned from
+ the called function (or 0 for non-existing or void functions).
- Weiterhin wird auch ein Array von Objekten *<ob> akzeptiert. Die
- Funktion <fun> wird dann fuer jedes Objekt <ob> im Array mit den
- Argumenten <arg...> aufgerufen.
- Die einzelnen Resultate werden in einem Array zusammen gefasst und
- dieses Array dann als Endresultat von call_other() zurueck gegeben.
- Die Elemente von *<ob> koennen Objekte oder Namen von Objekten sein.
- Zerstoerte Objekte und 0 als Element geben eine 0 zurueck, fuehren
- aber nicht zu einem Fehler.
+ Additionally the efun accepts an array of objects as <ob>: the
+ function is called with the same arguments in all the given objects.
+ The single results are collected in an array and yield the final
+ result. Array elements can be objects or the names of existing
+ objects; destructed objects and 0s will yield a '0' as result, but
+ don't cause an error.
- Das Objekt (bzw. die Objekte) kann direkt oder ueber einen String
- (d.h. den Objektnamen) angegeben werden. Wenn ein String angegeben
- wird und das Objekt noch nicht existiert, wird es geladen.
+ The object(s) can be given directly or via a string (i.e. its
+ object_name). If it is given by a string and the object does not
+ exist yet, it will be loaded.
- ob->fun(args) und "ob_name"->fun(args) sind aequivalent zu
- call_other(ob, "fun", args). Heutzutage kann "ob_name" auch eine
- Variable sein. ob->(fun)(args) ist aequivalent zu
- call_other(ob, fun, args), wobei <fun> ein Runtime Ausdruck ist,
- der den Funktionsnamen liefert.
+ ob->fun(args) and "ob_name"->fun(args) is equivalent to
+ call_other(ob, "fun", args). Nowadays the ob_name string can
+ also be a variable.
- Wenn das Objekt <ob> keine oeffentliche Funktion mit dem Namen <fun>
- enthaelt, gibt call_other() den Wert 0 zurueck. Dies ist nicht
- unterscheidbar von einer Funktion <fun>, die 0 zurueck liefert.
- Oeffentlich bedeutet "public", wenn andere Objekte aufgerufen
- werden und "public" oder "static", wenn der Aufruf an this_object()
- ergeht. Funktionen, die "private" oder "protected" definiert sind,
- koennen niemals von call_other() aufgerufen werden.
+ ob->fun(args) and ob->"fun"(args) are equivalent to
+ call_other(ob, "fun", args). ob->(fun)(args) are equivalent
+ to call_other(ob, fun, args) where fun is a runtime expression
+ returning the function name.
- Der Rueckgabewert von call_other() ist standardmaessig 'any'. Falls
- aber #pragma strict_types gesetzt ist, ist der Rueckgabewert
- 'unknown', und das Resultat des call_other() muss zuerst auf einen
- zutreffenden Variablentyp gecastet werden, bevor man es fuer etwas
- verwenden kann.
+ If ob::fun does not define a publicly accessible function, the
+ efun will call the H_DEFAULT_METHOD hook if set. If the hook
+ is not set or can't resolve the call either, call_other()
+ will return 0, which is indistinguishable from a function returning 0.
-BEISPIELE
- Die nachfolgenden Beispiele rufen alle die Funktion "QueryProp" auf
- mit dem Argument P_SHORT.
+ Calls to the master object never use the H_DEFAULT_METHOD hook.
+ To force non-default calls, the efun call_direct() can be used.
- string str, fun;
- str = (string)call_other(this_player(), "QueryProp", P_SHORT);
- fun = "QueryProp";
- str = (string)call_other(this_player(), fun, P_SHORT);
+ "publicly accessible" means "public" when calling other objects,
+ and "public" or "static" when calling this_object(). "private"
+ and "protected" function can never be called with call_other().
- str = (string)this_player()->QueryProp(P_SHORT);
- str = (string)this_player()->"QueryProp"(P_SHORT);
- fun = "QueryProp";
- str = (string)this_player()->(fun)(P_SHORT);
+ The return type of call_other() is 'any' by default. However,
+ if your LPC code uses #pragma strict_types, the return type is
+ 'unknown', and the result of call_other() must be casted to
+ the appropriate type before you can use it for anything.
- Solange #pragma strict_types gesetzt ist, muss man das Resultat von
- call_other() explizit auf einen passenden Typ casten, weil
- call_other() unknown liefert.
+EXAMPLES
+ // All the following statements call the lfun QueryProp()
+ // in the current player with the argument P_SHORT.
+ string str, fun;
- Das folgende Statement ruft die lfun short() in allen aktiven
- Benutzern auf und speichert das gesammelte Resultat in einer
- Variablen:
+ str = (string)call_other(this_player(), "QueryProp", P_SHORT);
+ fun = "QueryProp";
+ str = (string)call_other(this_player(), fun, P_SHORT);
- string *s;
- s = (string *)users()->short();
- !Compat: call_other("/users/luser/thing", "???", 0);
- Compat: call_other("users/luser/thing", "???", 0);
+ str = (string)this_player()->QueryProp(P_SHORT);
+ str = (string)this_player()->"QueryProp"(P_SHORT);
+ fun = "QueryProp";
+ str = (string)this_player()->(fun)(P_SHORT);
- Das sieht etwas merkwuerdig aus, wurde aber oft verwendet, um einfach
- ein Objekt zu laden. Dazu wurde die (nicht existierende) Funktion
- "???" im Objekt aufgerufen. Gluecklicherweise gibt es heute zu
- diesem Zweck die Efun load_object().
+ You have to do explicit type casting because of the unknown
+ return type, if you have set #pragma strict_types.
-GESCHICHTE
- In LDMud 3.2.8 wurden die folgenden Verbesserungen eingefuehrt:
- - die Formen x->"y"() und x->(y)() werden erkannt;
- - die Form x->y() kollidiert nicht mehr mit einer lokalen Variablen,
- die auch "y" heisst.
- - eine simul_efun call_other() erwischt auch Aufrufe der Form ->().
- - call_other kann auch auf Arrays von Objekten angewandt werden.
- LDMud 3.2.10 machte den Aufruf von Objektarrays konfigurierbar.
- LDMud 3.3.113 fuehrte den Hook H_DEFAULT_METHOD ein.
- LDMud 3.5.0 machte den Aufruf von Objektarrays nicht mehr optional.
+ // This statement calls the lfun short() in all interactive users
+ // and stores the collected results in a variable.
+ string *s;
-SIEHE AUCH
- call_direct(E), call_direct_resolved(E), call_resolved(E), create(A),
- pragma(LPC), extern_call(E), function_exists(E), functions(LPC),
- map_objects(E)
+ s = (string *)users()->short();
+
+ !Compat: call_other("/users/luser/thing", "???", 0);
+ Compat: call_other("users/luser/thing", "???", 0);
+
+ This looks a bit weird but it was used very often to just load
+ the object by calling a not existing function like "???".
+ Fortunately nowadays there is an efun load_object() for this
+ purpose.
+
+HISTORY
+ In LDMud 3.2.8 the following improvements were made:
+ - the forms x->"y"() and x->(y)() are recognized;
+ - the form x->y() no longer clashes with a local variable also
+ called "y";
+ - a simul_efun call_other() also catches ->() calls.
+ - call_other can be applied on arrays of objects.
+ LDMud 3.2.10 made the call on arrays of objects configurable.
+ LDMud 3.3.113 introduced the H_DEFAULT_METHOD hook.
+ LDMud 3.5.0 made the call on arrays of objects non-optional.
+
+SEE ALSO
+ call_direct(E), call_strict(E), call_direct_strict(E),
+ call_resolved(E), call_direct_resolved(E), create(A), pragma(LPC),
+ extern_call(E), function_exists(E), functions(LPC), map_objects(E)