Update doc/efun/ aus Driversourcen.
Manpages der efuns aktualisiert, neue Manpages hinzugefuegt.
Change-Id: I7cc91684269ff56d1aef47d5c5e7c87f7fd531dc
diff --git a/doc/efun/input_to b/doc/efun/input_to
index 87748d5..973d470 100644
--- a/doc/efun/input_to
+++ b/doc/efun/input_to
@@ -5,112 +5,109 @@
void input_to(string|closure fun, int flag, ...)
void input_to(string|closure fun, int flag, string|closure prompt, ...)
-BESCHREIBUNG
- Die naechste Zeile, die der Spieler eintippt, wird als Argument an die
- Funktion <fun> uebergeben. Ausnahme: wenn die naechste Zeile mit einem
- '!' beginnt, wird sie als Kommando ausgewertet bzw. an das letzte
- input_to() uebergeben, das das INPUT_IGNORE_BANG Flag gesetzt hat.
- Die Funktion <fun> kann "static" deklariert sein, nicht aber "private"
- (sonst wird sie nicht gefunden).
+DESCRIPTION
+ Enable next line of user input to be sent to the function <fun>
+ as an argument. Exception: if the next input
+ line starts with a "!", it will be parsed as a command resp.
+ passed to the most recent input_to() given with the
+ INPUT_IGNORE_BANG flag.
+ The function <fun> may be static, but must not be private (or
+ it won't be found).
- Der Aufruf von <fun> erfolgt nicht sofort, sondern erst, wenn der
- Spieler die Entertaste drueckt.
+ Note that fun is not called immediately but after pressing the
+ RETURN key.
- Wenn input_to() mehr als einmal pro Funktion aufgerufen wird,
- wird normalerweise nur das erste input_to() beruecksichtigt.
- Diese Verhalten kann durch die Angabe von INPUT_APPEND
- modifiziert werden: in diesem Fall wird das input_to() an die
- Liste der bereits anhaengigen input_tos angehaengt (siehe
- BEISPIELE).
+ Usually, if input_to() is called more than once in the same execution,
+ only the first call has any effect. This behaviour can be
+ modified by specifying the INPUT_APPEND flag which will append
+ the given input_to to the already existing input_tos (see
+ EXAMPLES).
- Wird andererseits waehrend einem laufenden input_to() (mittels "!" am
- Zeilenanfang) eine neue Funktion aufgerufen, die wiederum ein
- input_to() enthaelt, wird das urspruengliche input_to() so lange
- unterbrochen, bis das neue input_to() abgearbeitet wurde,
- anschliessend wird es wieder aktiv.
+ Also, if a command given during an input_to() (using the "!"
+ escape) issues its own input_to(), the previous input_to() is
+ suspended until the new input_to() has been handled, then the
+ previous one becomes active again.
- Das optionale <flag> kann ein binaeres Oder (|) der folgenden
- Werte sein:
+ The optional argument <flag> may be a binary-OR ('|') of the
+ following option values:
- INPUT_NOECHO (1):
- Die vom Spieler eingegebene Zeile erzeugt kein Echo und wird auch
- nicht erkannt, wenn der Spieler beobachtet wird.
+ INPUT_NOECHO (1):
+ The line given by the player will not be echoed, and is
+ not seen if snooped.
- Dieser Modus kann nur geaendert werden, wenn telnet enabled ist.
+ A change of this mode not possible with telnet disabled.
- INPUT_CHARMODE (2):
- Die Verbindung zum User wechselt von Zeilen- auf Zeichenmodus. So
- wird nur ein einzelnes Zeichen (!) vom Spieler empfangen.
+ INPUT_CHARMODE (2):
+ The connection is switched from line- into charmode to
+ retrieve a single character(!) from the player.
- Ist telnet disabled, wird lediglich die Interpretation der
- einkommenden Daten durch den Driver umgeschaltet - das
- Clientprogramm des Spieler verbleibt im gerade aktiven Modus.
+ Is telnet disabled, then only the handling of the
+ incoming data by the driver is changed - the client
+ program of the player will remain in its current mode.
- Nachdem die Funktion <fun> ausgefuehrt wurde, wechselt die
- Verbindung zurueck in Zeilenmodus, ausser ein nachfolgendes
- input_to( , 2) wurde gestartet.
+ After execution of <fun>, the connection is switched
+ back into linemode unless a subsequent input_to( , 2)
+ has been issued.
- Zeilenumbrueche werden je nach Client unterschiedlich empfangen,
- entweder als "", als "\r" gefolgt von "" oder als "\r" (letzteres
- kommt vor allem bei Windows Clients vor).
+ Lineends are received exactly as the client sent them:
+ "\n", "\r" followed by "\n", or just "\r".
- Das Frontend des Spielers kann dauernd im Zeilenmodus bleiben.
- Auch wenn input_to() nur ein einzelnes Zeichen fordert, muss der
- Spieler unter Umstaenden das Zeichen und einen Zeilenumbruch
- druecken (und senden). Normalerweise erhaelt <fun> dann den
- gesamten Input auf einmal.
+ Note that the players frontend is free to stay in
+ linemode all the time: even if you request a single
+ character, the player might be forced to type (and send)
+ that character plus the return key. Usually your function
+ will then receive the complete input line (including the
+ newline character sequence!) in one call.
- Will man laenger im Zeichenmodus bleiben, kann der Overhead
- reduziert werden, indem set_combine_charset() verwendet wird. So
- koennen Zeichensequenzen als ein String anstelle von
- Zeichen-fuer-Zeichen empfangen werden. In einem screenorientierten
- Editor gilt dies fuer die meisten druckbaren Zeichen.
+ If you plan to stay in charmode a longer time , you can
+ reduce the call overhead by using set_combine_charset()
+ to retrieve sequences of certain characters as one string
+ instead of one-by-one. In a screen-oriented editor for
+ example this would be most of the printable characters.
- INPUT_PROMPT (4):
- Das Argument nach dem <flag> wird als Prompt fuer die Eingabe
- verwendet. Wenn dieses Argument nicht angegeben (und damit kein
- Propmt definiert) ist, wird kein Prompt ausgegeben.
+ INPUT_PROMPT (4):
+ The argument following the <flag> argument is used as
+ prompt for the input. If this flag is not given, and thus
+ no prompt specified, nothing will be printed.
- INPUT_NO_TELNET (8):
- Modifiziert das INPUT_CHARMODE Argument: der Driver aendert
- seine Behandlung von eingehenden Daten entsprechend dem _CHARMODE
- Argument, sendet aber keine Telnetkommandos zur Anpassung
- des Verhaltens des Clientprogrammes.
+ INPUT_NO_TELNET (8):
+ Modifies the INPUT_CHARMODE flag: the driver will switch
+ it's internal handling of incoming data, but not send out
+ any telnet commands to switch the client's behaviour.
- INPUT_APPEND (16):
- Das input_to() wird an die Liste der bereits anhaengigen
- input_tos angehaengt.
+ INPUT_APPEND (16):
+ Append the input_to to the list of currently pending input_tos
+ (if any).
- INPUT_IGNORE_BANG (128):
- Eingaben, die mit ! beginnen, werden NICHT als Kommandos geparst,
- sondern auch als Argument an die Funkion <fun> uebergeben. Die
- Verwendung dieses Flags ist eingeschraenkt.
+ INPUT_IGNORE_BANG (128):
+ Input lines starting with '!' (or whatever the input
+ escape character was configured to be) will _not_ be parsed as
+ commands, but are given to the function as well. Usage
+ of this option is privileged.
- Alle nachfolgenden Argumente werden als zweites bzw. drittes usw.
- Argument an <fun> uebergeben.
+ The optional trailing args will be passed as second and
+ subsequent args to the function fun.
-
-BEISPIELE
+EXAMPLES
void func() {
- ...
- input_to("enter_name", INPUT_PROMPT, "Wie lautet dein Name?:");
- /* Frueher erledigte man dies mit:
- * write("Wie lautet dein Name?:");
- * input_to("enter_name");
- */
- ...
- }
-
- void enter_name(string str) {
- write("Heisst du wirklich '"+str+"'?? *kicher*\n");
- ...
+ ...
+ input_to("enter_name", INPUT_PROMPT, "Please enter your name:");
+ /* The traditional way of doing this was:
+ * write("Please enter your name:");
+ * input_to("enter_name");
+ */
+ ...
+ }
+ enter_name(string str) {
+ write("Is '"+str+"' really your name?? *giggle*\n");
+ ...
}
- Bei der input_to() Anweisung fuehrt der Driver die Funktion
- func() aus, erwartet aber gleichzeitig Input vom Spieler. Wenn
- dieser etwas eingegeben UND DIE ENTERTASTE GEDRUECKT HAT, arbeitet
- der Driver die Funktion enter_name() mit dem eingegebenen String
- als Argument ab.
+ When reaching the input_to() statement the driver
+ continues the function func() but also asks the user for
+ input. If you entered whatever is asked and press RETURN the
+ driver will invoke the enter_name() function with the
+ string you entered as argument to it.
void func() {
@@ -120,26 +117,53 @@
...
}
- Diese Sequenze erzeugt zwei input_tos: Eingaben gehen zuerst
- an enter_firstname(); und wenn diese Funktion fertig ist
- (einschliesslich etwaiger eigener non-INPUT_APPEND input_tos), geht
- die naechste Eingabe an enter_lastname().
+ This sequence will queue two input_tos: the input first goes
+ to enter_firstname(); and when this function is done
+ (including any non-INPUT_APPEND input_to()s on its own), the next
+ input will go to enter_lastname().
-GESCHICHTE
- Die Bedeutung von <flag> wurde in 3.2.1@93 erweitert.
- Die Limitierung fuer das "stapeln" von input_to()s aus !-Kommandos
- wurde in LDMud 3.2.8 implementiert.
- Seit LDMud 3.2.8 kann <fun> in Form einer Closure angegeben werden.
- LDMud 3.2.9 fuehrte das Flag INPUT_PROMPT samt zugehoerigem Argument
- ein.
- LDMud 3.2.11/3.3.593 fuehrte das INPUT_NO_TELNET Flag ein.
- LDMud 3.2.11/3.3.637 fuehrte das INPUT_APPEND Flag ein.
-FEHLER
- Im Zeichenmodus sollten Zeilenumbrueche eigentlich als "\n" zurueck
- gegeben werden. Dies allerdings kann existierenden Code zerstoeren.
+ Note that the list of input_to-s is treated as a flat list:
-SIEHE AUCH
- call_other(E), sscanf(E), privilege_violation(M),
- set_combine_charset(E), query_input_pending(E), find_input_to(E),
- input_to_info(E), remove_input_to(E), enable_telnet(E)
+ void func() {
+ ..
+ input_to("func1");
+ input_to("func2", INPUT_APPEND);
+ }
+
+ void func1() {
+ ..
+ input_to("func3", INPUT_APPEND);
+ }
+
+ void func2() { ... }
+ void func3() { ... }
+
+ This code will result in the functions being called in the order
+ func(), func1(), func2(), func3(); and not func(), func1(), func3(),
+ func2().
+
+
+BUGS
+ In charmode, it is not possible to receive the NUL character
+ and pass it to the mudlib: internally the NUL character has
+ magical properties.
+
+HISTORY
+ The meaning of the flag parameter was extended in 3.2.1@93.
+ The limited "stacking" of input_to()s issued from !-commands
+ was implemented in LDMud 3.2.8.
+ Since LDMud 3.2.8 the function can be given as a closure.
+ LDMud 3.2.9/3.3.125 introduced the INPUT_PROMPT flag and argument.
+ LDMud 3.2.11/3.3.593 added the INPUT_NO_TELNET flag.
+ LDMud 3.2.11/3.3.637 added the INPUT_APPEND flag.
+ LDMud 3.3 changed the handling of newline sequences in charmode
+ to verbatim passing. Earlier drivers passed an empty string
+ instead.
+ LDMud 3.3 allowed the driver to be configured to use a different
+ input escape character.
+
+SEE ALSO
+ privilege_violation(M), set_combine_charset(E),
+ query_input_pending(E), find_input_to(E), input_to_info(E),
+ remove_input_to(E), enable_telnet(E)