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