Flushable
ConfigurableSensibleUi
DefaultConfigurableSensibleUi
public interface SensibleUi extends Flushable
SensibleProgram
.
This interface contains methods for writing output to, and prompting for
input from, the user. The methods for writing output allow for writing
output at different logical levels, similar in concept to levels in a
logging framework. A program using this UI would typically use the
write*
methods for output that should always be written, the
status
, note
, and debug
methods for messages to be
written at the status, note, and debug levels,
respectively, in ascending verbosity order, and the warn
and
error
methods for messages to be written at the warn and
error levels, respectively.
This interface was inspired by that of the ui
object from
Mercurial's
internal API.
Modifier and Type | Method | Description |
---|---|---|
void |
debug(String format,
Object... args) |
Writes the message at the debug level.
|
void |
error(String format,
Object... args) |
Writes the message at the error level.
|
void |
flush() |
Causes any buffered output on the standard output stream, standard error
stream, and any implementation-dependent output destination (e.g., a
ProgramConsole ) to be written out. |
void |
note(String format,
Object... args) |
Writes the message at the note level.
|
String |
prompt(String message,
String defaultResponse) |
Prompts the user with the specified prompt message and default response.
|
int |
promptChoice(String message,
int defaultResponse,
String choices) |
Prompts the user with the specified prompt message, default response, and
choices.
|
char[] |
promptPassword(String message,
char[] defaultPassword) |
Prompts the user for a password with echoing turned off and with the
specified prompt message and default password.
|
void |
status(String format,
Object... args) |
Writes the message at the status level.
|
void |
warn(String format,
Object... args) |
Writes the message at the warn level.
|
void |
write(String format,
Object... args) |
Writes the message to the standard output stream.
|
void |
writeStderr(String format,
Object... args) |
Writes the message to the standard error stream.
|
void write(String format, Object... args)
format
- the format string as defined by Formatter
args
- the format string argumentsIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
underlying standard output streamvoid writeStderr(String format, Object... args)
format
- the format string as defined by Formatter
args
- the format string argumentsIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
underlying standard error streamvoid status(String format, Object... args)
format
- the format string as defined by Formatter
args
- the format string argumentsIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
underlying standard I/O destinationvoid note(String format, Object... args)
format
- the format string as defined by Formatter
args
- the format string argumentsIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
underlying standard I/O destinationvoid debug(String format, Object... args)
format
- the format string as defined by Formatter
args
- the format string argumentsIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
underlying standard I/O destinationvoid warn(String format, Object... args)
A causing/associated exception may be supplied in addition to the message
format and arguments by including it as the last argument in this method's
varargs argument. The exception must be an instance of Throwable
.
What is done with the exception is implementation dependent, but an
implementation could, for example, print the message followed by a stack
trace of the exception. If an exception needs to be supplied as the last
argument to this method but is intended as the last argument in the format
string argument list (e.g., as the argument for a %s
format
specifier), the exception must be supplied as a String
(e.g., by
calling its toString()
method) or any appropriate type that is not
a Throwable
.
format
- the format string as defined by Formatter
args
- the format string arguments optionally followed by a
Throwable
cause/associationIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
underlying standard I/O destinationvoid error(String format, Object... args)
A causing/associated exception may be supplied in addition to the message
format and arguments by including it as the last argument in this method's
varargs argument. The exception must be an instance of Throwable
.
What is done with the exception is implementation dependent, but an
implementation could, for example, print the message followed by a stack
trace of the exception. If an exception needs to be supplied as the last
argument to this method but is intended as the last argument in the format
string argument list (e.g., as the argument for a %s
format
specifier), the exception must be supplied as a String
(e.g., by
calling its toString()
method) or any appropriate type that is not
a Throwable
.
format
- the format string as defined by Formatter
args
- the format string arguments optionally followed by a
Throwable
cause/associationIllegalFormatException
- if format
or args
is illegal according to the rules of Formatter
NullPointerException
- if format
is null
StandardIoException
- if an error occurs while writing to the
underlying standard I/O destinationvoid flush()
ProgramConsole
) to be written out.flush
in interface Flushable
StandardIoException
- if an error occurs while flushing the
underlying standard I/O destinationsString prompt(String message, String defaultResponse)
The prompt message should not include a trailing space character or other trailing whitespace; appropriate whitespace or other characters will be added automatically.
The default response will be returned if the console is not present, the user simply presses enter (i.e., an empty string response), or the end of the stream is reached.
message
- the prompt messagedefaultResponse
- the default responseNullPointerException
- if message
is null
StandardIoException
- if an error occurs while writing/reading
to/from an underlying standard I/O destination/sourceint promptChoice(String message, int defaultResponse, String choices)
The prompt message should not include a trailing space character or other trailing whitespace; appropriate whitespace or other characters will be added automatically.
The default response will be returned if the console is not present, the user simply presses enter (i.e., an empty string response), or the end of the stream is reached.
The choices are encoded in the choices format which is a comma-separated list of choices. A choice may be split into alternatives that are all considered to be equivalent by separating them with a slash. All choices must be lowercase. A backslash escapes the character that follows it thus allowing the encoding of the backslash, comma, and slash characters as choices if needed. The user's response will be converted to lowercase before searching the choices for a match.
Choices Format Examples:
y
" or "n
" in
arbitrary case:
y,n
y
", "yes
",
"n
", or "no
" in arbitrary case:
y/yes,n/no
y
", "yes
",
"yes, please
", "n
", "no
", "no, thank you
",
"h
", or "help
" in arbitrary case:
y/yes/yes\, please,n/no/no\, thank you,h/help
message
- the prompt messagedefaultResponse
- the zero-based index of the default response in the
choices list; must be greater than or equal to zerochoices
- the choices encoded in the choices format; must be all
lowercase-1
if the user's response does not match any choice; otherwise (i.e.,
the user's response could not be obtained), the default responsePromptChoicesSyntaxException
- if choices
is malformedIllegalArgumentException
- if defaultResponse
is less than
zeroNullPointerException
- if message
or choices
is
null
StandardIoException
- if an error occurs while writing/reading
to/from an underlying standard I/O destination/sourcechar[] promptPassword(String message, char[] defaultPassword)
The prompt message should not include a trailing space character or other trailing whitespace; appropriate whitespace or other characters will be added automatically.
The default password will be returned if the console is not present, the user simply presses enter (i.e., an empty string password), or the end of the stream is reached.
message
- the prompt messagedefaultPassword
- the default passwordNullPointerException
- if message
is null
StandardIoException
- if an error occurs while writing/reading
to/from an underlying standard I/O destination/source