Update doc/efun/ aus Driversourcen.
Manpages der efuns aktualisiert, neue Manpages hinzugefuegt.
Change-Id: I7cc91684269ff56d1aef47d5c5e7c87f7fd531dc
diff --git a/doc/efun/catch b/doc/efun/catch
index 57c58aa..f9a6056 100644
--- a/doc/efun/catch
+++ b/doc/efun/catch
@@ -1,65 +1,67 @@
SYNOPSIS
mixed catch(expr, expr, ...)
- mixed catch(expr, expr, ...; modifiers)
+ mixed catch(expr, expr, ... ; modifiers)
-BESCHREIBUNG
- Wertet die Ausdruecke <expr> aus. Wenn kein Fehler auftritt, wird 0
- zurueck geliefert. Wenn ein Fehler auftritt, wird die Ausfuehrung an
- diesem Punkt abgebrochen und ein String mit der Fehlermeldung wird
- zurueck gegeben.
+DESCRIPTION
+ Evaluate the expressions. If there is no error, 0 is returned.
+ If there is an error, the evaluation of the expressions stops at
+ that point, and a string with the error message is returned.
- Systemeigene Fehlermeldungen beginnen mit einem "*", benutzerdefinierte
- Fehlermeldungen aus throw() und raise_error() (sofern von 0
- verschieden), werden unveraendert zurueck geliefert.
+ System error messages start with a leading '*', user-defined
+ error values (other than 0) as given to throw() and raise_error() are
+ returned as they are.
- Wenn zum Zeitpunkt, zu dem catch() aufgerufen wird, weniger als
- __CATCH_EVAL_COST__ Rechenticks uebrig sind, wird ein Laufzeitfehler
- RTE innerhalb von catch() erzeugt (und somit wie jeder andere
- Fehler abgefangen) und es werden keine Ausdruecke <expr> aus catch()
- ausgewertet. Der Modifikator 'reserve' kann verwendet werden,
- einen anderen Wert fuer die Reserve anzugeben.
+ If at the time the catch() is encountered less than
+ __CATCH_EVAL_COST__ eval ticks are left, a runtime error will be
+ thrown from inside the catch() (and thus caught like every other
+ error) and the expressions will not be executed. The 'reserve'
+ modifier can be used to reserve a different amount of eval ticks.
- Das Verhalten von catch() kann durch <modifiers> veraendert werden:
+ The default behaviour of catch() can be changed using modifiers:
- 'nolog': Normalerweise wird der Fehler im Fehlerlog
- gespeichert, um die Fehlersuche zu erleichtern. Wird
- 'nolog' gesetzt, wird dieser Log-Eintrag unterdrueckt.
- 'publish': Normalerweise wird master::runtime_error() fuer einen
- Fehler innerhalb eines catch() nicht aufgerufen. Mit
- diesem <modifier> wird runtime_error() trotzdem
- aufgerufen.
- 'reserve <expr>': <expr> muss eine ganzen Zahl groesser 0
- ergeben, welche dann als Rechenreserve anstelle
- von __CATCH_EVAL_COST__ verwendet wird. Das Minimum
- ist 2 * __MASTER_EVAL_COST__ .
+ 'nolog': Normally, the caught error will be logged in the
+ error logs for easier debugging. With this
+ modifier, the log is suppressed.
- catch() an sich ist nicht besonders laufzeit-intensiv: es braucht
- nur etwas mehr Zeit als ein Intra-Objekt-Funktionsaufruf.
-
- throw() ist ebenfalls nicht sehr teuer, da lediglich einige
- interne Strukturen aufgeraeumt werden muessen.
+ 'publish': Normally, master::runtime_error() is not called
+ for a caught error. This modifier instructs
+ catch() to call it nevertheless.
- Echte Laufzeitfehler (ob nun mit oder ohne catch()) sind hingegen
- sehr zeitintensiv.
+ 'reserve <expr>': The expression has to evaluate to a number
+ greater than 0 and is used to determine the amount
+ of eval ticks to reserve, instead of the default
+ of __CATCH_EVAL_COST__. The minimum required
+ are 2 * __MASTER_EVAL_COST__.
+ 'limit <expr>': The expression has to evaluate to a number
+ greater than 0 and is used to limit the eval cost
+ for the evaluation of the expression.
- catch ist nicht im eigentlichen Sinne eine Efun, sondern eine Compiler
- Anweisung.
+ catch() itself is not expensive as far as execution time is
+ concerned: it is about the same as a intra-object function call.
+ throw() is not very expensive either, but does include the
+ internal cleanup of several structures.
-BEISPIELE
+ Real runtime errors on the other hand are expensive regardless
+ of whether they are caught or not, as they include the generation
+ of the stack backtrace.
+
+ catch() is not really an efun but a compiler directive.
+
+EXAMPLES
object obj;
string err;
- if(err = catch(obj = clone_object("/foo/bar/baz")))
- write("Kann das Objekt nicht clonen. Grund: "+err+"\n");
+ if (err = catch(obj = clone_object("/foo/bar/baz")))
+ write("Cannot clone object, reason:"+err"+\n");
-GESCHICHTE
- LDMud 3.2.9 fuehrte den 'nolog' catch() als experimentelles Feature
- ein.
- LDMud 3.2.10 implementierte 'nolog' als offizielle Form und fuehrte
- zudem 'publish' ein.
- LDMud 3.3.559 verlegte den Test auf verbleibende Rechenticks in die
- vom catch() umschlossenen Ausfuehrung.
- LDMud 3.3.560 fuegte den Modifikator 'reserve' ein.
+HISTORY
+ LDMud 3.2.9 introduced the 'nolog' catch() as experimental feature.
+ LDMud 3.2.10 implemented 'nolog' as official form and added
+ 'publish'.
+ LDMud 3.3.559 moved the check regarding __CATCH_EVAL_COST__ inside
+ the catch().
+ LDMud 3.3.560 added the 'reserve' modifier.
+ LDMud 3.6.7 added the 'limit' modifier.
-SIEHE AUCH
+SEE ALSO
throw(E), raise_error(E), predefined(D), runtime_error(M)