/*::.
==================================================================================================================================
=================================================¦ Copyright © 2001 Allen Baker ¦=================================================
                                                 +------------------------------+
File:       TextWriter.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 writing of character files. A TextWriter writes text to a
character-output stream, buffering characters so as to provide efficient writing.<P>

A TextWriter is a PrintWriter that wraps a BufferedWriter. These two statements are essentially equivalent:
   <BLOCKQUOTE>
      <PRE id="unindent">
         PrintWriter out = new PrintWriter(new BufferedWriter(new OutputStreamWriter(new FileOutputStream("foo.out"))));
         TextWriter  out = new TextWriter("foo.out");
      </PRE>
   </BLOCKQUOTE>

<P>
   <DL>
      <DT>
         <B>
            Example usage:
         </B>
         <DD>
            <BLOCKQUOTE>
               <PRE id="unindent">
                  =======================================================================================
                  Use a TextWriter to write text to a text file - foo.txt.
                  ---------------------------------------------------------------------------------------
                  TextWriter myTextWriter = new TextWriter("foo.txt");
                  myTextWriter.println("a line of text");
                  myTextWriter.printf ("%s\n", "a line of text");
                  myTextWriter.flush();
                  myTextWriter.close();
               </PRE>
            </BLOCKQUOTE>
         </DD>
      </DT>
      <DT>
         <B>
            View Source:
         </B>
         <DD>
            <A href="TextWriter.java.html">
               TextWriter.java
            </A>
         </DD>
      </DT>
      <DT>
         <B>
            Author:
         </B>
         <DD>
            <A href="mailto:sourcecode.v01@cosmicabyss.com">
               Allen Baker
            </A>
         </DD>
      </DT>
   </DL>
*//*
======================================================================================================================== */
public class TextWriter extends PrintWriter
   {



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a new TextWriter, given the File to write to.

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

   @param
      pFile is the file to write to.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public TextWriter(File pFile) throws Exception
      {
      super(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(pFile), "UTF-8")));
//      super(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(pFile), "UTF-8")));
//      super(new BufferedWriter(new FileWriter(pFile)));
      XFile  xfile = new XFile(pFile);
      iCanonicalPath = xfile.getCanonicalPath();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a new TextWriter, given the name of the file to write to.

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

   @param
      pFileName is the name of the file to write to.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public <Type> TextWriter(Type pFileName) throws Exception
      {
      super(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(UString.toString(pFileName)), "UTF-8")));
//      super(new BufferedWriter(new OutputStreamWriter(new FileOutputStream(UString.toString(pFileName)), "UTF-8")));
//      super(new BufferedWriter(new FileWriter(UString.toString(pFileName))));
      XFile  xfile = new XFile(pFileName);
      iCanonicalPath = xfile.getCanonicalPath();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   Returns the canonical pathname String of this file.

   A canonical pathname is both absolute and unique. The precise definition of canonical form is
   system-dependent. This method first converts this pathname to absolute form if necessary, as if by
   invoking the getAbsolutePath() method, and then maps it to its unique form in a system-dependent
   way. This typically involves removing redundant names such as "." and ".." from the pathname,
   resolving symbolic links (on UNIX platforms), and converting drive letters to a standard case (on
   Microsoft Windows platforms).

   Every pathname that denotes an existing file or directory has a unique canonical form. Every
   pathname that denotes a nonexistent file or directory also has a unique canonical form. The
   canonical form of the pathname of a nonexistent file or directory may be different from the
   canonical form of the same pathname after the file or directory is created. Similarly, the canonical
   form of the pathname of an existing file or directory may be different from the canonical form of
   the same pathname after the file or directory is deleted.

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

   @return
      The canonical pathname String denoting the same file or directory as this file
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public String getCanonicalPath()
      {
      return iCanonicalPath;
      }



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

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

   @return
      A reference to this object

   @param
      pConsole is a ConsoleStream through which this objects sends its output.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public TextWriter 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="TextWriter.java.html#004">View source</A>

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public TextWriter 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(TextWriter.class.getName());
   private static final int      DFLT_LINE_LEN = ConsoleMessage.defaultLineLength();
   /*.
   ==========================================================================================
   Class variables
      cOut : console output.
   ------------------------------------------------------------------------------------------ */
   private static ConsoleStream  cOut = ConsoleStream.getSingleton();
   /*.
   ==========================================================================================
   Instance variables
      iCanonicalPath : absolute path name of the file
   ------------------------------------------------------------------------------------------ */
   private String  iCanonicalPath = "";



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  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.TextWriter
            </DD>
         </DT>
      </DL>

   <P><B>Implementation: </B><A HREF="TextWriter.java.html#005">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.TextWriter outputFileName"
            );
         System.exit(-1);
         }
      /*.
      ==========================================================================================
      Create an object and send its output to the ConsoleStream
      ------------------------------------------------------------------------------------------ */
      TextWriter  obj = new TextWriter(pArgs[0]);
      /*.
      ==========================================================================================
      Test code
      ------------------------------------------------------------------------------------------ */
      obj.test();
      /*.
      ==========================================================================================
      Use a TextWriter to write a line of text to a text file.
      ------------------------------------------------------------------------------------------ */
      obj.println("a line of text");
      obj.println(new XString("a line of text"));

      obj.flush();
      obj.close();
      }



   }  // class TextWriter



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