SYNOPSIS
#include <input_to.h>
void input_to(string|closure fun)
void input_to(string|closure fun, int flag, ...)
void input_to(string|closure fun, int flag, string|closure prompt, ...)
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).
Note that fun is not called immediately but after pressing the
RETURN key.
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).
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.
The optional argument <flag> may be a binary-OR ('|') of the
following option values:
INPUT_NOECHO (1):
The line given by the player will not be echoed, and is
not seen if snooped.
A change of this mode not possible with telnet disabled.
INPUT_CHARMODE (2):
The connection is switched from line- into charmode to
retrieve a single character(!) from the player.
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.
After execution of <fun>, the connection is switched
back into linemode unless a subsequent input_to( , 2)
has been issued.
Lineends are received exactly as the client sent them:
"\n", "\r" followed by "\n", or just "\r".
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.
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):
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):
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):
Append the input_to to the list of currently pending input_tos
(if any).
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.
The optional trailing args will be passed as second and
subsequent args to the function fun.
EXAMPLES
void func() {
...
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");
...
}
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() {
..
input_to("enter_firstname");
input_to("enter_lastname, INPUT_APPEND);
...
}
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().
Note that the list of input_to-s is treated as a flat list:
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)
|
