/*::.
==================================================================================================================================
=================================================¦ Copyright © 2001 Allen Baker ¦=================================================
                                                 +------------------------------+
File:       TextReader.java
Originator: Allen Baker (2001.09.02)
LayoutRev:  5
================================================================================================================================== */



/*.
==========================================================================================
Package
------------------------------------------------------------------------------------------ */
package cosmicabyss.com.lib;



/*.
==========================================================================================
Imports
------------------------------------------------------------------------------------------ */
import java.io.*;
import java.util.*;



/*::
======================================================================================================================== *//**
Instances of this class are convenience objects for buffered reading of character files. A TextReader reads text from a
character-input stream, buffering characters so as to provide efficient reading.<P>

Creating a TextReader is equivalent to wrapping a FileReader in a BufferedReader with the exception that the TextReader
readLine() method returns an XString instead of a String. These two statements are [almost] equivalent:
   <BLOCKQUOTE>
      <PRE id="unindent">
         BufferedReader in = new BufferedReader(new FileReader("foo.in"));
         TextReader     in = new TextReader("foo.in");
      </PRE>
   </BLOCKQUOTE>

<P>
   <DL>
      <DT>
         <B>
            Example usage:
         </B>
         <DD>
            <BLOCKQUOTE>
               <PRE id="unindent">
                  =========================================================================================
                  Use a TextReader to copy the contents of a text file - foo.txt - to
                  stdout.
                  -----------------------------------------------------------------------------------------
                  TextReader myTextReader = new TextReader("foo.txt");

                  XString s;
                  while ((s = myTextReader.readLine()) != null)
                     {
                     System.out.println(s);
                     }

                  myTextReader.close();
               </PRE>
            </BLOCKQUOTE>
         </DD>
      </DT>
      <DT>
         <B>
            View Source:
         </B>
         <DD>
            <A href="TextReader.java.html">
               TextReader.java
            </A>
         </DD>
      </DT>
      <DT>
         <B>
            Author:
         </B>
         <DD>
            <A href="mailto:sourcecode.v01@cosmicabyss.com">
               Allen Baker
            </A>
         </DD>
      </DT>
   </DL>
*//*
======================================================================================================================== */
public class TextReader
   {



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a new TextReader, given the File to read from.

   <P><B>Implementation: </B><A HREF="TextReader.java.html#000">View source</A>

   @param
      pFile is the file to read from.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public TextReader(File pFile) throws IOException
      {
      iIn = new BufferedReader(new InputStreamReader(new FileInputStream(pFile), "UTF-8"));
//      iIn = new BufferedReader(new FileReader(pFile));
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a new TextReader, given an InputStream (such as System.in) to read from.

   <P><B>Implementation: </B><A HREF="TextReader.java.html#001">View source</A>

   @param
      pInputStream is the InputStream to read from.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public TextReader(InputStream pInputStream) throws IOException
      {
      iIn = new BufferedReader(new InputStreamReader(pInputStream, "UTF-8"));
//      iIn = new BufferedReader(new InputStreamReader(pInputStream));
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a new TextReader, given the name of the file to read from.

   <P><B>Implementation: </B><A HREF="TextReader.java.html#002">View source</A>

   @param
      pFileName is the name of the file to read from.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public <Type> TextReader(Type pFileName) throws IOException
      {
      iIn = new BufferedReader(new InputStreamReader(new FileInputStream(UString.toString(pFileName)), "UTF-8"));
//      iIn = new BufferedReader(new FileReader(UString.toString(pFileName)));
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API BufferedReader Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/io/BufferedReader.html">
         View JDK SE API BufferedReader Class
      </A>

   <P><B>Implementation: </B><A HREF="TextReader.java.html#003">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void close() throws Exception
      {
      iIn.close();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API BufferedReader Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/io/BufferedReader.html">
         View JDK SE API BufferedReader Class
      </A>

   <P><B>Implementation: </B><A HREF="TextReader.java.html#004">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void mark(int readAheadLimit) throws Exception
      {
      iIn.mark(readAheadLimit);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API BufferedReader Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/io/BufferedReader.html">
         View JDK SE API BufferedReader Class
      </A>

   <P><B>Implementation: </B><A HREF="TextReader.java.html#005">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public boolean markSupported()
      {
      return iIn.markSupported();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API BufferedReader Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/io/BufferedReader.html">
         View JDK SE API BufferedReader Class
      </A>

   <P><B>Implementation: </B><A HREF="TextReader.java.html#006">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public int read() throws Exception
      {
      return iIn.read();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API BufferedReader Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/io/BufferedReader.html">
         View JDK SE API BufferedReader Class
      </A>

   <P><B>Implementation: </B><A HREF="TextReader.java.html#007">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public int read(char[] cbuf, int off, int len) throws Exception
      {
      return iIn.read(cbuf, off, len);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API BufferedReader Class documentation except that this method returns an XString instead of a
   String.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/io/BufferedReader.html">
         View JDK SE API BufferedReader Class
      </A>

   <P><B>Implementation: </B><A HREF="TextReader.java.html#008">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public XString readLine() throws Exception
      {
      String s = iIn.readLine();

      return (s==null)? null : new XString(s);
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API BufferedReader Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/io/BufferedReader.html">
         View JDK SE API BufferedReader Class
      </A>

   <P><B>Implementation: </B><A HREF="TextReader.java.html#009">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public boolean ready() throws Exception
      {
      return iIn.ready();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API BufferedReader Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/io/BufferedReader.html">
         View JDK SE API BufferedReader Class
      </A>

   <P><B>Implementation: </B><A HREF="TextReader.java.html#010">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void reset() throws Exception
      {
      iIn.reset();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   The description of this method is the same as the one for the method of the same name in the JDK SE
   API BufferedReader Class documentation.<P>

      <B>
         Documentation:
      </B>
       <A HREF="http://docs.oracle.com/javase/8/docs/api/java/io/BufferedReader.html">
         View JDK SE API BufferedReader Class
      </A>

   <P><B>Implementation: </B><A HREF="TextReader.java.html#011">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public long skip(long n) throws Exception
      {
      return iIn.skip(n);
      }


   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method sets the ConsoleStream for this object.

   <P><B>Implementation: </B><A HREF="TextReader.java.html#012">View source</A>

   @return
      A reference to this object

   @param
      pConsole is a ConsoleStream through which this objects sends its output.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public TextReader setOut(ConsoleStream pConsole)
      {
      cOut = pConsole;
      return this;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This boilerplate method is used for testing an instantiated object of this class and may include any
   code the developer chooses.

   <P><B>Implementation: </B><A HREF="TextReader.java.html#013">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public TextReader test() throws Exception
      {
      cOut.titledPrintf
         (
         "\"HELLO WORLD!\"",
         "%s  %s  %s",
         "I'm an object of the", CLASS_NAME, "class, and I approved this message."
         );
      return this;
      }



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Protected  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Private  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



   /*.
   ==========================================================================================
   Class Constants
      CLASS_NAME:
         The name of this class
      DFLT_LINE_LEN:
         The default line length for word wrapping
   ------------------------------------------------------------------------------------------ */
   private static final XString  CLASS_NAME    = new XString(TextReader.class.getName());
   private static final int      DFLT_LINE_LEN = ConsoleMessage.defaultLineLength();
   /*.
   ==========================================================================================
   Class variables
      cOut : console output.
   ------------------------------------------------------------------------------------------ */
   private static ConsoleStream  cOut = ConsoleStream.getSingleton();
   /*.
   ==========================================================================================
   Instance variables
   ------------------------------------------------------------------------------------------ */
   private BufferedReader iIn  = null;



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Inner Classes  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Public Static Methods  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method allows this class file to be unit tested as a standalone application. It's the method
   that's called when the class is invoked from the command line by using the java application launcher
   - "java". Main() is not a required method, but the practice of putting one in each class and
   wrapping class test code within it allows easy unit testing of the class; and main does not need to
   be removed when testing is complete.

   <P>
      <DL>
         <DT>
            <B>
               Command line usage:
            </B>
            <DD>
               Java cosmicabyss.com.lib.TextReader
            </DD>
         </DT>
      </DL>

   <P><B>Implementation: </B><A HREF="TextReader.java.html#014">View source</A>

   @param
      pArgs contains the command line arguments with which this class was invoked as an application.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static void main(String[] pArgs) throws Exception
      {
      /*.
      ==========================================================================================
      Greetings !
      ------------------------------------------------------------------------------------------ */
      cOut.banner(CLASS_NAME);
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      if (pArgs.length < 1)
         {
         cOut.println
            (
            "usage: java cosmicabyss.com.lib.TextReader inputFileName"
            );
         System.exit(-1);
         }
      /*.
      ==========================================================================================
      Create an object and send its output to the ConsoleStream
      ------------------------------------------------------------------------------------------ */
      TextReader  obj = new TextReader(pArgs[0]);
      /*.
      ==========================================================================================
      Test code
      ------------------------------------------------------------------------------------------ */
      obj.test();
      cOut.setLineLength(1000);
      /*.
      ==========================================================================================
      Use a TextReader to copy the contents of a text file to stdout.
      ------------------------------------------------------------------------------------------ */
      XString s;
      while ((s = obj.readLine()) != null)
         {
         cOut.println(s);
         }

      obj.close();
      }



   }  // class TextReader



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Notes  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */