lava.io
Class ConsoleDialog

java.lang.Object
  |
  +--lava.io.ConsoleDialog

public final class ConsoleDialog

extends java.lang.Object

Console-based input manager.

Details: ConsoleDialog offers a set of methods which are useful for interacting with users in console mode applications. Prompts are typically sent to the user through System.out, and responses are received from the user through System.in, but both streams can be customized.

The primary benefit of using ConsoleDialog is that it makes obtaining certain kinds of input easy. For example, you can call a method that requests an integer from the user and know that the return value will be a valid integer, since it will not return until the user complies. Deep in the call, that method automatically handles parsing, re-prompts after invalid responses, etc., so you don't have to.

query* methods

The query* methods prompt the user for information and then wait for a response. If the user's response is valid, the method returns with the data. If the user's response is not valid, then the action taken depends on the value of the error_response parameter passed in.

Case 1: error_response != null

The error_response string is output to the console and the user is prompted for the information again. (Note that a newline character is not automatically appended to the error message.) The method will never return until the user has entered a valid response.

Case 2: error_response == null

No error message is output. Instead, a special value is returned to indicate failure.

Case 3: error_response was omitted from the parameter call

Same as Case 1, except that a default error message is used.

Note that in case (2), it may be difficult to discern valid responses from failure values if the failure values lie within the range of valid responses. (See the documentation for each method for more information on which methods return which failure values.) In cases (1) and (3), the methods do not return until the user has entered a valid response.

Spaces before and after user responses are allowed, but always ignored. If the first part of a response is valid but the line contains additional input, the entire response is rejected. If an EOF signal is detected while reading the user's response, an EOFException is thrown.

Author:

Sharky

Field Summary

java.lang.String

default_error_response Default response to be used when the error response parameter is omitted from a query method call.

Constructor Summary

ConsoleDialog()
Constructs an instance that sends prompts to System.out and receives responses from System.in.

ConsoleDialog(java.io.Reader reader)
Constructs an instance that sends prompts to System.out and receives responses from the specified Reader.

ConsoleDialog(java.io.Reader reader, java.io.Writer writer)
Constructs an instance that sends prompts to the specified output stream and reads responses from the specified input stream.

Method Summary

char	queryChar(java.lang.String prompt) Queries the user for a single character, using the default error response.
char	queryChar(java.lang.String prompt, java.lang.String error_response) Queries the user for a single character.
float	queryFloat(java.lang.String prompt) Queries the user for a float.
float	queryFloat(java.lang.String prompt, java.lang.String error_response) Queries the user for a float.
java.io.File	queryInputFile(java.lang.String prompt, java.lang.String directory) See queryInputFile(String,String,String).
java.io.File	queryInputFile(java.lang.String prompt, java.lang.String directory, java.lang.String error_response) Queries the user for an output filename.
int	queryInt(java.lang.String prompt) Queries the user for an int.
int	queryInt(java.lang.String prompt, int radix) Queries the user for an int.
int	queryInt(java.lang.String prompt, int radix, java.lang.String error_response) Queries the user for an int.
java.io.File	queryOutputFile(java.lang.String prompt, java.lang.String directory) See queryOutputFile(String,String,String).
java.io.File	queryOutputFile(java.lang.String prompt, java.lang.String directory, java.lang.String error_response) Queries the user for an output filename.
java.lang.String	queryWord(java.lang.String prompt) Queries the user for a single word or C-style quoted string.
java.lang.String	queryWord(java.lang.String prompt, java.lang.String error_response) Queries the user for a single word or C-style quoted string.
java.lang.String[]	queryWords(java.lang.String prompt) Queries the user for a list of words.
java.lang.String[]	queryWords(java.lang.String prompt, java.lang.String error_response) Queries the user for a list of words.
java.lang.String	readLine() Reads a line of input.
void	send(java.lang.String s) Writes a string to the output stream and flushes.
void	sendLine(java.lang.String s) Writes a line to the output stream and flushes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

default_error_response

public java.lang.String default_error_response

Default response to be used when the error response parameter is omitted from a query method call.

Constructor Detail

ConsoleDialog

public ConsoleDialog(java.io.Reader reader,
                     java.io.Writer writer)

Constructs an instance that sends prompts to the specified output stream and reads responses from the specified input stream.

Parameters:

reader - the input stream

writer - the output stream

ConsoleDialog

public ConsoleDialog(java.io.Reader reader)

Constructs an instance that sends prompts to System.out and receives responses from the specified Reader.

ConsoleDialog

public ConsoleDialog()

Constructs an instance that sends prompts to System.out and receives responses from System.in.

Method Detail

send

public void send(java.lang.String s)
          throws java.io.IOException

Writes a string to the output stream and flushes.

sendLine

public void sendLine(java.lang.String s)
              throws java.io.IOException

Writes a line to the output stream and flushes.

Since:

1998.11.12

readLine

public java.lang.String readLine()
                          throws java.io.IOException

Reads a line of input.

Returns:

the line that was read, not including the line separator, or null if EOF

queryFloat

public float queryFloat(java.lang.String prompt,
                        java.lang.String error_response)
                 throws java.io.IOException

