type.lang
Class UniReader

java.lang.Object
  extended by type.lang.UniReader

public class UniReader
extends java.lang.Object

A universal reader class that provides a consistent interface for reading text from disk files, URL's, or from Standard Input. Standard input is the window from which the application was launched (the command/terminal window or UniCon).

To use its services, perform the following steps in the shown order:

  1. Create an instance of the class by passing the appropriate input source to the constructor.
  2. Invoke, on the instance, one of the read methods to read from the source.
  3. Repeat the above step to read additional elements as needed (assuming they exist).
  4. Invoke, on the instance, the close() method.
There are 10 read methods. Except for readChar, and readLine, which operate in a special way, the remaining eight methods read data according to the following algorithm:

Precondition: The data is compatible with the returned type, is possibly preceded by whitespace characters, but is certainly followed by a whitespace character.

Action: Starting from the current position in the input buffer, skip over any whitespace (blank, tab, and End-Of-Line characters) and then extract a sequence of non-whitespace characters until a whitespace character is reached. Attempt to interpret the extracted sequence (excluding the terminal whitespace) as representing a value of the method's return type. If the attempt is successful, return the interpreted value, otherwise, throw an exception.

The readLine method does not skip over leading whitespace. Instead, it reads all characters from the current position to the next EOL (End-Of-Line) and return them, excluding EOL, as a string.

The readChar method also does not skip over leading whitespace and should be considered as a low-level input service: It reads one character from the current position and returns it. Hence, it gives you full control over input and its interpretation and allows you to read whitespace as well as EOL.

Note:
The End-of-Line (EOL) marker is made up of a one character ('\n') under Unix, and of two ('\r\n') under Windows (you may have noticed that when you transfer a text file, from a PC to Unix system using binary-mode ftp, an extra ^M appears in each line - this is the '\r' character). To maintain platform independence, this class always consumes the '\r' so that EOL is always made up of one character.

Example 1:
Suppose we want to read the content of the file "Text", which contains text (the example in the UniWriter class shows how this file was created). Since we don't know, a priori, how many records are in the file, we have to depend on the eof() method to know when to stop reading. Note that depending on reading an empty or null string is not the proper way to do this. Note also that since eof is meaningful after we read at least once, we must first read and then check it. This is ideally done in the first clause of a for loop:

 import type.lang.*;

 public class ReadText
 {  public static void main (String[] args)
    {  //--------------------------------Open the File:
       UniReader ur = new UniReader("Text");
       for (String record = ur.readLine(); !ur.eof(); record = ur.readLine())
       {  //-----------------------------Process the data
          // e.g. IO.println(record);
       }
       //-------------------------------Close the file:
       ur.close();
    }
 }
Note that when eof() returns true, we must ignore the value returned by read and exit the loop, and that is exactly what happens in the last iteration of the loop. If the file exists but is empty, the loop body doesn't execute at all and, hence, the program works as expected.

Example 2:
Suppose we want to read the content of the file "Mixed" which is known to contain, in each record, a number (an int) and its square root (a double), separated by whitespace (the example in the UniWriter class shows how this file was created). Since we don't know, a priori, how many records are in the file, we have to depend on the eof() method to know when to stop reading.

 import type.lang.*;
 public class ReadMixed
 {  public static void main (String[] args)
    {  //--------------------------------Open the File:
       UniReader ur = new UniReader("Mixed");
       for (int number = ur.readInt(); !ur.eof(); number = ur.readInt())
       {  double root = ur.readDouble();
          //---------------------------Process the read data:
          // output and/or process
          // number and root.
       }
       //-------------------------------Close the file:
       ur.close();
    }
 }

Version:
3.0 (Summer 2000), 3.5 (Summer 2001), 4.0 (Summer 2002)
Author:
H. Roumani, roumani@cs.yorku.ca

Constructor Summary
UniReader()
          Create an instance connected to Standard Input.
UniReader(java.lang.String source)
          Create an instance connected to the passed source for subsequent reading.
 
