edu.colorado.io
Class EasyReader

java.lang.Object
  java.io.Reader
      java.io.FilterReader
          java.io.PushbackReader
              edu.colorado.io.EasyReader

All Implemented Interfaces:

java.io.Closeable, java.lang.Readable

public class EasyReader
extends java.io.PushbackReader

The EasyReader object has a small collection of methods for reading some primitive data values from an input stream or file.

Limitations:
If an IOException or FileNotFoundException occurs during any operation, then the EasyReader prints an error message and halts the program. The exceptions is not passed back to the calling program, so the calling program does not need to catch any exceptions.

Example:
This example declares an EasyReader that is attached to the keyboard input (System.in). It then uses doubleQuery to ask the user to enter a double number. The square of this double number is then printed:
import edu.colorado.io.EasyReader
...
EasyReader stdin = new EasyReader(System.in); // Attaches to keyboard
double d;
d = stdin.doubleQuery("Please type a double value: ");
System.out.println("The square of that is: " + d*d);


The EasyReader class includes:

(1) Three constructors to create an EasyReader from an InputStream, from an InputStreamReader, or from a file name. For example, to create an EasyReader from System.in:
EasyReader stdin = new EasyReader(System.in);

(2) Query methods: The names of these methods end with "Query". Each method prints a prompt (which is a String parameter) and then reads one line of input, converting the line to some type (char, double, int, or String). All of the query methods reject improperly formatted input lines (such as a 1.5 for an integer input). When an input line is rejected, the method prompts the user for a correctly formatted input. This continues until an input line is typed in the correct format.

(3) Peek method: This method returns the next character of the input without actually reading it.

(4) Input methods: The names of these methods end with "Input" or "InputLine". The methods read input and convert it to some type (char, double, int, or String). The "Input" methods just read the data, and the "InputLine" methods read the data and then discard the rest of the line.

(5) Boolean methods: The names of these methods begin with "is". They return various information about the input status.

(6) The methods skipLine and ignore. They read and throw away various input.

Java Source Code for this class:

http://www.cs.colorado.edu/~main/edu/colorado/io/EasyReader.java

See Also:

FormatWriter

Constructor Summary

EasyReader(java.io.InputStream in)
Initialize this EasyReader so that it reads from an InputStream.

EasyReader(java.io.InputStreamReader isr)
Initialize this EasyReader so that it reads from an InputStreamReader.

EasyReader(java.lang.String name)
Initialize this EasyReader so that it reads from a specified file.

Method Summary

