/*::.
==================================================================================================================================
=================================================¦ Copyright © 2008 Allen Baker ¦=================================================
                                                 +------------------------------+
File:       JavaFileV4.java
Originator: Allen Baker (2008.12.13 14:14)
LayoutRev:  5
================================================================================================================================== */



package cosmicabyss.com.lib;

import java.io.*;
import java.util.*;



/*::
======================================================================================================================== *//**
Instances of this class are TextFiles containing Java source code formatted in layout version 4.

<P>
   <DL>
      <DT>
         <B>
            Example usage:
         </B>
         <DD>
            <BLOCKQUOTE>
               <PRE id="unindent">
                  no example provided
               </PRE>
            </BLOCKQUOTE>
         </DD>
      </DT>
      <DT>
         <B>
            View Source:
         </B>
         <DD>
            <A href="JavaFileV4.java.html">
               JavaFileV4.java
            </A>
         </DD>
      </DT>
      <DT>
         <B>
            Author:
         </B>
         <DD>
            <A href="mailto:sourcecode.v01@cosmicabyss.com">
               Allen Baker
            </A>
         </DD>
      </DT>
   </DL>
*//*
======================================================================================================================== */
public class JavaFileV4 extends JavaFileBase
   {



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Public Classes, Constants, and Variables  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Public Inner Classes  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Public Class Constants  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Public Class Variables  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Public Instance Constants  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Public Instance Variables  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Protected Classes, Constants, and Variables  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Protected Inner Classes  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Protected Class Constants  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Protected Class Variables  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Protected Instance Constants  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Protected Instance Variables  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Private Classes, Constants, and Variables  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Private Inner Classes  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  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(JavaFileV4.class.getName());
   private static final int      DFLT_LINE_LEN = ConsoleMessage.defaultLineLength();



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Private Class Variables  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*.
   ==========================================================================================
   cOut : console output.
   ------------------------------------------------------------------------------------------ */
   private static ConsoleStream  cOut = ConsoleStream.getSingleton();



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Private Instance Constants  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Private Instance Variables  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



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



   static
      {
      /*.
      ==========================================================================================
      Make sure all the class constants and variables are initialized the first time the JVM
      loads this class code and before anything else in this class is accessed
      ------------------------------------------------------------------------------------------ */
      initializeClassConstantsAndVariables();
      }



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



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Private Constructors  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Private Instance Methods  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method initializes all the instance constants and variables

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   private boolean initializeInstanceConstantsAndVariables() throws Exception
      {
      boolean  successCode = true;

      if (successCode)
         {
         }
      return successCode;
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method puts a bookmark at the top of each method that has a method header comment block. It
   also puts an html link to that bookmark after the description portion of the method header comment.

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   private void bookmarkMethods() throws Exception
      {
      /*.
      ==========================================================================================
      We'll output the processed version of the file to a temp file so if the process fails
      midway through, we don't corrupt the original file
      ------------------------------------------------------------------------------------------ */
      File  iFile = new File(this.getCanonicalPath());
      File  oFile = File.createTempFile("bookmarkMethods-",".tmp");
      /*.
      ==========================================================================================
      Process the file
      ------------------------------------------------------------------------------------------ */
      bookmarkMethods
         (
         iFile.getName(),
         iFile.getCanonicalPath(),
         oFile.getCanonicalPath()
         );
      /*.
      ==========================================================================================
      Delete the original file
      ------------------------------------------------------------------------------------------ */
      if ( ! iFile.delete())
         {
         throw new Exception("Cannot delete " + iFile.getCanonicalPath());
         }
      /*.
      ==========================================================================================
      And replace it with the processed file.
      ------------------------------------------------------------------------------------------ */
      if ( ! oFile.renameTo(iFile))
         {
         throw new Exception("Cannot rename " + oFile.getCanonicalPath());
         }
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replicates the usage and description text within a source file.

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   private void replicateDescriptionAndUsageText() throws Exception
      {
      /*.
      ==========================================================================================
      We'll output the processed version of the file to a temp file so if the process fails
      midway through, we don't corrupt the original file
      ------------------------------------------------------------------------------------------ */
      File  iFile = new File(this.getCanonicalPath());
      File  oFile = File.createTempFile("replicateDescriptionAndUsageText-",".tmp");
      /*.
      ==========================================================================================
      Process the file
      ------------------------------------------------------------------------------------------ */
      replicateDescriptionAndUsageText
         (
         iFile.getCanonicalPath(),
         oFile.getCanonicalPath()
         );
      /*.
      ==========================================================================================
      Delete the original file
      ------------------------------------------------------------------------------------------ */
      if ( ! iFile.delete())
         {
         throw new Exception("Cannot delete " + iFile.getCanonicalPath());
         }
      /*.
      ==========================================================================================
      And replace it with the processed file.
      ------------------------------------------------------------------------------------------ */
      if ( ! oFile.renameTo(iFile))
         {
         throw new Exception("Cannot rename " + oFile.getCanonicalPath());
         }
      }



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Private Class Methods  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method initializes all the class constants and variables

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   private static void initializeClassConstantsAndVariables()
      {
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method puts a bookmark at the top of each method that has a method header comment block. It
   also puts an html link to that bookmark after the description portion of the method header comment.

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

   @param
      pJavaFileName is the name of the java file that is being processed.
   @param
      pFileIn is the name of the file that will be copied to the output file with the lines
      preprocessed.
         pFileOut must not be the same as pFileIn. PFileOut and pFileIn must not be null.
   @param
      pFileOut is the name that will be given to the file that is produced.
         pFileOut must not be the same as pFileIn. PFileOut and pFileIn must not be null.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   private static <Type1,Type2,Type3> void bookmarkMethods
      (
      Type1  pJavaFileName,
      Type2  pFileIn,
      Type3  pFileOut
      )
      throws Exception
      {
      /*.
      ==========================================================================================
      Check the parameters.
      ------------------------------------------------------------------------------------------ */
      if (pFileIn == null)
         {
         throw new Exception("pFileIn is null");
         }
      if (pFileOut == null)
         {
         throw new Exception("pFileOut is null");
         }
      if (pFileIn.equals(pFileOut))
         {
         throw new Exception("pFileIn and pFileOut are the same file");
         }
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      XString  fileIn  = new XString(pFileIn);
      XString  fileOut = new XString(pFileOut);
      /*.
      ==========================================================================================
      Set up the files
      ------------------------------------------------------------------------------------------ */
      XStringsIterator  iter   = new XStringsIterator(fileIn);
      TextWriter        output = new TextWriter(fileOut);
      /*.
      ==========================================================================================
      Search the input file for places to put the html links to individual methods
      ------------------------------------------------------------------------------------------ */
      int      algoNum    = 0;
      XString  algoNumStr = null;
      XString  prefix     = null;
      boolean  inHeader   = false;
      XString  lineBack3  = null;
      XString  lineBack2  = null;
      XString  lineBack1  = null;
      XString  lineThis   = null;
      XString  lineAhead1 = null;
      XString  lineAhead2 = null;
      XString  lineAhead3 = null;
      while (iter.hasNext())
         {
         /*.
         ==========================================================================================
         If we're inside of a method header javadoc comment, search for the end of the description
         portion of the comment and put an html link there for jumping to that method from the
         javadoc page
         ------------------------------------------------------------------------------------------ */
         if ((inHeader) && (lineBack1 != null))
            {
            ifb>
               (
                  (lineBack1.trim().startsWith("<P><B>Implementation:"))  ||
                  (lineBack1.trim().startsWith("*//*"))                           ||
                  (lineBack1.trim().startsWith("@return"))                        ||
                  (lineBack1.trim().startsWith("@param"))
               )
               {
               if ( ! lineBack2.trim().equals(""))
                  {
                  output.println();
                  }
               int  ref = algoNum - 1;
               output.println
                  (
                  prefix                                            +
                  "<P><B>Implementation: </B><A HREF=\"" +
                  UString.toString(pJavaFileName)                   +
                  ".html#"                                          +
                  algoNumStr                                        +
                  "\">View source</A>"
                  );
               if ( ! lineThis.trim().equals(""))
                  {
                  output.println();
                  }
               inHeader = false;
               }
            }
         /*.
         ==========================================================================================
         If we run across a method header, put a bookmark there that will be pointed to by the html
         link.
         ------------------------------------------------------------------------------------------ */
         ifb>
            (
               ((lineBack1  != null) && (lineBack1.trim().startsWith ("/*"   )))  &<_AMP_AMP_COLON_>
               ((lineThis   != null) && (lineThis.trim().startsWith  ("=="   )))  &<_AMP_AMP_COLON_>
               ((lineAhead1 != null) && (lineAhead1.trim().startsWith("=="   )))  &<_AMP_AMP_COLON_>
               ((lineAhead2 != null) && (lineAhead2.trim().endsWith  ("*//**")))
            )
            {
            prefix     = lineBack1.whitespacePrefix();
            algoNumStr = new XString
               (
                  ((algoNum < 100)? "0" : "")  +
                  ((algoNum <  10)? "0" : "")  +
                  algoNum
               );
            inHeader = true;
            lineBack1 = new XString(prefix + "/*:                                           + algoNumStr + "">");

            algoNum++;
            }
         /*.
         ==========================================================================================
         This prevents an additional copy of the html link from accumulating in the javadoc comment
         each time this method is run on the input file.
         ------------------------------------------------------------------------------------------ */
         if (lineBack1 != null)
            {
            if ( ! lineBack1.trim().startsWith("<P><B>Implementation:"))
               {
               output.println(lineBack1);
               }
            }
         lineBack3  = lineBack2;
         lineBack2  = lineBack1;
         lineBack1  = lineThis;
         lineThis   = lineAhead1;
         lineAhead1 = lineAhead2;
         lineAhead2 = lineAhead3;
         lineAhead3 = iter.next();
         }
      /*.
      ==========================================================================================
      Drain the queue of lines that were read from the input file by writing them to the output
      file.
      ------------------------------------------------------------------------------------------ */
      if (lineBack1 != null)
         {
         if ( ! lineBack1.trim().startsWith("<P><B>Implementation:"))
            {
            output.println(lineBack1);
            }
         }
      if (lineThis != null)
         {
         if ( ! lineThis.trim().startsWith("<P><B>Implementation:"))
            {
            output.println(lineThis);
            }
         }
      if (lineAhead1 != null)
         {
         if ( ! lineAhead1.trim().startsWith("<P><B>Implementation:"))
            {
            output.println(lineAhead1);
            }
         }
      if (lineAhead2 != null)
         {
         if ( ! lineAhead2.trim().startsWith("<P><B>Implementation:"))
            {
            output.println(lineAhead2);
            }
         }
      if (lineAhead3 != null)
         {
         if ( ! lineAhead3.trim().startsWith("<P><B>Implementation:"))
            {
            output.println(lineAhead3);
            }
         }
      /*.
      ==========================================================================================
      Flush the output buffers
      ------------------------------------------------------------------------------------------ */
      output.flush();
      /*.
      ==========================================================================================
      Close the files
      ------------------------------------------------------------------------------------------ */
      output.close();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method replicates the usage and description text within a source file.

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

   @param
      pFileIn is the name of the file that will be copied to the output file with the lines
      preprocessed.
         pFileOut must not be the same as pFileIn. PFileOut and pFileIn must not be null.
   @param
      pFileOut is the name that will be given to the file that is produced.
         pFileOut must not be the same as pFileIn. PFileOut and pFileIn must not be null.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   private static <Type1,Type2> void replicateDescriptionAndUsageText
      (
      Type1  pFileIn,
      Type2  pFileOut
      )
      throws Exception
      {
      /*.
      ==========================================================================================
      Check the parameters.
      ------------------------------------------------------------------------------------------ */
      if (pFileIn == null)
         {
         throw new Exception("pFileIn is null");
         }
      if (pFileOut == null)
         {
         throw new Exception("pFileOut is null");
         }
      if (pFileIn.equals(pFileOut))
         {
         throw new Exception("pFileIn and pFileOut are the same file");
         }
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      XString  fileIn  = new XString(pFileIn);
      XString  fileOut = new XString(pFileOut);
      /*.
      ==========================================================================================
      Set up the files
      ------------------------------------------------------------------------------------------ */
      XStringsIterator  iter   = new XStringsIterator(fileIn);
      TextWriter        output = new TextWriter(fileOut);
      /*.
      ==========================================================================================
      Read the input file to find the description and usage definitions and cache them. The
      definitions are EXPECTED to come before any uses of the definitions in the file.
      ------------------------------------------------------------------------------------------ */
      boolean             inDescDef  = false;
      boolean             descDefd   = false;
      boolean             inUsageDef = false;
      boolean             usageDefd  = false;
      ArrayList<XString>  usage      = new ArrayList<XString>();
      ArrayList<XString>  desc       = new ArrayList<XString>();
      while (iter.hasNext())
         {
         XString  line        = iter.next();
         XString  trimmedLine = line.trim();
         /*.
         ==========================================================================================
         Cache description definition
         ------------------------------------------------------------------------------------------ */
         if (( ! descDefd) && (trimmedLine.startsWith("Description<PRE>")))
            {
            output.println(line);
            inDescDef = true;
            }
         else if (inDescDef)
            {
            output.println(line);
            if (trimmedLine.startsWith("</PRE>"))
               {
               inDescDef = false;
               descDefd  = true;
               }
            else
               {
               desc.add(line);
               }
            }
         /*.
         ==========================================================================================
         Cache usage definition
         ------------------------------------------------------------------------------------------ */
         else if (( ! usageDefd) && (trimmedLine.startsWith("Usage<PRE>")))
            {
            output.println(line);
            inUsageDef = true;
            }
         else if (inUsageDef)
            {
            output.println(line);
            if (trimmedLine.startsWith("</PRE>"))
               {
               inUsageDef = false;
               usageDefd  = true;
               }
            else
               {
               usage.add(line);
               }
            }
         /*.
         ==========================================================================================
         Just echo all other lines to the output file
         ------------------------------------------------------------------------------------------ */
         else
            {
            output.println(line);
            }
         /*.
         ==========================================================================================
         When BOTH the definitions are found and cached, break out of this loop and begin looking
         for uses of the definitions.
         ------------------------------------------------------------------------------------------ */
         if (descDefd && usageDefd) break;
         }
      /*.
      ==========================================================================================
      Continue reading the input file and find all the uses of the description and usage
      definitions and replace whatever is already there with the cached definitions
      ------------------------------------------------------------------------------------------ */
      boolean inDescCmt  = false;
      boolean inUsageCmt = false;
      boolean inDescStr  = false;
      boolean inUsageStr = false;
      while (iter.hasNext())
         {
         XString  line        = iter.next();
         XString  trimmedLine = line.trim();
         /*.
         ==========================================================================================
         Use the description definition in comment blocks
         ------------------------------------------------------------------------------------------ */
         if (trimmedLine.startsWith("Description<PRE>"))
            {
            output.println(line);
            for (XString s : desc)
               {
               output.println(s);
               }
            inDescCmt = true;
            }
         else if (inDescCmt)
            {
            if (trimmedLine.startsWith("</PRE>"))
               {
               output.println(line);
               inDescCmt = false;
               }
            }
         /*.
         ==========================================================================================
         Use the usage definition in comment blocks
         ------------------------------------------------------------------------------------------ */
         else if (trimmedLine.startsWith("Usage<PRE>"))
            {
            output.println(line);
            for (XString s : usage)
               {
               output.println(s);
               }
            inUsageCmt = true;
            }
         else if (inUsageCmt)
            {
            if (trimmedLine.startsWith("</PRE>"))
               {
               output.println(line);
               inUsageCmt = false;
               }
            }
         /*.
         ==========================================================================================
         Use the description definition in string blocks
         ------------------------------------------------------------------------------------------ */
         else if (trimmedLine.startsWith("// <Description>"))
            {
            output.println(line);
            for (XString s : desc)
               {
               output.println("      \"" + s.trimLeft("   ").alignLeft(117,' ').concat("\\n\" +"));
               }
            inDescStr = true;
            }
         else if (inDescStr)
            {
            if (trimmedLine.startsWith("\"\"// </Description>"))
               {
               output.println(line);
               inDescStr = false;
               }
            }
         /*.
         ==========================================================================================
         Use the usage definition in string blocks
         ------------------------------------------------------------------------------------------ */
         else if (trimmedLine.startsWith("// <Usage>"))
            {
            output.println(line);
            for (XString s : usage)
               {
               output.println("      \"" + s.trimLeft("   ").alignLeft(117,' ').concat("\\n\" +"));
               }
            inUsageStr = true;
            }
         else if (inUsageStr)
            {
            if (trimmedLine.startsWith("\"\"// </Usage>"))
               {
               output.println(line);
               inUsageStr = false;
               }
            }
         /*.
         ==========================================================================================
         Just echo all other lines to the output file
         ------------------------------------------------------------------------------------------ */
         else
            {
            output.println(line);
            }
         }
      /*.
      ==========================================================================================
      Flush the output buffers
      ------------------------------------------------------------------------------------------ */
      output.flush();
      /*.
      ==========================================================================================
      Close the files
      ------------------------------------------------------------------------------------------ */
      output.close();
      }



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



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Protected Constructors  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Protected Instance Methods  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Protected Class Methods  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



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



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Public Constructors  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates an instance of a Java file.

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

   @param
      pPathName is the name of the file to interpret as a Java source code text file.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public <Type> JavaFileV4(Type pPathname) throws Exception
      {
      super(pPathname);
      initializeInstanceConstantsAndVariables();
      }



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Public Instance Methods  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method preprocesses a Java file.

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public void preprocess() throws Exception
      {
      /*.
      ==========================================================================================
      This method makes no sense on directory files, this must be a normal file
      ------------------------------------------------------------------------------------------ */
      if (this.isDirectory()) return;
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
      detabAndTrim();
      replicateDescriptionAndUsageText();
      bookmarkMethods();
      }



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

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

   @return
      A reference to this object

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

   @return
      A reference to this object
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public JavaFileV4 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;
      }



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Public Class Methods  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Main  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



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

   <P><B>Implementation: </B><A HREF="JavaFileV4.java.html#010">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);
      /*.
      ==========================================================================================
      Create an object and send its output to the ConsoleStream
      ------------------------------------------------------------------------------------------ */
      JavaFileV4  obj = new JavaFileV4(pArgs[0]);
      /*.
      ==========================================================================================
      Test code
      ------------------------------------------------------------------------------------------ */
      obj.test();
      obj.preprocess();
      }



   }  // class JavaFileV4



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