Method Summary
 void close()
          Removes the connection between the source and this instance thereby freeing any reserved resources.
 boolean eof()
          Indicates whether the End-Of-File marker of this instance has been reached.
 boolean readBoolean()
          Reads and returns a boolean from this instance.
 byte readByte()
          Reads and returns a byte from this instance.
 char readChar()
          Reads and returns a character from this instance.
 double readDouble()
          Reads and returns a double from this instance.
 float readFloat()
          Reads and returns a float from this instance.
 int readInt()
          Reads and returns an int from this instance.
 java.lang.String readLine()
          Attempts to read and return a record from this instance.
 long readLong()
          Reads and returns a long from this instance.
 short readShort()
          Reads and returns a short from this instance.
 java.lang.String readWord()
          Reads and returns a word from this instance.
 java.lang.String toString()
          Return a string representation of this reader.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

UniReader

public UniReader(java.lang.String source)
Create an instance connected to the passed source for subsequent reading.

Parameters:
source - can be:
  • The name [and path] of a disk file. Use '/' in the path under Unix and '\' under Windows. Note that you will need two backslashes '\\' if the path is a string literal. If the embedded path is relative then it is considered relative to the working directory specified in IO.workingDir.
  • A URL address. The address must begin with the prefix: http://.
  • The null string. In this case, subsequent input will be from Standard Output; the window from which the application was launched.
Throws:
java.lang.RuntimeException - with message: File/Path not found! if the file (or path) doesn't exist.
java.lang.RuntimeException - with message: File cannot be opened for reading! if the file cannot be read from; e.g. read-protected.
java.lang.RuntimeException - with message: Invalid URL! if the passed URL is not valid.

UniReader

public UniReader()
Create an instance connected to Standard Input. This convenience constructor has the same effect as passing null to the 1-argument constructor.

Method Detail

toString

public java.lang.String toString()
Return a string representation of this reader.

Overrides:
toString in class java.lang.Object
Returns:
the string "A UniReader connected to: " followed by the data source on which the instance was constructed.

eof

public boolean eof()
Indicates whether the End-Of-File marker of this instance has been reached. If this is a keyboard instance, there will be no end-of-file marker (because the read methods will block until an input is made).

Note: For non-keyboard instances, the application must check eof() after each read. If found true then the return of the read method should be discarded and no further read attempts should be made.

Returns:
true if the end-of-file marker was encountered during the last read;
false otherwise.

close

public void close()
Removes the connection between the source and this instance thereby freeing any reserved resources.

Throws:
java.lang.RuntimeException - with message: File cannot be closed! if the close failed.

readChar

public char readChar()
Reads and returns a character from this instance. Reads the character at the current position in the the input buffer. If it is a carriage_return, then the method skips it and reads the next character.

Returns:
the read character as a char if it is not the End-Of-File marker. Otherwise, is returned and eof() is set to true.
Throws:
java.lang.RuntimeException - with message: Reading past end-of-file! if @link #eof()} was true prior to the call.
java.lang.RuntimeException - with message: Reading error! if an error was encountered while reading.

readWord

public java.lang.String readWord()
Reads and returns a word from this instance. Skips over any whitespace, reads a sequence of non- whitespace characters until a whitespace character is reached.

Returns:
the read sequence, excluding the terminal whitespace, as a String. If no such sequence is available, null is returned and eof() is set to true.
Throws:
java.lang.RuntimeException - with message: Reading past end-of-file! if eof() was true prior to the call.
java.lang.RuntimeException - with message: Reading error! if an error was encountered while reading.

readByte

public byte readByte()
Reads and returns a byte from this instance. Skips over any whitespace, reads a sequence of non- whitespace characters until a whitespace character is reached. For the sequence to represent a byte, it must be made up of digits, optionally preceded by a sign, and must have a numeric value within the range of byte.

Returns:
the byte value of the read sequence. If no such sequence is available, 0 is returned and eof() is set to true.
Throws:
java.lang.RuntimeException - with message: Reading past end-of-file! if eof() was true prior to the call.
java.lang.RuntimeException - with message: Reading error! if an error was encountered while reading.
java.lang.NumberFormatException - if the content of the read sequence does not represent a byte.

readShort

public short readShort()
Reads and returns a short from this instance. Skips over any whitespace, reads a sequence of non- whitespace characters until a whitespace character is reached. For the sequence to represent a short, it must be made up of digits, optionally preceded by a sign, and must have a numeric value within the range of short.

Returns:
the short value of the read sequence. If no such sequence is available, 0 is returned and eof() is set to true.
Throws:
java.lang.RuntimeException - with message: Reading past end-of-file! if eof() was true prior to the call.
java.lang.RuntimeException - with message: Reading error! if an error was encountered while reading.
java.lang.NumberFormatException - if the content of the read sequence does not represent a short.