char	charInput() Read a character from this EasyReader.
char	charInputLine() Read a character from a complete line of this EasyReader.
char	charQuery(java.lang.String prompt) Print a prompt, then read and return a character from this EasyReader.
double	doubleInput() Read a double number from this EasyReader.
double	doubleInputLine() Read a double value from a complete line of this EasyReader.
double	doubleQuery(java.lang.String prompt) Print a prompt, then read and return a double value from this EasyReader.
void	ignore() Read and discard one character.
int	intInput() Read an integer from this EasyReader.
int	intInputLine() Read an integer from a complete line of this EasyReader.
int	intQuery(java.lang.String prompt) Print a prompt, then read and return an integer from this EasyReader.
boolean	isEOF() Determine whether this EasyReader has reached the end-of-file.
boolean	isEOLN() Determine whether the next input character is an end-of-line.
boolean	isFormatProblem() Determine whether there was an incorrectly formatted input to the most recent input operation.
static void	main(java.lang.String[] args) A demonstration program.
static void	pause(long milliseconds) Make the computation pause for a specified number of milliseconds.
char	peek() Peek ahead at the next character from this EasyReader (but don't read it).
boolean	query(java.lang.String prompt) Print a prompt, then read and return a YES/NO answer from this EasyReader.
void	skipLine() Read and discard the rest of the current input line.
java.lang.String	stringInput() Read a String (up to whitespace) from this EasyReader.
java.lang.String	stringInputLine() Read a String from a complete line of this EasyReader.
java.lang.String	stringQuery(java.lang.String prompt) Print a prompt, then read and return a String from this EasyReader.

Methods inherited from class java.io.PushbackReader

close, mark, markSupported, read, read, ready, reset, skip, unread, unread, unread

Methods inherited from class java.io.Reader

read, read

Methods inherited from class java.lang.Object

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

Constructor Detail

EasyReader

public EasyReader(java.io.InputStream in)

Initialize this EasyReader so that it reads from an InputStream.

Parameters:

in - an InputStream that this EasyReader will read from

Postcondition:

This EasyReader has been initialized so that its subsequent input comes from the specified InputStream.

Example:

EasyReader stdin = new EasyReader(System.in);

EasyReader

public EasyReader(java.lang.String name)

Initialize this EasyReader so that it reads from a specified file.

Parameters:

name - the name of the file that this EasyReader will read from

Postcondition:

This EasyReader has been initialized so that its subsequent input comes from the specified file. If the file does not exist, then an error message is printed to System.err and the program exits.

Example:

EasyReader stdin = new EasyReader("foo.txt");

EasyReader

public EasyReader(java.io.InputStreamReader isr)

Initialize this EasyReader so that it reads from an InputStreamReader.

Parameters:

in - an InputStreamReader that this EasyReader will read from

Postcondition:

This EasyReader has been initialized so that its subsequent input comes from the specified InputStreamReader.

Method Detail

charInput

public char charInput()

Read a character from this EasyReader.

Parameters:

- - none

Returns:

a character that's been read

Note: This method reads and throws away whitespace. Then it reads and returns the next character. If end-of-file has been reached, then it returns ASCII value zero.

charInputLine

public char charInputLine()

Read a character from a complete line of this EasyReader.

Parameters:

- - none

Returns:

a character that's been read

Note:

This method is indentical charInput() with an added activation of skipLine() just before returning.

charQuery

public char charQuery(java.lang.String prompt)

Print a prompt, then read and return a character from this EasyReader.

Parameters:

prompt - a prompt to print

Postcondition:

The prompt has been printed to System.out. Then a character has been read and returned with charInputLine.

doubleInput

public double doubleInput()

Read a double number from this EasyReader.

Parameters:

- - none

Returns:

a double number that's been read

Input Method:

An attempt is made to read the following items into a String:

(1) Zero or more whitespace characters (which are discarded);

(2) An optional + or - sign.

(3) A sequence of digits that form the integer part of the number.

(4) If the next character is a decimal point, then it is read along with a sequence of digits that form the fractional part of the number.

(5) If the next character is 'e' or 'E', then it is read along with an optional +/- sign and digits that form the exponent part of the number.

After these items, there may be a non-digit delimiter, or the end-of-file may appear after the number. The delimiter (or EOF) is not read.

Conversion: The above items are converted to a double value using Double.valueOf.

Format Problems:

If a NumberFormatException occurs, then the method returns Double.NaN and an immediate activation of isFormatProblem() will return true.

doubleInputLine

public double doubleInputLine()

Read a double value from a complete line of this EasyReader.

Parameters:

- - none

Returns:

a double value that's been read

Note:

This method is identical doubleInput( ) with an added activation of skipLine( ) just before returning.

doubleQuery

public double doubleQuery(java.lang.String prompt)

Print a prompt, then read and return a double value from this EasyReader.

Parameters:

prompt - a prompt to print

Postcondition:

The prompt has been printed to System.out. Then a double value has been read and returned with doubleInputLine.

Format Problems:

If doubleInputLine encounters a format problem, but !isEOF(), then the user is prompted to type a new input line until a correct double value is provided. If end-of-file is reached, then the method returns Double.NaN and an immediate activation of isFormatProblem() will return true.

ignore

public void ignore()

Read and discard one character.

Parameters:

- - none

Postcondition:

One character has been read and discarded.

intInput

public int intInput()

Read an integer from this EasyReader.

Parameters:

- - none

Returns:

an integer that's been read

Format:

An attempt is made to read the following items into a String:

(1) Zero or more whitespace characters (which are discarded);

(2) An optional + or - sign.

(3) A sequence of digits that form the actual integer. There may be a non-digit delimiter after the integer, or the end-of-file may appear after the integer. The delimiter (or EOF) is not read.

Conversion: The above items are converted to an integer value using Integer.parseInt.

Format Problems:

If a NumberFormatException occurs, then the method returns Integer.MIN_VALUE and an immediate activation of isFormatProblem() will return true.

intInputLine

public int intInputLine()

Read an integer from a complete line of this EasyReader.

Parameters:

- - none

Returns:

an integer that's been read

Note:

This method is indentical intInput( ) with an added activation of skipLine( ) just before returning.

intQuery

public int intQuery(java.lang.String prompt)

Print a prompt, then read and return an integer from this EasyReader.

Parameters:

prompt - a prompt to print

Postcondition:

The prompt has been printed to System.out. Then an integer has been read and returned with intInputLine.

Format Problems:

If intInputLine encounters a format problem, but !isEOF(), then the user is prompted to type a new input line until a correct int value is provided. If end-of-file is reached, then the method returns Integer.MIN_VALUE and an immediate activation of isFormatProblem() will return true.

isEOF

public boolean isEOF()

Determine whether this EasyReader has reached the end-of-file.

Parameters:

- - none

Returns:

If this EasyReader has reached the end of file (reading all characters up to but not including EOF), then the return value is true; if an attempt to read causes an IOException, then the return value is also true; otherwise the return value is false.

Note:

A user at the keyboard indicates EOF for standard input by typing ctrl-z (MS Windows) or ctrl-c (Unix). For an interactive user, this method does pause until the user provides some input or indicates end-of-file by pressing ctrl-z.

Example:

Read one integer per line from standard input until EOF, then print the sum of all the integers:
EasyReader stdin = new EasyReader(System.in);
int sum = 0;
System.out.println("Type one int per line & press ctrl-z to end:");
while (!stdin.isEOF( ))
sum += stdin.intInputLine( );
System.out.println("Total sum: " + sum);

isEOLN

public boolean isEOLN()

Determine whether the next input character is an end-of-line.

Parameters:

- - none

Returns:

If the next input character is a newline ('\n') or carriage return ('\r'), then the return value is true; if isEOF(), then the return value is also true; if an attempt to read causes an IOException, then the return value is also true; otherwise the return value is false.

isFormatProblem

public boolean isFormatProblem()

Determine whether there was an incorrectly formatted input to the most recent input operation.

Parameters:

- - none

Returns:

A true return value indicates that the most recent activation of an input methods had an IOException OR was given input of the wrong form (such as "abc" instead of an integer). Note that the return value is applicable to only the MOST RECENT activation of these input methods:
doubleInput, intInput
doubleInputLine, intInputLine
doubleQuery, intQuery

pause

public static void pause(long milliseconds)

Make the computation pause for a specified number of milliseconds.

Parameters:

milliseconds - the number of milliseconds to pause

Postcondition:

The computation has paused for the specified time.

peek

public char peek()

Peek ahead at the next character from this EasyReader (but don't read it).

Parameters:

- - none

Returns:

The return value is the next character that will be read from this EasyReader. If there is no next character (because of the end-of-file marker), then the return value is '\0'.

query

public boolean query(java.lang.String prompt)

Print a prompt, then read and return a YES/NO answer from this EasyReader.

Parameters:

prompt - a prompt to print

Postcondition:

stringQuery(prompt) has been called to ask a question and read the answer, which is considered true if it begins with "Y" or "y" and false if it begins with "N" or "n". If the answer did not begin with a lower- or upper-case Y or N, then the process is repeated until a correct Yes/No answer is provided. If EOF is reached, then false is returned.

skipLine

public void skipLine()

Read and discard the rest of the current input line.

Parameters:

- - none

Postcondition:

Characters have been read and discarded up to and including the end of the current input line (or to the end-of-file).

stringInput

public java.lang.String stringInput()

Read a String (up to whitespace) from this EasyReader.

Parameters:

- - none

Returns:

a String that's been read

Format: Whitespace has been skipped, and then a string has been read up to but not including the next whitespace character.

stringInputLine

public java.lang.String stringInputLine()

Read a String from a complete line of this EasyReader.

Parameters:

- - none

Returns:

a String that's been read

Format: An entire line of characters has been read up to and including the end of the current line (or the end-of-file). All characters before the end are returned in a String.

stringQuery

public java.lang.String stringQuery(java.lang.String prompt)

Print a prompt, then read and return a String from this EasyReader.

Parameters:

prompt - a prompt to print

Postcondition:

The prompt has been printed to System.out. Then a String has been read and returned with stringInputLine.

main

public static void main(java.lang.String[] args)

A demonstration program. To run the demonstration:
java edu.colorado.io.EasyReader