Queries the user for a float. A valid response is any string of characters which can reasonably be interpreted as a float. For more information about this method, see the general description of query* methods above. Failure value: Float.MIN_VALUE.

Parameters:

prompt - the prompt

error_response - the error response (default: default_error_response)

Returns:

the float entered by the user

queryFloat

public float queryFloat(java.lang.String prompt)
                 throws java.io.IOException

Queries the user for a float. Supplies default parameters for queryFloat(String,String).

queryInt

public int queryInt(java.lang.String prompt,
                    int radix,
                    java.lang.String error_response)
             throws java.io.IOException

Queries the user for an int. A valid response is any string of characters which can be interpreted as a signed 32-bit integer using the given radix. Radix-specific prefixes, such as "0x", are not allowed. For more information about this method, see the general description of query* methods above. Failure value: Integer.MIN_VALUE.

Parameters:

prompt - the prompt

radix - the radix (default: 10)

error_response - the error response (default: default_error_response)

Returns:

the int entered by the user

queryInt

public int queryInt(java.lang.String prompt,
                    int radix)
             throws java.io.IOException

Queries the user for an int. Supplies default parameters for queryInt(String,int,String).

queryInt

public int queryInt(java.lang.String prompt)
             throws java.io.IOException

Queries the user for an int. Supplies default parameters for queryInt(String,int,String).

queryWords

public java.lang.String[] queryWords(java.lang.String prompt,
                                     java.lang.String error_response)
                              throws java.io.IOException

Queries the user for a list of words. A word is defined as any continuous sequence of non-space characters, but spaces may be included in words by surrounding the words with double quotes. Double-quoted strings are interpreted like C-style string literals. Unpaired quotes are treated as literal quotes. For more information about this method, see the general description of query* methods above. If the line entered is blank, a 0-length array is returned. (Note that a blank line is not considered a failure.)

Failure value: null.

Parameters:

prompt - the prompt

error_response - the error response (Default value: default_error_response)

Returns:

an array of Strings containing the words entered by the user

queryWords

public java.lang.String[] queryWords(java.lang.String prompt)
                              throws java.io.IOException

Queries the user for a list of words. Supplies default parameters for queryWords(String,String).

queryWord

public java.lang.String queryWord(java.lang.String prompt,
                                  java.lang.String error_response)
                           throws java.io.IOException

Queries the user for a single word or C-style quoted string. For more information about this method, see the general description of query* methods above.

Failure value: null.

Parameters:

prompt - the prompt

error_response - the error response

Returns:

a String containing the word entered by the user

queryWord

public java.lang.String queryWord(java.lang.String prompt)
                           throws java.io.IOException

Queries the user for a single word or C-style quoted string. Supplies default parameters for queryWord(String,String).

queryChar

public char queryChar(java.lang.String prompt,
                      java.lang.String error_response)
               throws java.io.IOException

Queries the user for a single character. For more information about this method, see the general description of query* methods above.

Failure value: 0.

Parameters:

prompt - the prompt

error_response - the error response

Returns:

the character entered by the user

Since:

1998

queryChar

public char queryChar(java.lang.String prompt)
               throws java.io.IOException

Queries the user for a single character, using the default error response. For more information about this method, see the general description of query* methods above.

Parameters:

prompt - the prompt

Returns:

the character entered by the user

queryInputFile

public java.io.File queryInputFile(java.lang.String prompt,
                                   java.lang.String directory,
                                   java.lang.String error_response)
                            throws java.io.IOException

Queries the user for an output filename. A valid response is filename that describes an existing, readable file. Filenames with spaces must be enclosed in quotes. The user may response with a relative filename or an absolute filename. If a relative filename is given, the directory parameter will be used to resolve the filename.

For more information about this method, see the general description of query* methods above.

Failure value: null.

Note: The following boolean condition is tested to make sure the filename entered is a valid file:

file . exists () && file . isFile () && file . canRead ()

where file is a java.io.File object.

Parameters:

prompt - the prompt

directory - the starting directory for relative filenames

error_response - the error response

Returns:

a File object refering to the file

queryInputFile

public java.io.File queryInputFile(java.lang.String prompt,
                                   java.lang.String directory)
                            throws java.io.IOException

See queryInputFile(String,String,String).

queryOutputFile

public java.io.File queryOutputFile(java.lang.String prompt,
                                    java.lang.String directory,
                                    java.lang.String error_response)
                             throws java.io.IOException

Queries the user for an output filename. A valid response is filename that describes a file that can be created or written to. Filenames with spaces must be enclosed in quotes. The user may response with a relative filename or an absolute filename. If a relative filename is given, the directory parameter will be used to resolve the filename.

For more information about this method, see the general description of query* methods above.

Failure value: null.

Note: The following boolean condition is tested to make sure the filename entered is a valid file:

file . canWrite ()

where file is a java.io.File object.

Parameters:

prompt - the prompt

directory - the starting directory for relative filenames

error_response - the error response

Returns:

a File object refering to the selected output file

queryOutputFile

public java.io.File queryOutputFile(java.lang.String prompt,
                                    java.lang.String directory)
                             throws java.io.IOException

See queryOutputFile(String,String,String).