readInt

public int readInt()
Reads and returns an int from this instance. Skips over any whitespace, reads a sequence of non- whitespace characters until a whitespace character is reached. For the sequence to represent an int, it must be made up of digits, optionally preceded by a sign, and must have a numeric value within the range of int.

Returns:
the int value of the read sequence. If no such sequence is available, 0 is returned and eof() is set to true.
Throws:
java.lang.RuntimeException - with message: Reading past end-of-file! if eof() was true prior to the call.
java.lang.RuntimeException - with message: Reading error! if an error was encountered while reading.
java.lang.NumberFormatException - if the content of the read sequence does not represent an int.

readLong

public long readLong()
Reads and returns a long from this instance. Skips over any whitespace, reads a sequence of non- whitespace characters until a whitespace character is reached. For the sequence to represent a long, it must be made up of digits, optionally preceded by a sign, and must have a numeric value within the range of long.

Returns:
the long value of the read sequence. If no such sequence is available, 0 is returned and eof() is set to true.
Throws:
java.lang.RuntimeException - with message: Reading past end-of-file! if eof() was true prior to the call.
java.lang.RuntimeException - with message: Reading error! if an error was encountered while reading.
java.lang.NumberFormatException - if the content of the read sequence does not represent a long.

readFloat

public float readFloat()
Reads and returns a float from this instance. Skips over any whitespace, reads a sequence of non- whitespace characters until a whitespace character is reached. For the sequence to represent a float, it must be made up of digits, optionally preceded by a sign, a decimal point, an optional exponent prefixed by the letter E or e, and must have a numeric value within the range of float.

Returns:
the float value of the read sequence. If no such sequence is available, 0 is returned and eof() is set to true.
Throws:
java.lang.RuntimeException - with message: Reading past end-of-file! if eof() was true prior to the call.
java.lang.RuntimeException - with message: Reading error! if an error was encountered while reading.
java.lang.NumberFormatException - if the content of the read sequence does not represent a float.

readDouble

public double readDouble()
Reads and returns a double from this instance. Skips over any whitespace, reads a sequence of non- whitespace characters until a whitespace character is reached. For the sequence to represent a double, it must be made up of digits, optionally preceded by a sign, a decimal point, an optional exponent prefixed by the letter E or e, and must have a numeric value within the range of double.

Returns:
the double value of the read sequence. If no such sequence is available, 0 is returned and eof() is set to true.
Throws:
java.lang.RuntimeException - with message: Reading past end-of-file! if eof() was true prior to the call.
java.lang.RuntimeException - with message: Reading error! if an error was encountered while reading.
java.lang.NumberFormatException - if the content of the read sequence does not represent a double.

readBoolean

public boolean readBoolean()
Reads and returns a boolean from this instance. Skips over any whitespace, reads a sequence of non- whitespace characters until a whitespace character is reached.

Returns:
true if the read sequence is "true" (case-insensitive), and false otherwise. If no such sequence is available, false is returned and eof() is set to true.
Throws:
java.lang.RuntimeException - with message: Reading past end-of-file! if eof() was true prior to the call.
java.lang.RuntimeException - with message: Reading error! if an error was encountered while reading.

readLine

public java.lang.String readLine()
Attempts to read and return a record from this instance. See the example in the class description above on how to correctly capture the end-of-file condition in a loop.
If the eof() state was true prior to invoking this method, a runtime error occurs.

Otherwise, starting from the current position in the input buffer, this method extracts characters, catenating them into the return string, until an End-Of-Line marker (EOL), or the End-Of-File marker (EOF) is encountered.

If EOL was encountered, it is extracted (i.e. the position in the input buffer is advanced to one character beyond the EOL) but not catenated and the string is returned. It is possible (if there are empty records) that two or more EOL markers occur in sequence. In this case the position in the buffer at the start of the read is already at an EOL. The EOL is encountered immediately, extracted (but not catenated), the position is advanced, and a zero-length string is returned.

If EOF was encountered, then it is not extracted (i.e. the position in the input buffer is left at the EOF) and the length of the catenated string is examined:

Returns:
a string computed according to the above algorithm.
Throws:
java.lang.RuntimeException - with message: Reading past end-of-file! if eof() was true prior to invoking this method.
java.lang.RuntimeException - with message: Reading error! if an error was encountered while reading.


Java by Abstraction: A Client-View Approach